Перейти до основного вмісту

Отримання чека з доступними акціями (з операціями списання і нарахування)​

URI: /api/v1/promotion/analyze-after-sell

Метод використовується для отримання чека з доступними акціями, з виконанням операцій списання та нарахування бонусів.

Запит виконується методом POST у json форматі з даними.

⚠️ Запит повинен містити заголовок Accept: application/json

Параметри запиту​

Ім'яТипОбов'язковийОпис
drugstore_idstringТакІдентифікатор аптеки (з бази даних аптеки)
cash_register_numberstringТакІдентифікатор каси
pharmacist_idstringТакІдентифікатор фармацевта
documentarrayТакДані чека
document.idstringТакУнікальний ідентифікатор (GUID) документу (чек)
⚠️ GUID повинен бути ідентичним document.id в запиті analyze_before_sell
document.numberstringТакВнутрішній номер чека
document.fiscal_numberstringТакФіскальний номер чека
document.datedateТакДата і час формування чека, в форматі Y-m-d H:i
Формат часу - 24 години
document.amount_of_cashfloat | nullНіГотівка, яку дав покупець
document.amount_of_change_to_bonusfloat | nullНіКількість решти яку перевести в бонус
document.contentarrayТакТовари в чеку
document.content.*.idstringТакУнікальний ідентифікатор (GUID) позиції в чеку
document.content.*.goods_idstringТакІдентифікатор товару
document.content.*.quantitynumericТакКількість товару в чеку
document.content.*.price_buynumericТакЗакупівельна вартість
document.content.*.price_retailnumericТакРоздрібна вартість
document.content.*.activebooleanНіПараметр товару в чеку
true - нараховувати бонуси і знижки
false - не нараховувати бонуси і знижки
customerarray | nullНіДані покупця
customer.phonestring | nullНіНомер телефона покупця
customer.card_numberstring | nullНіНомер бонусної карти покупця
customer.confirmation_codestring |nullНіКод підтвердження списання бонусних балів
customer.amount_of_bonuses_to_write_offnumeric | nullНіКількість бонусів для списання
channelstring | nullНіКанал продажу:
  • insurance
  • call_center
  • online
  • offline
  • insulin
  • reimbursement
  • hesed
sourcestring | nullНіТорговий майданчик:
  • bond
  • glovo
  • telegram
  • zdorovi
  • own
  • *
  • atb
  • liki
  • viber
  • helsi
  • optimapharm
  • aptekaskarb
  • tabletki
  • geoapteka
  • liki24
promocodestringНіПромокод (для спрацювання акцій які діють за промокодом)
увага
  • Кожен клієнт (аптека) підтверджує списання бонусів тільки якщо сума списання більше певної суми X. Для списання бонусів, сума яких більше X, необхідно передати параметр amount_of_bonuses_to_write_off та confirmation_code
  • Якщо сума списання менше X, то запитувати код підтвердження не потрібно і достатньо передати параметр amount_of_bonuses_to_write_off
  • Кожна мережа аптек встановлює індивідуальне значення суми X (ліміт списання без підтвердження). Налаштувати максимальну суму до списання бонусів без коду підтвердження можна на сторінці Параметри.

Приклад запиту​

Запит: /api/v1/promotion/analyze-after-sell
{
    "drugstore_id": "969",
    "cash_register_number": "7890",
    "pharmacist.id": "000001",
    "customer": {
        "phone": "380997654321",
        "card_number": "969000000013",
        "confirmation_code": "199928",
        "amount_of_bonuses_to_write_off": 11
    },
    "document": {
        "id": "f2a28abd-34d3-4ea1-9153-5beb50cd56ca",
        "number": "1234",
        "fiscal_number": "86960",
        "date": "2023-03-30 23:20",
        "document.amount_of_cash": 205,
        "document.amount_of_change_to_bonus": 0.5,
        "content": [
            {
                "id": "f2a28abd-34d3-4ea1-9153-5beb50cd56ca",
                "goods_id": "1057426",
                "quantity": 5.5,
                "price_buy": 15.75,
                "price_retail": 22.5,
         "active":true
         }
      ]
   },
   "channel": "offline",
   "source": null,
   "promocode": "PROMO123"
}
інформація

Алгоритм відправки запитів із обробкою помилок та повторними спробами знаходиться за посиланням

Параметри відповіді​

Ім'яТипОпис
documentobjectПараметри чека
document.idstringУнікальний ідентифікатор (GUID) документу (чек)
document.numberstringВнутрішній номер чека
document.datestringДата і час формування чека
document.bonus_to_write_offfloatКількість бонусів для списання
document.bonus_to_write_off_max_amountfloatКількість бонусів доступна до списання в поточному стані документу
document.bonus_to_accrue_from_changefloatКількість решти яку переведено в бонус
document.amount_of_cashfloatГотівка, яку дав покупець
document.amount_of_changefloatРешта, яку треба дати покупцю
document.promocodestring / nullЗначення введеного промокоду (для спрацювання акцій які діють за промокодом)/
🛈 Якщо не введено — null
document.promocode_appliedbooleanПідсумковий статус застосування промокоду для всього чека. У документі набуває значення:
  • true – якщо промокод був успішно застосований хоча б до одного товару у списку content
  • false – лише у випадку, коли умови промокоду не були виконані для жодного товару в документі (всі позиції у списку content мають статус false)
🛈 Наприклад, якщо в кошику 3 товари, і промокод дав знижку лише на один із них, то в цьому товарі буде true, у двох інших — false, а в загальному полі документа — true
document.contentlist[object]Товари в чеку
document.content.idstringУнікальний ідентифікатор (GUID) позиції в чеку
document.content.goods_idstringІдентифікатор товару
document.content.quantityfloatКількість товару в чеку
document.content.price_buyfloatЗакупівельна вартість
document.content.price_retailfloatРоздрібна вартість
document.content.price_newfloatЦіна товару з урахуванням знижок. Якщо немає ніяких знижок - дублюється роздрібна ціна. Якщо є знижка - ціна з урахуванням знижки або фіксована ціна на товар
document.content.discountfloatСума або відсоток знижки
document.content.bonusfloatКількість отриманих бонусів за покупку
document.content.actionstringВідображає тип зміни по позиції чеку.
Якщо позиція була продубльована, значення буде insert.
В інших випадках використовується update
document.content.priority_maxintegerПріоритет акції, яка спрацювала на дану позицію товару в чеку
document.content.promotion_idsarrayІдентифікатор акції, яка застосована для даної позиції товару в чеку
document.content.promocode_appliedbooleanОзнака застосування промокоду: приймає значення true, якщо промокод був успішно застосований до даної позиції товару
promotionobjectПараметри акції
promotion.namestringНазва акції
promotion.date_fromstringДата з якої діє акція
promotion.date_tostringДата до якої діє акція
promotion.typeobjectТип акції
promotion.type.namestringНазва типу акції
promotion.type.descriptionstringОпис типу акції
promotion.parametersobjectПараметри знижки
promotion.parameters.bonus_percentobjectПараметри бонуса у % від роздрібної ціни
promotion.parameters.bonus_percent.namestringНазва параметра бонуса
promotion.parameters.bonus_percent.descriptionstringОпис параметра бонуса
promotion.parameters.bonus_percent.valuefloatЗначення параметра бонуса
pharmacistobjectПараметри фармацевта
pharmacist.idstringІдентифікатор фармацевта
pharmacist.full_namestringПовне ім'я фармацевта
pharmacist.emailstringЕлектронна пошта фармацевта
pharmacist.phonestringНомер телефона фармацевта
customerobjectПараметри покупця
customer.customerobjectПараметри покупця
customer.customer.first_namestringІм'я покупця
customer.customer.last_namestringПрізвище покупця
customer.customer.middle_namestringПо-батькові покупця
customer.customer.emailstringЕлектронна пошта покупця
customer.customer.citystringМісто проживання покупця
customer.customer.phonestringНомер телефона покупця
customer.customer.card_numberstringНомер бонусної карти покупця
customer.customer.birthdaystringДата народження покупця
customer.customer.bonusesfloatКількість бонусів на рахунку покупця
customer.customer.typeobjectТип карти
customer.customer.type.idstringID типу карти
customer.customer.type.namestringНазва типу карти
customer.bonus_accountsobjectsБлок містить деталізацію по подарунковим бонусам клієнта
customer.bonus_accounts.typestringТип бонусного рахунку
customer.bonus_accounts.amountfloatКількість подарункових бонусів, доступна для оплати товару з даного бонусного рахунку
customer.bonus_accounts.date_fromstringДата та час активації бонусів
🛈 Початковий час, з якого бонуси можуть бути використані
customer.bonus_accounts.date_tostringДата та час згоряння бонусів
🛈 Кінцевий термін, після настання якого бонуси стають недійсними (неактивними) і не можуть бути списані
customer.bonus_accounts.write_off_percent_from_totalfloatМаксимальний відсоток від загальної суми чека, який можна оплатити бонусами з цього рахунку
🛈 Значення 100 означає, що цими бонусами можна покрити всю суму покупки, якщо не встановлено інших обмежень
customer.bonus_accounts.commentstringКоментар. Передається назва подарункових бонусів
customer.bonus_accounts.goods_idsarrayСписок ID товарів, на які поширюються обмеження списання бонусів
  • Якщо масив порожній ([]), це означає, що обмежень на списання бонусів немає (бонуси можна використати для будь-якого товару)
  • Якщо вказані ID, то бонуси з цього рахунку можна списати лише на ці товари
messagestringПовідомлення про результат списання / нарахування бонусів
codeintegerКод відповіді від сервера

Приклад успішної відповіді​

200 OK

Відповідь: /api/v1/promotion/analyze-after-sell
{
    "data": {
        "document": {
            "id": "43a3bf87-0e4e-11f1-82dd-107b4448c38c",
            "number": "096-000007995",
            "date": "2026-02-20 13:21",
            "total": 326.7,
            "total_initial": 326.7,
            "bonus_to_write_off": 0,
            "bonus_to_accrue": 0,
            "bonus_to_accrue_from_change": 0,
            "amount_of_cash": 0,
            "amount_of_change": 0,
            "bonus_to_write_off_max_amount": 4.53,
            "promocode": "PROMO123",
            "promocode_applied": false,
            "content": [
                {
                    "id": "814c0006-0349-11f1-8cb9-00505693efdb",
                    "goods_id": "UT-00032031",
                    "price_buy": 302.53,
                    "price_retail": 326.7,
                    "price_new": 326.7,
                    "quantity": 1,
                    "discount": null,
                    "bonus": null,
                    "action": "update",
                    "priority_max": 30,
                    "promotion_ids": [
                        "6f82fbd7-a119-40a2-b60a-65f1cc677836"
                    ],
                    "promocode_applied": false
                }
            ]
        },
        "pharmacist": {
            "id": "00000000184",
            "full_name": "Пінязенко Ірина Леонтіївна",
            "email": "[email protected]",
            "phone": "380675575639"
        },
        "promotion": [
            {
                "id": "6f82fbd7-a119-40a2-b60a-65f1cc677836",
                "name": "2 - Універсальна Гаевского FARMACIA",
                "created_at": "2025-02-14 15:45:23",
                "date_from": "2025-02-14",
                "date_to": "2050-02-14",
                "type": {
                    "name": "Бонус",
                    "description": "Бонус при купівлі SKU у торговій точці в грн або %"
                },
                "parameters": [
                    {
                        "name": "bonus_value",
                        "description": "Розмір бонусу",
                        "value": 3
                    },
                    {
                        "name": "bonus_type",
                        "description": "Метод розрахунку бонусу ",
                        "value": "%"
                    },
                    {
                        "name": "enable_markup_percent_min",
                        "description": "Задіяти мінімальний відсоток націнки",
                        "value": true
                    }
                ]
            },
            {
                "id": "f2220475-18b4-4fcc-828a-a286d12c0a15",
                "name": "2.1 - Універсальна Гаевского FARMACIA(нові клієнти)",
                "created_at": "2025-02-20 15:56:26",
                "date_from": "2025-02-20",
                "date_to": "2050-02-20",
                "type": {
                    "name": "Бонус",
                    "description": "Бонус при купівлі SKU у торговій точці в грн або %"
                },
                "parameters": [
                    {
                        "name": "bonus_type",
                        "description": "Метод розрахунку бонусу ",
                        "value": "%"
                    },
                    {
                        "name": "enable_markup_percent_min",
                        "description": "Задіяти мінімальний відсоток націнки",
                        "value": true
                    },
                    {
                        "name": "bonus_value",
                        "description": "Розмір бонусу",
                        "value": 3
                    }
                ]
            }
        ],
        "customer": {
            "customer": {
                "first_name": "І",
                "last_name": "П",
                "middle_name": "Б",
                "email": null,
                "city": null,
                "phone": "380933741801",
                "card_number": "3809337418017",
                "birthday": null,
                "bonuses": 4.53,
                "type": {
                    "id": "ded7f987-719c-41ac-ad53-fe26ab83490d",
                    "name": "Універсальна"
                }
            },
            "bonus_accounts": [
                {
                    "type": "gift",
                    "amount": 20,
                    "date_from": "2025-09-29 00:00:00",
                    "date_to": "2025-10-06 00:00:00",
                    "write_off_percent_from_total": 100,
                    "comment": "ТЕСТ Деталізація подарункових бонусів 3",
                    "goods_ids": [
                        "UT-00030353",
                        "UT-00117645",
                        "UT-00000056",
                        "UT-00030373",
                        "UT-00030389",
                        "UT-00030374",
                        "UT-00030357",
                        "UT-00030348",
                        "00-00025964",
                        "00-00003149"
                    ]
                },
                {
                    "type": "gift",
                    "amount": 12,
                    "date_from": "2025-09-29 00:00:00",
                    "date_to": "2025-10-06 00:00:00",
                    "write_off_percent_from_total": 100,
                    "comment": "ТЕСТ Деталізація подарункових бонусів 3",
                    "goods_ids": [
                        "UT-00034001",
                        "UT-00034003",
                        "UT-00034002"
                    ]
                }
            ]
        }
    }
}

Приклади неуспішних відповідей​

Код підтвердження для списання бонусів не існує​

Відповідь: 400 Bad Request
{
    "message": "Код підтвердження для списання бонусів не існує" 
}

Термін дії коду підтвердження для списання бонусів завершений​

Відповідь: 400 Bad Request
{
    "message": "Термін дії коду підтвердження для списання бонусів завершений" 
}

Кількість бонусів до списання не відповідає заявленій​

Відповідь: 400 Bad Request
{
    "message": "Кількість бонусів до списання не відповідає заявленій"   
}

Необхідний код підтвердження списання бонусів, можна списати без підтвердження до X бонусів​

Відповідь: 400 Bad Request
{
    "message": "Необхідний код підтвердження списання бонусів, можна списати без підтвердження до X бонусів"  
}

Код підтвердження для списання бонусів вже використано​

Відповідь: 400 Bad Request
{
    "message": "Код підтвердження для списання бонусів вже використано" 
}

Недостатньо бонусів на рахунку​

Відповідь: 400 Bad Request
{
    "message": "Недостатньо бонусів на рахунку"  
}

Для даного чеку немає активних акцій​

Відповідь: 400 Bad Request
{
    "message": "Для даного чеку немає активних акцій"  
}

Подарункового сертифікату не існує​

Відповідь: 400 Bad Request
{
    "message": "Подарункового сертифікату не існує" 
}

Подарунковий сертифікат використаний​

Відповідь: 400 Bad Request
{
    "message": "Подарунковий сертифікат використаний"  
}

Подарунковий сертифікат не активний​

Відповідь: 400 Bad Request
{
    "message": "Подарунковий сертифікат не активний" 
}

За даним каналом продажу бонус не може бути списаний​

Відповідь: 400 Bad Request
{
    "message": "За даним каналом продажу бонус не може бути списаний" 
}

Недостатньо готівки для цього документа, готівка повинна бути не менше ніж:​

Відповідь: 400 Bad Request
{
    "message": "Недостатньо готівки для цього документа, готівка повинна бути не менше ніж:"  
}

Сума решти, конвертована в бонус, перевищує суму решти​

Відповідь: 400 Bad Request
{
    "message": "Сума решти, конвертована в бонус, перевищує суму решти"  
}

Сума готівки не вказана​

Відповідь: 400 Bad Request
{
    "message": "Сума готівки не вказана" 
}

Внутрішня помилка в системі аналізу документів​

Відповідь: 500
{
    "message": "Внутрішня помилка в системі аналізу документів" 
}

Помилка сервера​

Відповідь: 500
{
    "message": "Помилка сервера" 
}

Карта заблокована​

Відповідь: 500
{
    "message": " The card is locked"
}