API SNABZHENETS+

Этот раздел предназначен для специалиста, который подключает вашу учётную систему, CRM или отчётность к SNABZHENETS+. Для работы в самом портале начните с первых шагов.

Integration API позволяет читать и изменять доступные данные, Variable API — получать значения отдельных полей, а исходящие webhook-события — узнавать об изменениях без постоянного опроса.

В примерах используются условные данные. Вместо <portal> подставьте адрес своего портала; ключ и идентификаторы получите в нём же.

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

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

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

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

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

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

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

Список показывает поддерживаемые права 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

Ключ открывает только выданные ему права. Используйте методы, перечисленные в этом разделе и OpenAPI вашего портала. Возможность выполнить действие в интерфейсе сама по себе не означает, что оно доступно через API.

Базовый 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
Получать уведомления об изменениях заявок	webhooks.read, webhooks.write, purchase_requisitions.read

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

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

Адреса методов используют версию v1. Тело запроса и обычные ответы передаются в JSON. Обязательные поля, ограничения и форматы описаны на странице соответствующего API.

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

Swagger и OpenAPI

Откройте /docs на домене того портала, для которого выдан ключ. Там находятся актуальные методы, поля и примеры запросов для подключения внешней системы.

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

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-события — события, тело запроса, заголовки и проверка подписи;
• Коды ошибок — HTTP-статусы, лимиты запросов и восстановление работы.

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

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