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

Описание основных сущностей 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 содержит баланс и историю взаимодействий клиента с филиалом