API SNABZHENETS+

Публичный API предназначен для согласованного обмена данными с ERP, CRM, BI и middleware. Во внешний контракт входят только Integration API, Variable API и исходящие webhook-события.

Быстрый старт

1. Выпустите ключ в своём портале

Уполномоченный пользователь портала открывает:

Настройки → Интеграции → API / Webhooks → Управление → API-ключи

Прямой путь внутри текущего портала:

/app/settings/integrations/api-webhooks/manage

Для просмотра списка ключей нужны права api_keys.read, для выпуска — api_keys.create, а для отзыва — отдельное право отзыва API-ключей. Если интеграция ещё не установлена, её установку выполняет пользователь с правом управления интеграциями.

Консоль показывает все поддерживаемые безопасные scopes. Недоступные текущему пользователю права отображаются серыми: ключ не может получить больше доступа, чем его создатель. Чтобы выдать purchase_requisitions.read, роли создателя нужно право Заявки → Просмотр → Все. Это предметное право портала и не требует административного доступа ко всей платформе.

Укажите название внешней системы и отметьте только необходимые scopes. Для первой проверки чтения закупок достаточно:

purchase_requisitions.read

После нажатия Создать ключ сразу скопируйте полный секрет spk_.... Он показывается только один раз; восстановить его позднее нельзя.

2. Откройте OpenAPI своего портала

Swagger UI и исходная спецификация находятся на том же домене, где работает портал:

https://<portal>.snabplus.com/docs
https://<portal>.snabplus.com/docs-json

Также поддерживаются совместимые адреса /api/docs и /api/docs-json.

В Swagger нажмите Authorize и вставьте только полный spk_...:

• без логина и пароля;
• без текста X-API-Key:;
• без префикса Bearer.

Swagger самостоятельно передаст значение в заголовке X-API-Key.

3. Проверьте права ключа

GET /api/v1/integration-api/meta
X-API-Key: spk_...

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

4. Получите первые закупки

GET /api/v1/integration-api/purchase-requisitions?page=1&limit=50
X-API-Key: spk_...

В актуальном OpenAPI закупки находятся в отдельном разделе Procurements. Если API вернул 200, но items пуст, проверьте, есть ли у создателя ключа доступ к воронкам с нужными закупками. 401 означает проблему с самим ключом, а 403 — отсутствие требуемого scope или действующего доменного доступа.

Граница публичного API

API key внешнего разработчика не является пользовательской сессией и не даёт доступ к администрированию портала, управлению сотрудниками, ролями, настройками платформы или установленными сервисами. Внутренние методы приложения не входят в публичный контракт, даже если их вызывает веб-интерфейс SNABZHENETS+.

Используйте только методы, перечисленные в этом разделе документации. Попытка обратиться к другому контуру должна завершаться ответом 401, 403 или 404.

Базовый URL

Используйте адрес портала, для которого выдан ключ:

https://<portal>.snabplus.com/api/v1

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

Для каждой внешней системы владелец портала заранее выдаёт отдельный API key с точным минимальным набором scopes. Разработчик интеграции не создаёт ключ и не может самостоятельно расширить его права.

Передавайте ключ только в заголовке:

X-API-Key: spk_...

Не передавайте ключ в URL, query-параметрах, клиентском JavaScript, журналах или публичных репозиториях. При утечке прекратите запросы и запросите замену ключа у владельца портала.

Принцип минимальных прав

Каждый scope открывает только конкретный ресурс и действие. Для односторонней выгрузки достаточно scopes чтения; права записи выдаются только когда внешний сценарий действительно изменяет бизнес-данные.

Примеры:

Сценарий	Минимальные scopes
Читать номенклатуру	catalog.read
Создавать и обновлять заявки	purchase_requisitions.read, purchase_requisitions.write
Читать значения переменных каталога	variables.read, catalog.read
Управлять собственной webhook-подпиской	webhooks.read, webhooks.write

Не запрашивайте scopes «на будущее». Если сценарий расширяется, владелец портала должен отдельно согласовать новый набор прав.

Версионирование и форматы

Публичные paths используют версию v1. Bodies и обычные ответы передаются в JSON. Конкретные обязательные поля, ограничения и форматы описаны на странице соответствующего API.

Для изменяющих запросов используйте Idempotency-Key, когда он указан в контракте. Повторяйте запрос после сетевой ошибки только с тем же ключом и тем же телом.

Swagger и OpenAPI

Swagger UI демонстрационного портала содержит только разрешённый внешний контракт. Для реальной интеграции открывайте /docs на домене того портала, для которого выдан ключ. Swagger не является картой внутренних методов приложения.

Чтобы подготовить запрос:

1. откройте нужную операцию;
2. в блоке Parameters проверьте path, query и header-параметры;
3. в Request body → Schema посмотрите типы, обязательные поля, enum и ограничения;
4. переключитесь на Example Value, чтобы получить пример JSON;
5. в Responses проверьте схему успешного ответа и ожидаемые коды ошибок.

Сырую спецификацию OpenAPI можно импортировать в Postman, Insomnia, IDE или генератор клиента:

https://<portal>.snabplus.com/docs-json

Используйте только операции, присутствующие в этой публичной спецификации.

Разделы документации

• Integration API — ресурсы закупочного процесса и разрешённые операции внешней системы;
• Закупки через API — ключ, первый запрос, позиции, RFQ, предложения и диагностика пустого списка;
• Variable API — каталог доступных полей и чтение значений;
• Исходящие webhook-события — события, payload, headers и проверка подписи;
• Коды ошибок — HTTP-статусы, rate limit и обработка отказов.

Связанные страницы

• API для интеграции закупок