Сущности системы#

Описание основных сущностей API Sagi, их полей и назначения.

Order (Заказ)#

Основная сущность транзакции в системе, содержащая всю информацию о покупке, начисленных/списанных бонусах и статусе.

Основные поля:

  • id (int64) - Уникальный идентификатор заказа

  • order_number (int64) - Номер заказа для отображения клиенту

  • type (string) - Тип заказа («direct», «qr», «online», «auto»)

  • sender (OrderSender) - Информация о клиенте, совершившем заказ

  • recipient (RecipientBranch) - Информация о филиале, принявшем заказ

  • created_at (int64) - Время создания заказа (timestamp)

  • paid_at (int64) - Время оплаты заказа (timestamp)

  • updated_at (int64) - Время последнего обновления (timestamp)

  • status (string) - Статус заказа («CREATED», «COMPLETED», «DECLINED»)

Финансовые поля:

  • initial_order_total_amount (float64) - Изначальная сумма заказа

  • order_total_amount (float64) - Итоговая сумма заказа

  • order_cashback_amount (float64) - Сумма начисленного кешбека

  • paid_from_card (float64) - Оплачено картой

  • paid_from_balance (float64) - Оплачено из общего баланса

  • paid_from_private_balance (float64) - Оплачено из приватного баланса (бонусы филиала)

  • paid_from_cash (float64) - Оплачено наличными

Дополнительные поля:

  • comment (string) - Комментарий к заказу

  • payment_method (string) - Способ оплаты («cash», «card», «online», «mixed»)

  • award (OrderAwardItem) - Информация о выданной награде

  • private_order (bool) - Является ли заказ приватным (в рамках филиала)

  • refunds ([]OrderRefund) - Массив возвратов по заказу

  • error (OrderError) - Информация об ошибке (если статус DECLINED)

UserAward (Награда пользователя)#

Сущность, представляющая информацию о программе наград и накопленных штампах клиента.

Основные поля:

  • id (ObjectID) - Уникальный идентификатор записи награды

  • title (string) - Название награды (например, «Бесплатный кофе»)

  • description (string) - Описание условий получения награды

  • stamp_count (int) - Требуемое количество штампов для получения награды

  • received_stamp_count (int) - Текущее накопленное количество штампов

Временные поля:

  • created_at (int64) - Время создания записи (timestamp)

  • activated_at (int64) - Время активации программы наград (timestamp)

  • expired_at (int64) - Время истечения программы наград (timestamp)

  • updated_at (int64) - Время последнего обновления (timestamp)

Связанные сущности:

  • branch (RecipientBranch) - Филиал, в котором действует программа наград

  • recipient (OrderSender) - Клиент, участвующий в программе

Статистика:

  • total (int) - Количество раз, когда клиент получал эту награду

  • is_active (bool) - Активна ли программа наград

User (Пользователь)#

Сущность клиента системы с персональной информацией и связями с филиалами.

Персональные данные:

  • id (int64) - Уникальный идентификатор пользователя

  • phone (string) - Номер телефона (основной идентификатор)

  • first_name (string) - Имя

  • last_name (string) - Фамилия

  • avatar (string) - URL аватара пользователя

  • birthday (time.Time) - Дата рождения

  • birthday_json (string) - Дата рождения в формате DD-MM-YYYY

Статус и безопасность:

  • is_blocked (bool) - Заблокирован ли пользователь

  • blocked_reason (string) - Причина блокировки

  • created_at (int64) - Время регистрации (timestamp)

  • updated_at (int64) - Время последнего обновления (timestamp)

Связи с филиалами:

  • private_branches ([]PrivateBranch) - Массив филиалов, в которых клиент участвует в программе лояльности

PrivateBranch (Частный филиал)#

Сущность, представляющая отношения клиента с конкретным филиалом, включая баланс, ограничения и настройки.

Идентификаторы:

  • branch_id (int64) - Уникальный ID филиала

  • group_id (int64) - ID группы филиалов (одинаковый для всех филиалов бизнеса)

Баланс и лимиты:

  • balance (float64) - Текущий баланс бонусов в этом филиале

  • daily_tx_count (int64) - Количество транзакций сегодня

  • daily_tx_limit (int64) - Дневной лимит транзакций

  • spend_amount (float64) - Общая сумма покупок в филиале

Проценты и бонусы:

  • cash_back_percent (float64) - Текущий процент кешбека

  • increased_cashback_percent (float64) - Повышенный процент кешбека

  • usage_bonus_percentage (float64) - Процент использования бонусов

  • birthday_bonus (PrivateBranchBirthdayBonus) - Настройки birthday bonus

Временные метки:

  • expired_at (int64) - Время истечения отношений с филиалом

  • updated_at (int64) - Время последнего обновления

  • last_uploaded_notification (int64) - Время последнего уведомления

  • first_transaction_date_after_notification (int64) - Первая транзакция после уведомления

Статус:

  • is_client (bool) - Является ли активным клиентом филиала

  • come_from (BonusComeFrom) - Информация о том, откуда пришел клиент

Дополнительные поля:

  • certificates ([]UserCertificate) - Сертификаты клиента в филиале

  • delay_bonuses ([]DelayBonus) - Отложенные бонусы

  • tags (Tags) - Теги клиента в филиале

  • wallet (PrivateBranchWallet) - Кошелек клиента

Legacy поля (устаревшие):

  • certificate_balance (int) - Баланс сертификатов (будет удален)

  • certificate_balance_expiration (int64) - Истечение баланса сертификатов

  • certificate_id (int64) - ID сертификата

RecipientBranch (Филиал-получатель)#

Информация о филиале, используемая в заказах и других операциях.

Основные поля:

  • id (int64) - Уникальный идентификатор филиала

  • name (string) - Название филиала

  • address (string) - Адрес филиала

  • phone (string) - Телефон филиала

  • group_id (int64) - ID группы филиалов

OrderSender (Отправитель заказа)#

Информация о клиенте в контексте заказа.

Поля:

  • id (int64) - ID пользователя

  • first_name (string) - Имя

  • last_name (string) - Фамилия

  • phone (string) - Телефон

  • avatar (string) - Аватар

Использование сущностей#

В API ответах#

Эндпоинты возвращают полные объекты сущностей или их части в зависимости от назначения:

  • GET /api/v1/orders/{order_id} → полный объект Order

  • GET /api/v1/branches/{branch_id}/customers/{user_id}/award → объект UserAward

  • GET /api/v1/promoters/find → объект User

  • GET /api/v1/branches/{branch_id}/customers/{user_id}/private-branch → объект PrivateBranch

В бизнес-логике#

Сущности связаны между собой:

  • Order содержит ссылки на OrderSender и RecipientBranch

  • User содержит массив PrivateBranch для каждого филиала

  • UserAward связана с конкретным RecipientBranch

  • PrivateBranch содержит баланс и историю взаимодействий клиента с филиалом

★ Insight ───────────────────────────────────── Структура сущностей отражает реальную бизнес-модель системы лояльности, где клиенты могут участвовать в программах разных филиалов одновременно, накапливать отдельные балансы и получать персонализированные условия кешбека в каждом филиале. ─────────────────────────────────────────────────