REST API модульных интеграций

Полный пользовательский справочник Integrations API (curl, поля, примеры ответов) — в разделе API интеграций: Структура и обозначения, Быстрый старт, Все методы API, Работа с заказами и др.

Ниже — краткая выжимка для разработчика модуля: те же эндпоинты, с акцентом на статусы, meta и связь с хуками.

Базовый URL: https://{домен}/api/integrations/v1/

Авторизация: Авторизация и секреты — Authorization: Bearer {identifier}:{secret}.

Ответы read — те же snapshot, что в хуках.

Заказы

Список

GET /api/integrations/v1/orders?per_page=50&since=2026-05-01T00:00:00Z
Authorization: Bearer my-key:secret

Scope: orders.read. Пагинация cursor, per_page до 100.

Карточка

GET /api/integrations/v1/orders/42

Смена статуса заказа

POST /api/integrations/v1/orders/42/status
Content-Type: application/json

{"status_code": "order.in_progress"}

или {"status_id": 5}.

Scope: orders.write_status.

Ответ (фрагмент):

{
  "ok": true,
  "unchanged": false,
  "order_id": 42,
  "status_code": "order.in_progress",
  "status_semantic": "IN_PROGRESS",
  "order": { "...": "snapshot" }
}

В аудите: initiator=integration. После commit уходят хуки order.status_changed (и при отмене — цепочка по позициям).

Позиция заказа

GET /api/integrations/v1/orders/42/items/7
POST /api/integrations/v1/orders/42/items/7/status
Content-Type: application/json

{"status_code": "item.issued"}

HTTP	Ситуация
404	Заказ/позиция не найдены или позиция не из этого заказа
403	Заказ другой точки (ключ привязан к точке)
422	Не указан статус или неизвестный status_code

Интеграция может менять позицию с status_locked (робот system — нет).

Meta заказа

POST /api/integrations/v1/orders/42/meta
Content-Type: application/json

{"meta": {"crm_id": "CRM-9912"}}

Scope: orders.write_meta. Namespace — по правилам IntegrationEntityMetaService (query/header, если настроено в ядре).

Пользователи

GET /api/integrations/v1/users
GET /api/integrations/v1/users/15
POST /api/integrations/v1/users/15/meta

Scope: users.read, users.write_meta.

Платежи, документы, организации, каталог

Метод	URL	Scope
GET	/payments	payments.read
GET	/documents	documents.read
POST	/documents/{id}/external-ref	documents.write_external_ref
GET	/organizations	organizations.read
GET	/products	products.read
GET	/pickup-points	pickup_points.read

Запуск синхронизации модуля

POST /api/integrations/v1/integrations/MyCrm/sync

Scope: integrations.trigger_sync. Ставит хук integration.sync_requested для пакета.

Inbound (отдельный контур)

POST /api/integrations/v1/integrations/inbound/MyCrm/3

Без Bearer API‑ключа — только подпись inbound. Подробнее: Входящий webhook.

Рекомендации

• Не опрашивайте GET /orders каждую секунду — используйте хуки/webhook для push.
• Обрабатывайте unchanged: true при смене статуса на тот же.
• Храните связку order.id ↔ внешний ID в meta, а не только в CRM.

Связанные разделы

• Хуки
• Примеры

Документы

Через API доступны только чтение списка и запись внешнего ID (GET /documents и POST /documents/{id}/external-ref). Создать или править документ через API нельзя. Подробнее: Документы.