Закупки через API

Этот раздел описывает безопасный сценарий чтения закупочного процесса внешней системой: от выпуска ключа до получения закупки, её позиций, RFQ и предложений поставщиков.

Где получить API-ключ

Ключ выпускается в том портале, данные которого должна читать внешняя система:

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

Прямой относительный путь:

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

Если «Закупки — чтение» показано серым, текущая роль не может передать это право API-ключу. Администратор портала должен выдать создателю ключа Заявки → Просмотр → Все. Давать пользователю административный доступ ко всей платформе для этого не нужно.

Для одностороннего чтения отметьте только:

purchase_requisitions.read

Если нужны RFQ и предложения поставщиков, дополнительно отметьте:

supplier_documents.read

Не выбирайте права записи, если внешняя система только выгружает данные. Полный секрет spk_... показывается после создания один раз.

Авторизация в Swagger

Откройте Swagger на домене своего портала:

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

Нажмите Authorize, вставьте полный spk_... и подтвердите. Не добавляйте Bearer и не вставляйте имя заголовка: Swagger самостоятельно сформирует X-API-Key.

Сырой OpenAPI для Postman, IDE или генератора SDK:

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

Проверка доступных ресурсов

Всегда начинайте интеграционную диагностику с метаданных:

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

В resources должны присутствовать как минимум:

{
  "key": "purchase-requisitions",
  "scope": "purchase_requisitions",
  "operations": ["list", "get"]
}

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

Список закупок

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

Параметры:

Параметр	Тип	Назначение
search	string	Поиск по номеру, названию, номеру заявки заказчика и комментарию
q	string	Приоритетный алиас search
pipelineId	UUID	Ограничить результат одной доступной воронкой
page	integer, от 1	Номер страницы
limit	integer, 1–100	Размер страницы, по умолчанию 50

Пример типизированного ответа:

{
  "resource": "purchase-requisitions",
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "number": "Заявка-2026-001",
      "pipelineId": "22222222-2222-4222-8222-222222222222",
      "name": "Насосное оборудование",
      "status": "in_progress",
      "plannedTotal": "150000.00",
      "currency": "RUB",
      "dueDate": "2026-08-15T00:00:00.000Z",
      "createdAt": "2026-07-20T09:00:00.000Z",
      "updatedAt": "2026-07-28T08:30:00.000Z"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1
}

Для одной записи:

GET /api/v1/integration-api/purchase-requisitions/{id}
X-API-Key: spk_...

Позиции закупки

GET /api/v1/integration-api/procurement-items?procurementId={id}&page=1&limit=100
X-API-Key: spk_...

Ответ содержит опубликованные поля позиции: id, procurementId, catalogItemId, skuSnapshot, rawName, quantity, unitId, unitPrice, totalPrice, vatRate, требуемую и плановую даты, полученное количество, статус и даты изменения.

Можно дополнительно использовать pipelineId, status, updatedSince, search или q. Прямое чтение одной позиции:

GET /api/v1/integration-api/procurement-items/{id}
X-API-Key: spk_...

Запросы цен поставщикам

GET /api/v1/integration-api/supplier-rfqs?procurementId={id}&page=1&limit=50
X-API-Key: spk_...

Требуется supplier_documents.read. Фильтры: procurementId, pipelineId, supplierId, status, updatedSince, search или q.

Ответ содержит бизнес-номер, закупку, поставщика, тему, сроки, статус, валюту, суммы, условия оплаты и доставки и опубликованные даты жизненного цикла. Он не содержит технические параметры доставки, токены, внутренние комментарии, служебные snapshots и контактные адреса.

Предложения поставщиков

GET /api/v1/integration-api/supplier-quotes?procurementId={id}&page=1&limit=50
X-API-Key: spk_...

Требуется supplier_documents.read. Кроме общих фильтров можно передать rfqId. Ответ содержит связь с закупкой и RFQ, поставщика, номер предложения, статус, источник, валюту, суммы, НДС, сроки и публичные условия.

RFQ, предложения и позиции доступны только для чтения. Их изменение и команды жизненного цикла через внешний контракт не публикуются.

Воронки и этапы

Чтобы сопоставить pipelineId и текущие этапы:

GET /api/v1/integration-api/pipelines
GET /api/v1/integration-api/pipelines/{pipelineId}/stages
X-API-Key: spk_...

Возвращаются только воронки, доступные создателю ключа. Управление составом воронок и этапов во внешний API не входит.

Почему список может быть пустым

200 OK с пустым items не всегда означает отсутствие закупок в портале. Проверьте:

1. в GET /meta есть нужный resource и scope;
2. создатель ключа активен и имеет полное право чтения домена;
3. создателю доступны воронки, где находятся нужные закупки;
4. переданный pipelineId относится к одной из этих воронок;
5. search, status, updatedSince и другие фильтры не исключили записи.

Коды диагностики:

HTTP	Что проверить
401	Заголовок X-API-Key, полный секрет, срок действия и отзыв ключа
403	Наличие scope и текущие права создателя ключа
404	ID, tenant и доступность родительской закупки
429	Лимит запросов и Retry-After

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

• Обзор публичного API
• Полный Integration API
• Коды ошибок