Integration API

Integration API — стабильный REST-фасад для ERP, CRM, BI и middleware. Он работает через API keys и не открывает внутренние endpoints интерфейса.

Короткий ответ

Integration API даёт внешним системам безопасный REST-доступ к объектам закупочного процесса: заявкам, поставщикам, номенклатуре, складам, прайс-листам, счетам и связям с внешними ID.

Базовый URL

/api/v1/integration-api

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

Передавайте API key одним из способов:

X-API-Key: spk_...
Authorization: Bearer spk_...

Ключи с write/delete scopes выполняют действия от имени пользователя, который создал ключ. Ключи без пользователя-создателя могут выполнять только чтение.

На один портал действует один активный публичный API key. Чтобы выпустить новый ключ, сначала отзовите текущий.

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

Публичный Integration API ограничен по API key/tenant: по умолчанию 300 запросов в минуту. Платформенный администратор может увеличить лимит в Hub до 3000 запросов в минуту.

Каждый ответ содержит остаток лимита:

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

При превышении лимита API возвращает 429:

{
  "statusCode": 429,
  "error": "rate_limited",
  "message": "Public API rate limit exceeded",
  "limit": 300,
  "remaining": 0,
  "resetInSeconds": 17
}

В ответе 429 также есть Retry-After.

Meta

GET /api/v1/integration-api/meta

Возвращает доступные ресурсы, операции, события и scopes текущего ключа.

Список стабильных outbound webhook-событий описан отдельно в разделе Исходящие webhook-события.

Webhook-подписки

Исходящие webhook-подписки можно настраивать через JSON API:

GET    /api/v1/integration-api/webhook
POST   /api/v1/integration-api/webhook
PUT    /api/v1/integration-api/webhook/:id
DELETE /api/v1/integration-api/webhook/:id
POST   /api/v1/integration-api/webhook/:id/test

POST принимает JSON array. Каждый элемент создаёт отдельный webhook на одно событие и один URL:

[
  {
    "name": "ERP procurement status",
    "event": "integration_api.procurement.status_changed",
    "url": "https://erp.example.com/hooks/snabzhenets",
    "isActive": true
  }
]

Список, изменение и удаление возвращают параметры webhook в JSON. Секрет подписи возвращается только один раз при создании в поле secretPlaintext.

Быстрый старт webhook через API

1. Создайте API key со scopes webhooks.read, webhooks.write и, если нужно отключать подписки, webhooks.delete. Вместо них можно использовать общие scopes integration_api.read/write/delete.
2. Получите доступные события через GET /api/v1/integration-api/meta и возьмите нужное имя из поля events.
3. Создайте подписку через POST /api/v1/integration-api/webhook.
4. Сохраните secretPlaintext из ответа. Повторно получить секрет нельзя.
5. Нажмите тестовую доставку через POST /api/v1/integration-api/webhook/:id/test и проверьте подпись на своей стороне.

Получить список webhook

GET /api/v1/integration-api/webhook
Authorization: Bearer spk_...

{
  "items": [
    {
      "id": "hook_id",
      "name": "ERP procurement status",
      "event": "integration_api.procurement.status_changed",
      "url": "https://erp.example.com/hooks/snabzhenets",
      "isActive": true,
      "successCount": 12,
      "failureCount": 1,
      "lastDeliveredAt": "2026-06-09T10:00:00.000Z",
      "lastErrorAt": null,
      "lastErrorMessage": null,
      "createdAt": "2026-06-09T09:00:00.000Z",
      "updatedAt": "2026-06-09T09:00:00.000Z"
    }
  ]
}

Изменить webhook

PUT /api/v1/integration-api/webhook/hook_id
Authorization: Bearer spk_...
Content-Type: application/json

{
  "name": "ERP procurement status v2",
  "event": "integration_api.procurement.updated",
  "url": "https://erp.example.com/hooks/snabzhenets-v2",
  "isActive": true
}

Можно передавать только изменяемые поля. Ответ возвращается в формате { "item": ... } без секрета.

Отключить webhook

DELETE /api/v1/integration-api/webhook/hook_id
Authorization: Bearer spk_...

Удаление мягкое: подписка остаётся в истории, но возвращается с isActive: false.

Отправить test event

POST /api/v1/integration-api/webhook/hook_id/test
Authorization: Bearer spk_...

Тестовая доставка использует тот же URL, headers и HMAC-подпись, что и боевые события. Её событие — integration.test_event.

Валидация webhook

• url должен быть публичным HTTPS/HTTP endpoint, который проходит защиту от SSRF.
• event должен быть из публичного каталога событий.
• Один элемент массива создаёт одну подписку на одно событие и один URL.
• При ошибке в любом элементе create-запрос отклоняется целиком.

Ресурсы

Поддерживаемые ресурсы v1:

Resource	Назначение
purchase-requisitions	Заявки
catalog-items	Номенклатура
counterparties	Контрагенты
warehouses	Склады
price-lists	Прайс-листы
invoices	Входящие счета

Legacy-ключ procurements принимается как alias для purchase-requisitions.

Общие операции:

GET    /api/v1/integration-api/:resource
POST   /api/v1/integration-api/:resource
GET    /api/v1/integration-api/:resource/:id
PATCH  /api/v1/integration-api/:resource/:id
DELETE /api/v1/integration-api/:resource/:id
POST   /api/v1/integration-api/:resource/:id/operations/change-status

DELETE в v1 архивирует ресурс, если доменная сущность поддерживает архивирование.

External Links

Связи помогают сопоставлять внешний ID с внутренней сущностью SNABZHENETS+.

GET /api/v1/integration-api/links?externalSource=erp&externalId=1001&entityType=catalog_item

PUT /api/v1/integration-api/links
Content-Type: application/json

{
  "externalSource": "erp",
  "externalId": "1001",
  "entityType": "catalog_item",
  "entityId": "uuid",
  "idempotencyKey": "erp-1001-v4"
}

Пример

POST /api/v1/integration-api/catalog-items
Authorization: Bearer spk_...
Content-Type: application/json

{
  "sku": "PUMP-100",
  "name": "Насос циркуляционный",
  "brand": "Grundfos",
  "externalSource": "erp",
  "externalId": "1001",
  "idempotencyKey": "erp-catalog-1001"
}

Scopes

Можно выдать общий scope integration_api.read/write/delete или доменные scopes:

• purchase_requisitions.read/write/delete
• counterparties.read/write/delete
• suppliers.read/write/delete
• catalog.read/write/delete
• warehouses.read/write/delete
• price_lists.read/write/delete
• finance.read/write/delete
• supplier_documents.read/write/delete
• customer_documents.read/write/delete
• settings.read/write/delete
• webhooks.read/write/delete

Для Variable API дополнительно нужен variables.read. Legacy scopes procurements.* принимаются как alias для purchase_requisitions.*.

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

• API для интеграции закупок
• Обзор API
• Аутентификация
• Исходящие webhook-события