Модель доступа¶

Доступ к организации, разрешение создавать заявки и доступ к конкретной заявке — разные права.

Идентификация партнёра¶

CARGO.RUN определяет партнёрский сервис по clientId из M2M-токена. Для получения заявок перевозчика дополнительно используется платформа, настроенная у интеграционного клиента.

Проверка организации¶

GET <baseUrl>/api/integrations/Organizations/Check?inn={inn}
Authorization: Bearer <accessToken.token>

Ответ:

{
  "exists": true,
  "canCreateBids": true,
  "hasAccess": false
}

Поле	Значение
`exists`	Организация с таким ИНН существует
`canCreateBids`	Партнёрским сервисам разрешено создавать её заявки
`hasAccess`	Текущий интеграционный клиент уже связан с организацией

Результат	Действие
`exists=false`	Вызвать `Organizations/Apply`
`canCreateBids=true`, `hasAccess=true`	Можно создавать заявки
`canCreateBids=true`, `hasAccess=false`	Вызвать `Organizations/Apply` для получения доступа
`canCreateBids=false`	Не создавать заявку; можно читать заявки, которые перевозчик связал с партнёром

Создание организации¶

POST <baseUrl>/api/integrations/Organizations/Apply
Authorization: Bearer <accessToken.token>
Content-Type: application/json

{
  "name": "ООО Ромашка",
  "inn": "7701234567",
  "kpp": "770101001",
  "ogrn": "1027700000000"
}

Поля name и inn обязательны. Поиск организации выполняется по ИНН.

Правила:

новая организация создаётся и связывается с текущим партнёром;
к организации, созданной другим партнёрским сервисом, текущему партнёру может быть выдан собственный доступ;
доступ к внутренней организации CARGO.RUN по умолчанию не выдаётся;
исключение возможно только при явной административной настройке.

Успешный ответ содержит ID организации:

{
  "id": 12345
}

Доступ к заявке¶

Партнёр может читать:

Заявку, созданную им в доступной организации. Проверяется источник заявки, внешний ID и технический пользователь организации.
Заявку перевозчика, у которой ExternalPlatform соответствует платформе партнёра и заполнен ExternalPlatformOrderId.

Знание ID не предоставляет доступ к произвольной заявке.

При синхронном чтении недоступной или несуществующей заявки возвращается 404 Not Found. В асинхронной очереди HTTP-запрос задачи может завершиться успешно, а ошибка возвращается в objects[].status="Error" и objects[].message.

Идентификаторы заявки¶

Идентификатор	Назначение
`id`	Внутренний ID заявки CARGO.RUN
`bid.externalId`	ID заявки, созданной партнёрским сервисом
`ExternalPlatformOrderId`	ID заказа партнёра, указанный перевозчиком в CARGO.RUN
`IntegrationBidListModel.externalId`	Для связанной заявки содержит `ExternalPlatformOrderId`; для собственной — `bid.externalId`
`objects[].key`	При `Write` используется как `bid.externalId`, если поле внутри `bid` не заполнено

Область объединённого списка¶

Для GET /api/integrations/Bids/GetList заголовок X-Organization-Id необязателен:

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

В обоих случаях список объединяет собственные и транслируемые заявки. Используйте isCreatedByPlatform, а не наличие externalId, чтобы определить источник.