Интеграция Common Provider и Barsy

Common Provider е универсален адаптер в Barsy, чрез който може да се интегрира произволна система за управление на начисления — хотелски PMS, клубна система, лоялти платформа или подобна.

При приключване на сметка Barsy извиква API на насрещната система, за да начисли консумацията към съответна сметка, стая или профил. При избор на ред от списъка Barsy може автоматично да зареди клиент и да приложи отстъпка. На касовата бележка се отпечатва избраният идентификатор и поле за подпис.

Насрещната система трябва да имплементира два HTTP endpoint-а: search_list и add_charge.

Note

Тази страница е предназначена за разработчиците на насрещната система. За настройване на Barsy вижте подстраниците по-долу.

Автентикация

Всички заявки от Barsy използват HTTP Digest автентикация (RFC 7616). Насрещният сървър трябва да изиска Digest автентикация и да валидира credentials-ите, конфигурирани в настройките на Barsy в полетата Api Username и Api Password.

Конструиране на URL

Barsy конструира URL-ите като добавя пътя на endpoint-а след Api URL (trailing slash се премахва автоматично):

Api URL (конфигурация)	Резултат за search_list
`https://example.com/api`	`https://example.com/api/search_list?query=...`
`https://example.com/api/`	`https://example.com/api/search_list?query=...`

Search List

Извиква се когато потребителят въвежда стойност за търсене в диалога за приключване на сметка.

Important

Настройката Източник на списък с данни (Допълнителна информация при използване → Източник на списък с данни) трябва да е От външна система. Без тази настройка Barsy няма да извика search_list.

Заявка:

Параметърът query съдържа въведения текст (URL encoded).

GET {api_url}/search_list?query={стойност}

Успешен отговор (HTTP 200):

{
  "results": [
    {
      "value_id": "ACC-001",
      "value_name": "Стая 101",
      "client_id": 42,
      "client_name": "Иван Иванов",
      "discount": 10,
      "available_amount": 250.00
    },
    {
      "value_id": "ACC-002",
      "value_name": "Стая 202",
      "client_id": 15
    },
    {
      "value_id": "ACC-003",
      "value_name": "Конферентна зала А",
      "client_name": "Мария Петрова"
    },
    {
      "value_id": "ACC-004",
      "value_name": "Отворена сметка бар"
    }
  ]
}

Ако results е празен масив или липсва, Barsy показва съобщение „Няма открити резултати“.

Свойства на обектите в results:

Поле	Тип	Задължително	Описание
`value_id`	string	да	Уникален идентификатор на записа. Изпраща се при начисляване (add_charge) и се отпечатва на касовата бележка.
`value_name`	string	да	Четимо описание на записа. Показва се в списъка с резултати в POS интерфейса.
`client_id`	int	не	ID на клиент в Barsy. Ако е подадено, Barsy зарежда автоматично съответния клиент при избор на реда.
`client_name`	string	не	Ако няма client_id, Barsy търси клиент по точно съвпадение с името. Ако не го намери, продължава без клиент.
`discount`	float	не	Отстъпка в проценти като положително число (напр. 10 за 10%). Надписва отстъпката на клиента в Barsy.
`available_amount`	float	не	Налична сума по сметката (напр. остатъчен бюджет, лимит, баланс по стая). Показва се на касиера до бутона на начина на плащане като „Наличност“.

Поведение при избор на ред от списъка:

Ако има client_id — Barsy зарежда клиента по ID. Ако стойността не съответства на съществуващ клиент в Barsy, тя се пренебрегва тихо. Ако в сметката вече има избран клиент (не анонимен), новата стойност не презаписва текущата.
Ако няма client_id, но има client_name — Barsy търси по точно съвпадение с името. При неуспех — продължава без клиент.
Ако има клиент и discount — надписва отстъпката на заредения клиент. Без клиент отстъпката се пренебрегва.
Ако няма нито клиент, нито отстъпка — клиентът се нулира (анонимен) и отстъпката става 0.

Отговор при грешка:

Вижте раздел Обработка на грешки.

Add Charge

Извиква се при финализиране на плащане. Записва начислението към съответната сметка/стая/профил в насрещната система.

Полето total присъства задължително при всички режими на групиране — съдържа крайния тотал на сметката с всички отстъпки. Полето account_id е номерът на сметката в Barsy и се изпраща за обратна референция. Всички цени са с включено ДДС (брутни) и след прилагане на всички отстъпки (на ниво ред и на ниво сметка).

Форматът на тялото зависи от настройката Групиране в Barsy (вижте раздел Режими на групиране).

Заявка:

POST {api_url}/add_charge
Content-Type: application/json

Само тотал (без детайли по артикули):

{
  "value_id": "ACC-001",
  "account_id": 5,
  "total": 33.70,
  "currency": "EUR",
  "service_date": "2025-11-07 14:30:00"
}

С разбивка по ДДС група (Групиране = По ДДС група, по подразбиране):

{
  "value_id": "ACC-001",
  "account_id": 5,
  "total": 33.70,
  "currency": "EUR",
  "service_date": "2025-11-07 14:30:00",
  "groups": [
    {
      "group_name": "Артикули с ДДС 20% по сметка 5",
      "price": 25.600,
      "tax_rate": 20
    },
    {
      "group_name": "Артикули с ДДС 9% по сметка 5",
      "price": 8.100,
      "tax_rate": 9
    }
  ]
}

С разбивка по артикул (Групиране = По ред):

{
  "value_id": "ACC-001",
  "account_id": 5,
  "total": 8.80,
  "currency": "EUR",
  "service_date": "2025-11-07 14:30:00",
  "orders": [
    {
      "article_id": 101,
      "article_name": "Кафе",
      "price": 3.500,
      "quantity": 2,
      "tax_rate": 20
    },
    {
      "article_id": 205,
      "article_name": "Минерална вода",
      "price": 1.800,
      "quantity": 1,
      "tax_rate": 20
    }
  ]
}

Поле	Тип	Описание
`value_id`	string	Идентификаторът, избран от search_list
`account_id`	int	Номер на сметката в Barsy (за обратна референция)
`total`	float	Краен тотал с всички отстъпки (с ДДС), закръглен до 2 знака. Присъства при всички режими.
`currency`	string	Валутен код (ISO 4217, напр. EUR, BGN)
`service_date`	string	Дата и час на отваряне на сметката в Barsy, формат YYYY-MM-DD HH:MM:SS
`groups`	array	При разбивка по ДДС група — масив от групи, по една за всяка различна ДДС ставка
`groups[].group_name`	string	Описание на групата (генерирано от Barsy)
`groups[].price`	float	Обща сума за групата с всички отстъпки (с ДДС), закръглена до 3 знака
`groups[].tax_rate`	float	ДДС ставка в проценти (напр. 20, 9, 0)
`orders`	array	При разбивка по артикул — масив от редове, по един за всеки артикул
`orders[].article_id`	int	ID на артикула в Barsy
`orders[].article_name`	string	Име на артикула
`orders[].price`	float	Единична цена след всички отстъпки (с ДДС), закръглена до 3 знака
`orders[].quantity`	float	Количество
`orders[].tax_rate`	float	ДДС ставка в проценти

Успешен отговор (HTTP 200):

{
  "charge_id": "CHG-A1B2C3D4"
}

Поле	Тип	Задължително	Описание
`charge_id`	string	да	Уникален идентификатор на начислението. Barsy го записва като transaction ID и може да се използва за справки.

Important

Ако отговорът не съдържа charge_id (или стойността е празна/null), Barsy третира операцията като неуспешна и показва грешка на потребителя.

Отговор при грешка:

Вижте раздел Обработка на грешки.

Режими на групиране

Настройката Групиране в Barsy определя формата на данните в add_charge. Конфигурира се от оператора и не се предава динамично.

Режим	Описание
По ред	Изпраща по един запис за всеки артикул в сметката. Подходящо за системи с детайлна отчетност по артикул.
По ДДС група (по подразбиране)	Изпраща по един запис за всяка ДДС ставка в сметката. Подходящо за системи с отчетност по ДДС групи.
Само тотал	Изпраща само total — крайната сума без детайли. Подходящо за системи, на които не са нужни разбивки по артикули.

Обработка на грешки

При грешка вашата система трябва да върне HTTP 4xx или 5xx с JSON тяло:

{
  "error_code": "ACCOUNT_CLOSED",
  "message": "Четимо съобщение за грешката"
}

Поле	Тип	Задължително	Описание
`message`	string	да	Съобщение за грешката, разбираемо за крайния потребител. Barsy го показва директно на екрана.
`error_code`	string	не	Машинно-четим код на грешката за лесно разпознаване в насрещната система. Не се показва на потребителя.

HTTP статус	Поведение на Barsy
4xx с поле message	Показва стойността директно на потребителя
4xx без поле message	Показва общо съобщение за грешка
5xx (всякакъв)	Показва съобщение за недостъпност на насрещната система

Съобщенията в message следва да са написани на езика на крайния потребител (касиер/сервитьор) и да са конкретни — например „Стая 101 не приема начисления“ вместо „Грешка“.

Поток на данните

Касиер (POS)              Barsy                    Вашата система
    |                       |                             |
    | 1. Избира начин на    |                             |
    |    плащане            |                             |
    |                       |                             |
    | 2. Въвежда стойност   |                             |
    |    за търсене         |                             |
    |---------------------->|                             |
    |                       | 3. GET search_list?query=.. |
    |                       |---------------------------->|
    |                       |                             |
    |                       | 4. { "results": [...] }     |
    |                       |<----------------------------|
    |                       |                             |
    | 5. Вижда списъка      |                             |
    |<----------------------|                             |
    |                       |                             |
    | 6. Избира ред         |                             |
    |    (зарежда клиент    |                             |
    |     и отстъпка)       |                             |
    |                       |                             |
    | 7. Потвърждава        |                             |
    |---------------------->|                             |
    |                       | 8. POST add_charge          |
    |                       |    { value_id, account_id,  |
    |                       |      total, ... }           |
    |                       |---------------------------->|
    |                       |                             |
    |                       | 9. { "charge_id": "..." }   |
    |                       |<----------------------------|
    |                       |                             |
    | 10. Плащането е       |                             |
    |     записано.         |                             |
    |     Печат на бележка  |                             |
    |     (value_id)        |                             |
    |<----------------------|                             |

Пълен пример

Хотелски PMS — настройки в Barsy:

Настройка	Стойност
Име на системата	`Hotel PMS`
Api URL	`https://pms.example.com/api/v1`
Api Username	`barsy_user`
Api Password	`s3cret_p@ss`
Групиране	По ДДС група
Източник на списък с данни	От външна система

Заявка search_list:

GET https://pms.example.com/api/v1/search_list?query=101
Authorization: Digest username="barsy_user", ...

Отговор:

{
  "results": [
    {
      "value_id": "FOLIO-8842",
      "value_name": "Стая 101 - Иван Петров (до 15.11)",
      "client_id": 42,
      "discount": 15
    },
    {
      "value_id": "FOLIO-8901",
      "value_name": "Стая 1012 - Групова резервация",
      "client_name": "Корп. клиент ООД"
    }
  ]
}

Заявка add_charge (при групиране по ДДС група):

POST https://pms.example.com/api/v1/add_charge
Authorization: Digest username="barsy_user", ...
Content-Type: application/json

{
  "value_id": "FOLIO-8842",
  "account_id": 5,
  "total": 54.65,
  "currency": "EUR",
  "service_date": "2025-11-07 14:30:00",
  "groups": [
    {
      "group_name": "Артикули с ДДС 20% по сметка 5",
      "price": 42.500,
      "tax_rate": 20
    },
    {
      "group_name": "Артикули с ДДС 9% по сметка 5",
      "price": 12.150,
      "tax_rate": 9
    }
  ]
}

Отговор:

{
  "charge_id": "PMS-TXN-20251107-001"
}

При грешка:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error_code": "ACCOUNT_CHECKED_OUT",
  "message": "Стая 101 е checkout-ната. Моля, изберете активна стая."
}

Чеклист за имплементация

Endpoint-и

GET /search_list?query=… — приема query параметър, връща JSON с results
POST /add_charge — приема JSON body, връща JSON с charge_id

Автентикация

HTTP Digest автентикация е конфигурирана и работи
Невалидни credentials връщат 401 Unauthorized

Search List

Отговорът съдържа масив results (дори празен)
Всеки резултат има задължителните полета value_id и value_name
value_id е уникален идентификатор (ще се използва в add_charge)
client_id (ако се подава) съответства на реален клиент в Barsy
discount е положително число (напр. 10, а не -10)
available_amount (ако се подава) представлява налична сума по сметката

Add Charge

Поддържа се само тотал (без детайли по артикули)
Поддържа се разбивка по ДДС група, ако е необходимо
Поддържа се разбивка по артикул, ако е необходимо
Отговорът съдържа непразен charge_id
charge_id е уникален за всяко начисление

Обработка на грешки

Грешките връщат HTTP 4xx/5xx
Тялото съдържа JSON с поле message
Съобщенията са разбираеми за крайния потребител
Опционално: добавен error_code за машинно разпознаване на грешки

Общи

Content-Type на отговорите е application/json
Кодировка UTF-8
HTTPS е препоръчителен (credentials се предават при всяка заявка)