Обзор системы#

Что такое Sagi#

Sagi — это комплексная платформа лояльности для бизнеса, которая позволяет интегрировать бонусную программу непосредственно в кассовые системы и POS терминалы.

Система объединяет:

  • Мобильное приложение для клиентов (iOS/Android)

  • Веб-платформу для управления бизнесом

  • REST API для интеграции с кассовыми системами

  • Административную панель для настройки программ лояльности

Архитектура интеграции#

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   POS Terminal  │◄──►│   Sagi API      │◄──►│ Mobile App      │
│   (Ваша касса)  │    │ (docs.sagi.kz)  │    │ (Клиенты)       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Receipt       │    │   MongoDB       │    │   Push          │
│   Printer       │    │   Database      │    │   Notifications │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Среды разработки#

Production (Продакшен)#

  • URL: https://gateway.sagi.kz

  • Назначение: Рабочая среда для живых транзакций

  • SLA: 99.9% uptime, < 2сек время ответа

  • Поддержка: 24/7

Sandbox (Тестовая среда)#

  • URL: https://test.sagi.kz

  • Назначение: Тестирование и разработка интеграции

  • Данные: Тестовые пользователи и транзакции

  • Ограничения: Без реальных SMS и push-уведомлений

  • Подсказка: Тестовый код везде - 1111

Основные сущности#

Клиенты (Users)#

  • Регистрация по номеру телефона (+77XXXXXXXXX)

  • Персональная информация (имя, дата рождения)

  • Статус в конкретном филиале (новый/постоянный клиент)

Бонусы (Private Balance)#

  • Персональный баланс клиента в каждом филиале

  • Настраиваемый процент кешбека (обычно 3-10%)

  • Возможность списания с кодом подтверждения

  • Срок действия бонусов (опционально)

Штампы и награды (Awards)#

  • Система накопительных штампов (например, 10 покупок = бесплатный кофе)

  • Настраиваемые награды для каждого филиала

  • Автоматическое добавление товара-подарка в чек

Филиалы (Branches)#

  • branch_id - уникален для каждого отдельного филиала

  • group_id - уникален для каждой группы филиалов одного бизнеса

  • Индивидуальные настройки программы лояльности

  • Возможность работы в сети заведений

Пример структуры ID: Бизнес «Рога и Копыта» имеет 10 филиалов:

  • Филиал №1: branch_id=100001, group_id=5000

  • Филиал №2: branch_id=100002, group_id=5000

  • Филиал №10: branch_id=100010, group_id=5000

Такая структура позволяет:

  • Управлять настройками каждого филиала независимо

  • Объединять статистику и клиентскую базу по группе

  • Переводить бонусы между филиалами одного бизнеса

Требования к интеграции#

Технические требования:#

  • HTTP/HTTPS клиент для API запросов

  • JSON поддержка для обмена данными

  • JWT токены для аутентификации

  • UTF-8 кодировка для корректного отображения кириллицы

Версии API:#

  • Текущая версия: v1 (/api/v1/)

  • Формат дат: ISO 8601 (RFC3339)

  • Кодировка: UTF-8

  • Формат данных: JSON

Лимиты запросов:#

  • Общий лимит: 1000 запросов/час на токен

  • Аутентификация: 10 попыток/час на IP

  • Поиск клиентов: 100 запросов/минуту

  • Транзакции: без ограничений (для активных операций)

Безопасность:#

  • HTTPS обязателен - все HTTP запросы перенаправляются

  • JWT токены с автоматическим обновлением

  • SMS коды для подтверждения списания бонусов

  • Ограничения по ролям (кассир/администратор/менеджер)

Полезные ссылки#

Swagger API Documentation - интерактивная документация с возможностью тестирования: https://gateway.sagi.kz/api/v1/swagger/index.html

Поддержка#

При возникновении вопросов по интеграции:

  • WhatsApp: +7 775 700 0030