Оновлення (створення) карти клієнта

URI: /api/v1/promotion/customer

Метод використовується для створення або оновлення дисконтної картки покупця.

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

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

Пошук анкети виконується окремо за двома полями:

• phone
• discount_card_number

Алгоритм обробки запиту:

• Збіг за обома параметрами (phone і discount_card_number)

Якщо phone та discount_card_number знаходяться в одній анкеті, оновлюються всі поля, передані у тілі запиту.

• Збіг за різними анкетами

Якщо phone та discount_card_number знаходяться в різних анкетах, видається помилка.

• Збіг тільки за phone

Якщо discount_card_number не знайдено, оновлюються всі дані карти, де знайдено phone. Бонуси на рахунку клієнта залишаються без змін.

• Збіг тільки за discount_card_number

Якщо phone не знайдено, оновлюються всі дані карти, де знайдено discount_card_number. Бонуси на рахунку клієнта залишаються без змін.

• Відсутність збігів за обома параметрами

Якщо phone та discount_card_number не знайдено, створюється нова анкета.

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

Ім'я	Тип	Обов'язковий	Опис
phone	string	Так	Номер телефона клієнта
last_name	string	Так	Прізвище клієнта
first_name	string	Так	Ім'я клієнта
middle_name	string	Ні	Ім'я по батькові клієнта
city_name	string	Ні	Назва населеного пункту проживання клієнта
address	string	Ні	Адреса клієнта
address_index	string	Ні	Поштовий індекс клієнта
address_flat	string	Ні	Номер квартири / будинку клієнта
email	string	Ні	Адреса електронної пошти клієнта
birthday	string	Ні	Дата народження клієнта
gender	string	Ні	Стать клієнта: m або male — чоловік f або female — жінка a або asexual — без статі 🛈 Допускається як коротке, так і повне значення
discount_card_number	string	Ні	Номер дисконтної картки клієнта
want_free_samples	boolean	Ні	Прапор згоди отримання безкоштовних зразків
contact_via_phone	boolean	Ні	Прапор згоди зв'язку через телефон
contact_via_sms	boolean	Ні	Прапор згоди зв'язку через СМС
contact_via_email	boolean	Ні	Прапор згоди зв'язку через електронну пошту
contact_via_messenger	boolean	Ні	Прапор згоди зв'язку через месенджери
agree_terms_conditions	boolean	Ні	Прапор згоди з правилами та умовами
phone_verified	boolean	Ні	Прапор підтвердження номера телефона клієнта

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

Запит: /api/v1/promotion/customer

{
        "phone": "380991234567", 
        "last_name": "Тест",
        "first_name": "Анна",
        "middle_name": "Тест",
        "city_name": "Конотоп",
        "address": "Test",
        "address_index": "22066",
        "address_flat": "12",
        "email": "[email protected]",
        "birthday": "1993-07-16",
        "gender": "f",
        "discount_card_number": null,
        "want_free_samples": true,
        "contact_via_phone": true,
        "contact_via_sms": true,
        "contact_via_email": true,
        "contact_via_messenger": true,
        "agree_terms_conditions": true,
        "phone_verified": false
    }

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

Ім'я	Тип	Опис
data	object	Дані клієнта
data.phone	string	Номер телефона клієнта
data.last_name	string	Прізвище клієнта
data.first_name	string	Ім'я клієнта
data.middle_name	string	Ім'я по батькові клієнта
data.city_name	string	Назва населеного пункту проживання клієнта
data.email	string	Адреса електронної пошти клієнта
data.birthday	string	Дата народження клієнта
data.gender	string	Стать клієнта: male — чоловік female — жінка asexual — без статі 🛈 Допускається лише повна текстова назва
data.discount_card_number	string	Номер дисконтної картки клієнта
data.want_free_samples	string	Прапор згоди отримання безкоштовних зразків
data.contact_via_phone	string	Прапор згоди зв'язку через телефон
data.contact_via_sms	string	Прапор згоди зв'язку через СМС
data.contact_via_email	string	Прапор згоди зв'язку через електронну пошту
data.contact_via_messenger	string	Прапор згоди зв'язку через месенджери
data.agree_terms_conditions	string	Прапор згоди з правилами та умовами
data.phone_verified	string	Прапор підтвердження номера телефона клієнта
data.children	array	Список з роками народження дітей клієнта
data.loyalty	string	Прапор активної програми лояльності
data.loyalty_date	string	Строк дії програми лояльності
data.bonuses	float/double	Кількість бонусів на рахунку клієнта
data.bonus_accounts	objects	Блок містить деталізацію по подарунковим бонусам клієнта
data.bonus_accounts.type	string	Тип бонусного рахунку
data.bonus_accounts.amount	float	Кількість подарункових бонусів, доступна для оплати товару з даного бонусного рахунку
data.bonus_accounts.date_from	string	Дата та час активації бонусів 🛈 Початковий час, з якого бонуси можуть бути використані
data.bonus_accounts.date_to	string	Дата та час згоряння бонусів 🛈 Кінцевий термін, після настання якого бонуси стають недійсними (неактивними) і не можуть бути списані
data.bonus_accounts.write_off_percent_from_total	float	Максимальний відсоток від загальної суми чека, який можна оплатити бонусами з цього рахунку 🛈 Значення 100 означає, що цими бонусами можна покрити всю суму покупки, якщо не встановлено інших обмежень
data.bonus_accounts.comment	string	Коментар. Передається назва подарункових бонусів
data.bonus_accounts.goods_ids	array	Список ID товарів, на які поширюються обмеження списання бонусів 🛈 Якщо масив порожній ([]), це означає, що обмежень на списання бонусів немає (бонуси можна використати для будь-якого товару)
data.locked	boolean	Статус блокування клієнтської карти: 0 — карта активна (не заблокована) 1 — карта заблокована
data.type	object	Тип карти
data.type.id	string	ID типу карти
data.type.name	string	Назва типу карти
data.address	string	Адреса клієнта
data.address_post_code	string	Поштовий індекс клієнта
data.address_flat	string	Номер квартири/будинку клієнта
data.children	array	Список з роками народження дітей клієнта
data.loyalty	boolean	Прапор активної програми лояльності
data.loyalty_date	string	Строк дії програми лояльності

Приклад відповіді

Відповідь: /api/v1/promotion/customer

{
  "data": {
    "phone": "380991234567",
    "last_name": "Тест",
    "first_name": "Анна",
    "middle_name": "Тест",
    "city_name": "Конотоп",
    "email": "[email protected]",
    "birthday": "16.07.1993",
    "gender": "female",
    "discount_card_number": "3809998080340",
    "want_free_samples": 1,
    "contact_via_phone": 1,
    "contact_via_sms": 1,
    "contact_via_email": 1,
    "contact_via_messenger": 1,
    "agree_terms_conditions": 1,
    "phone_verified": 0,
    "bonuses": 0,
    "bonus_accounts": [
            {
                "type": "gift",
                "amount": 1.49,
                "date_from": "2025-09-18 00:00:00",
                "date_to": "2026-09-17 00:00:00",
                "write_off_percent_from_total": 100,
                "comment": "ТЕСТ Деталізація подарункових бонусів 3",
                "goods_ids": []
            },
            {
                "type": "gift",
                "amount": 6.98,
                "date_from": "2025-09-18 00:00:00",
                "date_to": "2026-09-17 00:00:00",
                "write_off_percent_from_total": 100,
                "comment": "ТЕСТ Деталізація подарункових бонусів 3",
                "goods_ids": []
            }
        ],
    "locked": 1,
    "type": {
      "id": null,
      "name": null
    },
    "address": null,
    "address_post_code": null,
    "address_flat": null,
    "children": [],
    "loyalty": false,
    "loyalty_date": null
  }
}

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

Відповідь: 400 Bad Request

{
   "message": "A card with this phone number and card number already exist separately"
}