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

API SNABZHENETS+ использует JWT (JSON Web Token) для пользовательских запросов. Для некоторых интеграционных сценариев, например Variable API, можно использовать API keys с ограниченными scopes.

Получение токена

Отправьте POST-запрос с учётными данными:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@company.com",
  "password": "your-password"
}

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

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600
}

Если пользователь зарегистрирован публично и ещё не подтвердил email, вход возвращает 403 с кодом email_not_verified. Повторное письмо подтверждения можно запросить через POST /api/v1/auth/email-verification/resend; ответ не раскрывает, существует ли аккаунт.

Использование токена

Передавайте accessToken в заголовке каждого запроса:

GET /api/v1/purchase-requisitions
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

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

accessToken действует 1 час. Для получения нового токена без повторного ввода пароля используйте refreshToken:

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Изоляция порталов

Каждый токен привязан к конкретному порталу. Запросы с токеном одного портала не могут получить данные другого портала.

API keys

Администратор портала может выпустить API key для внешней системы. Ключ передаётся в заголовке:

X-API-Key: spk_...

Ключ не заменяет пользовательский логин и не даёт полный доступ к порталу. Для Variable API он должен иметь variables.read и один или несколько доменных scopes, например catalog.read, purchase_requisitions.read, documents.read, company.read.

Для Integration API ключ можно передавать как X-API-Key: spk_... или Authorization: Bearer spk_.... Write/delete-запросы выполняются от имени пользователя, который создал ключ; ключи без пользователя-создателя работают только на чтение.

На портал может быть активен только один публичный API key. Integration API отдаёт остаток лимита в RateLimit-* headers и возвращает 429, если лимит запросов исчерпан.

Секретная часть ключа показывается только при создании. Если ключ скомпрометирован, его нужно архивировать и выпустить новый.

Лимиты Integration API

Для публичного Integration API действует tenant-лимит: по умолчанию 300 запросов в минуту. Если у портала несколько старых ключей, они используют общий bucket портала. Новые активные дубликаты не создаются: сначала архивируйте текущий ключ.

Каждый ответ Integration API содержит headers:

RateLimit-Limit: 300
RateLimit-Remaining: 299
RateLimit-Reset: 42
RateLimit-Policy: 300;w=60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1760000042

При 429 дождитесь времени из Retry-After или resetInSeconds, затем повторите запрос.

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

• Не передавайте токены в URL-параметрах
• Храните токены в безопасном месте и не размещайте их в открытом браузерном хранилище
• При компрометации токена — смените пароль в настройках профиля
• Для API keys выдавайте минимальный набор scopes, необходимый интеграции