Интеграции

Управление подключениями к внешним сервисам. Сейчас через API доступен CRUD интеграций CDEK API v2.

Права и область видимости

Все endpoint-ы требуют Sanctum Bearer token. Доступ проверяется через модуль integrations новой системы ролей, Orchid route permission platform.integrations.cdek.list и legacy-роли.

Действие	Новая система	Legacy-роли
Просмотр	`integrations.view`	`admin`, `warehouse_manager`, `warehouse_worker`
Создание/изменение	`integrations.create/update`	`admin`, `warehouse_manager`, `warehouse_worker`
Удаление	`integrations.delete`	`admin`, `warehouse_manager`

Data scope применяется так же, как в ЛК: global видит все домены, domain и warehouse видят свой домен, owner видит только свои интеграции.

Формат source_id

Источник доставки хранится строкой в формате {provider}-{account_id}. Для записи CDEK ca_id=15 API вернет source_id=cdek-15. Это значение нужно передавать в заказе как ds.ods_source_id. Для совместимости старое значение без префикса, например 12, считается apiship-12. Legacy значение -15 считается cdek-15 и при миграции будет приведено к новому формату.

GET/api/integrations/cdek

Список доступных текущему пользователю интеграций CDEK.

ca_status	0 или 1.
ca_domain_id	Фильтр по домену. Для не-global scope дополнительно ограничивается своим доменом.
ca_user_id	Фильтр по владельцу интеграции.
ca_name	Поиск по названию.
sort	`ca_id`, `ca_name`, `ca_status`, `ca_domain_id`, `ca_user_id`, `updated_at`. Минус означает DESC.
per_page	Максимум 250, по умолчанию 50.

GET /api/integrations/cdek?ca_status=1&sort=-ca_id&per_page=50

POST/api/integrations/cdek

Создание интеграции CDEK. Секрет сохраняется, но в ответе не возвращается.

{
  "ca_name": "Основной CDEK",
  "ca_base_url": "https://api.cdek.ru",
  "ca_client_id": "account-id",
  "ca_client_secret": "secure-password",
  "ca_domain_id": 10,
  "ca_user_id": 0,
  "ca_status": 1,
  "ca_test_mode": false,
  "ca_order_type": 1,
  "ca_ds_id": 2,
  "ca_tariff_code": 136,
  "ca_shipment_point": "MSK1",
  "ca_sender_company": "ООО Ромашка",
  "ca_sender_name": "Иван Иванов",
  "ca_sender_phone": "+79990000000",
  "ca_sender_email": "sender@example.com"
}

Поля отправителя в интеграции необязательные и имеют приоритет над складом. Если ca_shipment_point, ca_sender_city, ca_sender_address или контактные поля отправителя пустые, NWMS берет их из вкладки Доставки FF-склада заказа. Для клиентского склада используется его связанный FF-склад из wh_parent_id. ca_tariff_code теперь необязательный тариф по умолчанию; основной тариф нужно передавать в заказе как ds.ods_tariff_code. Если заполнить ca_ds_id, то при создании/обновлении заказа с ds.ods_source_id=cdek-{ca_id} поле ds.ods_ds_id можно не передавать: NWMS возьмет службу доставки из интеграции.

{
  "ca_id": 15,
  "source_id": "cdek-15",
  "ca_name": "Основной CDEK",
  "ca_client_secret_set": true,
  "ca_ds_id": 2,
  "ca_tariff_code": 136
}

GET/api/integrations/cdek/{id}

Получить одну интеграцию CDEK с учетом data scope.

PUT/api/integrations/cdek/{id}

Частичное обновление интеграции. Если ca_client_secret не передан или передан пустым, текущий секрет не меняется.

{
  "ca_name": "CDEK Москва",
  "ca_base_url": "https://api.edu.cdek.ru",
  "ca_test_mode": true,
  "ca_tariff_code": 136
}

DELETE/api/integrations/cdek/{id}

Удаление интеграции. Требуется уровень удаления модуля integrations или legacy-роль admin/warehouse_manager.

{
  "deleted": true
}

Econt

Legacy CRUD endpoints для настроек интеграции Econt. Права, data scope, pagination и правила скрытия секретов такие же, как у CDEK-интеграций.

GET/api/integrations/econt

Список доступных текущему пользователю интеграций Econt.

Право	`integrations.view`
Filters	`status`, `domain_id`, `user_id`, `name`.
Sort	`id`, `name`, `status`, `updated_at`.

GET /api/integrations/econt?status=1&sort=-id&per_page=50

POST/api/integrations/econt

Создает Econt-интеграцию. Секретные поля сохраняются, но не возвращаются в ответе.

Право	`integrations.create`
Required	Название интеграции и учетные данные Econt.
Response	Возвращает созданную интеграцию и `source_id` для использования в заказах.

{
  "name": "Econt Sofia",
  "status": 1,
  "domain_id": 10,
  "user_id": 0,
  "client_id": "econt-client",
  "client_secret": "secure-password"
}

GET/api/integrations/econt/{id}

Возвращает одну Econt-интеграцию, если она входит в область видимости пользователя.

Право	`integrations.view`
404	Интеграция не существует или скрыта data scope.

PUT/api/integrations/econt/{id}

Частично обновляет Econt-интеграцию. Если секрет не передан, сохраненное значение не меняется.

Право	`integrations.update`
Payload	Можно передать только изменяемые поля.

DELETE/api/integrations/econt/{id}

Удаляет Econt-интеграцию. Требуется право удаления интеграций.

{
  "deleted": true
}

Speedy

Legacy CRUD endpoints для настроек интеграции Speedy. Модель доступа и область видимости совпадают с другими delivery integrations.

GET/api/integrations/speedy

Список доступных текущему пользователю интеграций Speedy.

Право	`integrations.view`
Filters	`status`, `domain_id`, `user_id`, `name`.
Sort	`id`, `name`, `status`, `updated_at`.

GET /api/integrations/speedy?status=1&sort=-id&per_page=50

POST/api/integrations/speedy

Создает Speedy-интеграцию. Секретные поля не возвращаются в ответе.

Право	`integrations.create`
Required	Название интеграции и учетные данные Speedy.
Response	Возвращает созданную интеграцию и `source_id` для заказов.

{
  "name": "Speedy Varna",
  "status": 1,
  "domain_id": 10,
  "user_id": 0,
  "client_id": "speedy-client",
  "client_secret": "secure-password"
}

GET/api/integrations/speedy/{id}

Возвращает одну Speedy-интеграцию, если она входит в область видимости пользователя.

Право	`integrations.view`
404	Интеграция не существует или скрыта data scope.

PUT/api/integrations/speedy/{id}

Частично обновляет Speedy-интеграцию. Если секрет не передан, сохраненное значение не меняется.

Право	`integrations.update`
Payload	Можно передать только изменяемые поля.

DELETE/api/integrations/speedy/{id}

Удаляет Speedy-интеграцию. Требуется право удаления интеграций.

{
  "deleted": true
}

Автоматическая работа заказов

После выбора CDEK-интеграции в доставке заказа NWMS использует ту же конвейерную логику, что и ApiShip: выгрузка по статусу, получение печатной формы и прогрузка статусов после отправки. CDEK распознается по префиксу cdek- в ods_source_id. Тариф отправки берется из ds.ods_tariff_code заказа, а если поле пустое, используется необязательный ca_tariff_code интеграции.