Аутентификация#

Система Sagi использует аутентификацию на основе JWT токенов для доступа к бизнес API.

Типы аутентификации:

  • Bearer JWT - основной тип аутентификации для всех API запросов

  • Срок действия токена: 30 дней

  • Максимальный период обновления: 365 дней

  • Заголовок: Authorization: Bearer {token}

Авторизация бизнес-пользователя#

POST /api/v1/auth/business#

Метод для авторизации бизнес-пользователя через логин и пароль.

Тело запроса:

{
    "phone": "string",        // логин пользователя
    "password": "string",     // пароль пользователя
    "license_key": "string"   // опционально: лицензионный ключ
}

Пример запроса:

curl -X POST "{{baseURL}}/api/v1/auth/business" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "business_user@example.com",
    "password": "secure_password"
  }'

Успешный ответ (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expire": "2024-10-15T10:30:00Z",
  "muted": false,
  "organization": {
    "id": 1231456789,
    "role": "administrator",    // analytic, administrator, cashier
    "branches": [1234567890123456789, 9876543210987654321],
    "branches_details": [
      {
        "id": 1988850967616950272,
        "name": "BranchName",
        "subscription_active": true
      }
    ]
  }
}

Коды ошибок:

  • 400 - Неверный формат данных

  • 401 - Неверный логин или пароль

  • 500 - Внутренняя ошибка сервера

Важные поля ответа:

  • access_token - JWT токен для дальнейших запросов

  • expire - время истечения токена в формате RFC3339

  • organization.branches - массив ID филиалов, доступных пользователю

  • organization.role - роль пользователя (employer, administrator, cashier)

Обновление токена#

POST /api/v1/auth/refresh_token#

Обновляет истекший или истекающий токен.

Заголовки:

Authorization: Bearer {current_token}

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

Пример запроса:

curl -X POST "{{baseURL}}/api/v1/auth/refresh_token" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Успешный ответ (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expire": "2024-11-15T10:30:00Z"
}

Рекомендации по безопасности#

  1. Хранение токенов: Сохраняйте токены безопасно, не передавайте в URL

  2. Обновление: Используйте автоматическое обновление токенов за 1-2 дня до истечения

  3. Логирование: Логируйте все попытки аутентификации для аудита

  4. Филиалы: После авторизации обязательно сохраните branches[0] как основной филиал

  5. Group ID: Получите group_id филиала через метод получения информации о филиале

Получение информации о филиале#

После авторизации необходимо получить подробную информацию о филиале:

GET /api/v1/branches/{branch_id}#

Используйте первый элемент из массива branches для получения group_id, который потребуется для работы с бонусами клиентов.