--- metadata: - name: generator content: Diplodoc Platform v5.64.2 alternate: - >- https://yamagistrali.ru/docs/ru/pages/api/usecases/for_insurance_organization/cargo_insurance_integration_usecase - href: >- https://yamagistrali.ru/docs/ru/pages/api/usecases/for_insurance_organization/cargo_insurance_integration_usecase.md type: text/markdown title: Markdown version - href: https://yamagistrali.ru/docs/ru/llms.txt rel: describedby style: - _assets/style/custom.css csp: - script-src: - https://mc.yandex.ru img-src: - https://mc.yandex.ru connect-src: - https://mc.yandex.ru - wss://mc.yandex.ru child-src: - 'blob:' - https://mc.yandex.ru frame-src: - 'blob:' - https://mc.yandex.ru frame-ancestors: - 'blob:' - https://mc.yandex.ru canonical: >- ru/pages/api/usecases/for_insurance_organization/cargo_insurance_integration_usecase.html vcsPath: >- ru/pages/api/usecases/for_insurance_organization/cargo_insurance_integration_usecase.md --- # Обработка заказов по страхованию груза по API Данный документ описывает процесс интеграции с API системы Магистрали для обработки заказов на страхование грузов. ## Полезные ссылки - [OpenAPI (Прод)](https://yamagistrali.ru/openapi_gen/) - [OpenAPI (Демо)](https://partner-test-yamagistrali.ru/openapi_gen/) - [OAuth Яндекса](https://oauth.yandex.ru/) - [Документация OAuth 2.0](https://yandex.ru/dev/id/doc/) --- ## Описание API Для описания интеграции с API Магистрали используется OpenAPI спецификация. Спецификацию можно найти [здесь](https://yamagistrali.ru/openapi/?urls.primaryName=Magistrali+insurance+beta). Для тестирования и разработки используйте демонстрационный стренд [здесь](https://partner-test-yamagistrali.ru/openapi/?urls.primaryName=Magistrali+insurance+beta). ## Диаграмма состояний заказов Для лучшего понимания процесса интеграции, ниже представлена диаграмма состояний заказов на страхование груза: ```mermaid stateDiagram-v2 [*] --> draft state "Черновик" as draft state "Ожидает страхования" as awaiting_insurance state "Получен страховой организацией" as received_by_insurance_organization state "Обработан страховой организацией" as processed_by_insurance_organization state "Отказ от страховой организации" as cancelled_by_insurance_organization state "Отменен клиентом" as cancelled_by_customer note left of awaiting_insurance Внутри состояния "Ожидает страховки": Клиент может обновлять данные без изменения состояния Заказ может вернуться в "Черновик" end note draft --> awaiting_insurance : Клиент отправил заказ awaiting_insurance --> draft : Редактирование заказа awaiting_insurance --> received_by_insurance_organization : Страховая получила заказ awaiting_insurance --> cancelled_by_insurance_organization : Отказ со стороны страховой организации awaiting_insurance --> cancelled_by_customer : Отмена клиентом received_by_insurance_organization --> processed_by_insurance_organization : Обработка завершена received_by_insurance_organization --> cancelled_by_insurance_organization : Отмена со стороны страховой организации received_by_insurance_organization --> cancelled_by_customer : Отмена со стороны клиента processed_by_insurance_organization --> cancelled_by_customer : Отмена со стороны клиента processed_by_insurance_organization --> [*] cancelled_by_customer --> [*] cancelled_by_insurance_organization --> [*] ``` ## Состояния заказов | Отображаемое имя | Состояние (API) | Описание | | -------------------------------- | ------------------------------------- | ---------------------------------------------------------- | | Черновик | `draft` | Заказ находится в разработке у клиента | | Ожидает страхования | `awaiting_insurance` | Заказ отправлен и ожидает обработки страховой организацией | | Получен страховой организацией | `received_by_insurance_organization` | Страховая организация получила заказ и начала обработку | | Обработан страховой организацией | `processed_by_insurance_organization` | Страховая организация завершила обработку заказа | | Отменён клиентом | `cancelled_by_customer` | Клиент отменил заказ | | Отказ от страховой организации | `cancelled_by_insurance_organization` | Страховая организация отказалась от страхования | ## Общий процесс интеграции 1. Регулярно запрашивайте обновления заказов на страхование груза 1. Подтверждайте получение обновлений 1. Обрабатывайте заказы в статусе `awaiting_insurance` 1. Обновляйте статусы заказов в системе 1. При необходимости, добавляйте страховые сертификаты ## Описание API эндпоинтов ### Получение обновлений заказов **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/listCargoInsuranceOrdersUpdates/v0` Получение списка необработанных обновлений запросов на страхование грузов, отсортированных по дате обновления от большего к меньшему. **Параметры запроса**: - `limit` (опциональный): Количество обновлений. Если не указан, то возвращаются 100 обновлений. **Пример запроса**: ```json { "data": { "limit": 100 } } ``` **Пример ответа**: ```json { "data": { "updates": [ { "updateId": "upd_123456", "id": "ins_789012", "updated": "2025-07-22T20:21:19.773333823Z" } ] } } ``` Где `updateId` - идентификатор обновления, `id` - идентификатор запроса на страхование грузов, `updated` - дата обновления в UTC. ### Получение деталей заказов **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/listCargoInsuranceOrders/v0` Получение подробной информации о запросах на страхование грузов. **Параметры запроса**: - `ids` (опциональный): Идентификаторы запросов на страхование грузов. Если null или не передан - возвращаются все запросы. - `limit` (обязательный): Лимит запросов на страхование грузов. Если не указан, то возвращаются первые 1000 запросов. **Пример запроса**: ```json { "data": { "ids": ["ins_789012"], "limit": 1000 } } ``` **Пример ответа**: ```json { "data": { "orders": [ { "id": "ins_789012", "created": { "time": "2020-01-01T00:00:00", "displayTZ": "+03:00" }, "updated": { "time": "2020-01-01T00:00:00", "displayTZ": "+03:00" }, "receivedByInsuranceOrganization": null, "processedByInsuranceOrganization": null, "cancelledByCustomer": null, "cancelledByInsuranceOrganization": null, "state": "awaiting_insurance", "insuranceOrganizationId": "io_123456", "insuranceOrganizationName": "Страховая организация", "cargoInsuranceProductId": "cip_123456", "isRefrigeratorModeCoverageIncluded": true, "direction": "ru_ru", "cargoInsuranceSubProducts": [ { "id": "cisp_123456", "displayName": "Страхование от мошенничества" } ], "customerOrganizationId": "f123456", "customerOrganizationName": "ООО \"Клиент\"", "customerOrganizationTin": "0238475023", "packageName": "Холодильное оборудование", "declaredCargoCost": 20000000.0, "declaredCargoCostCurrency": "RUB", "shipmentAddress": "Москва, ул. Льва Толстого, 16", "shipmentCountryCode": "RU", "shipmentStartDateTime": { "time": "2025-01-01T00:00:00", "displayTZ": "+03:00" }, "unshipmentAddress": "Санкт-Петербург, Пискарёвский просп., 2, корп. 2Щ", "unshipmentCountryCode": "RU", "unshipmentEndDateTime": { "time": "2025-02-01T00:00:00", "displayTZ": "+03:00" }, "isHasUnacknowledgementedUpdates": true, "updates": [ { "updateId": "upd_123456", "updateDateTime": { "time": "2025-07-22T20:21:19.773333823Z", "displayTZ": "+03:00" }, "isAcknowledgeSet": false } ], "insuranceCertificateExternalId": "string", "insuranceCertificateNumber": "string", "insuranceCertificateDate": "2025-07-22T20:21:19.773333823Z", "insuranceCertificateExternalLink": "string", "insuranceCertificateFileContainerId": "string", "insurancePremium": 0, "insurancePremiumCurrency": "string", "orderId": "0-prefix_ID-2509-26-10-001", "packageId": "54-prefix_ID-2509-26-10-002", "transportationType": ["auto", "railway"], "comment": "Some comment test" } ] } } ``` ### Подтверждение получения обновлений **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersUpdatesAcknowledge/v0` Указание, что обновления запросов на страхование грузов обработаны. **Параметры запроса**: - `updateIds`: Идентификаторы обновлений, которые были обработаны. **Пример запроса**: ```json { "data": { "updateIds": ["upd_123456"] } } ``` ### Установка статуса "Получен страховой организацией" **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersReceivedByInsuranceOrganization/v0` Указание, что запросы на страхование грузов получены страховой организацией. **Параметры запроса**: - `ids`: Идентификаторы запросов на страхование грузов. **Пример запроса**: ```json { "data": { "ids": ["ins_789012"] } } ``` ### Установка статуса "Обработан страховой организацией" **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersProcessedByInsuranceOrganization/v0` Указание, что запросы на страхование грузов обработаны страховой организацией. **Параметры запроса**: - `ids`: Идентификаторы запросов на страхование грузов. **Пример запроса**: ```json { "data": { "ids": ["ins_789012"] } } ``` ### Установка статуса "Отказ от страховой организации" **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersCancelledByInsuranceOrganization/v0` Указание, что запросы на страхование грузов отменены страховой организацией. **Параметры запроса**: - `ids`: Идентификаторы запросов на страхование грузов. **Пример запроса**: ```json { "data": { "ids": ["ins_789012"] } } ``` ### Добавление страхового сертификата **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/updateCargoInsuranceCertificate/v0` Обновление параметров страхового сертификата или полиса. **Параметры запроса**: - `id` (обязательный): Идентификатор запроса на страхование грузов. - `insuranceCertificateExternalId` (опциональный): Внешний ID страхового сертификата. - `insuranceCertificateNumber` (опциональный): Номер страхового сертификата. - `insuranceCertificateDate` (опциональный): Дата страхового сертификата. - `insuranceCertificateExternalLink` (опциональный): Ссылка на страховой сертификат. - `insuranceCertificateFileContainerId` (опциональный): ID контейнера с файлами сертификата (см. раздел "Загрузка файлов сертификата"). - `insurancePremium` (опциональный): Страховая премия. - `insurancePremiumCurrency` (опциональный): Валюта страховой премии. Если какой-то параметр не передан, он не будет обновлен. **Пример запроса**: ```json { "data": { "id": "ins_789012", "insuranceCertificateNumber": "CERT-123456", "insuranceCertificateDate": "2025-07-22T20:21:19.773333823Z", "insuranceCertificateExternalLink": "https://example.com/certificate/123456", "insurancePremium": 1500.0, "insurancePremiumCurrency": "RUB" } } ``` --- ### Загрузка файлов сертификата Для добавления файлов страхового сертификата необходимо выполнить три последовательных действия: #### 1. Создать контейнер для файлов **Эндпоинт**: `POST /api/storage/container/create/v0` Создает временный контейнер для хранения файлов. Контейнер имеет TTL (время жизни) по умолчанию 1 день. **Пример запроса**: ```json { "data": {} } ``` **Пример ответа**: ```json { "data": { "id": "cont_" } } ``` {% note warning %} Для каждого заказа на страхование нужен отдельный контейнер с файлами. Контейнеры не переиспользуемые. {% endnote %} --- #### 2. Добавить файлы в контейнер **Эндпоинт**: `POST /api/storage/container/addFiles/v0` Загружает файлы в созданный контейнер. Файлы передаются в формате `multipart/form-data`. **Параметры запроса**: - `containerId` (form-data): ID контейнера, полученный на шаге 1. - `files` (form-data, массив файлов): Файлы для загрузки. **Пример ответа**: ```json { "data": { "files": { "filename1.pdf": "fs_", "filename2.pdf": "fs_" } } } ``` **Пример запроса**: ```bash curl -X POST https://yamagistrali.ru/api/storage/container/addFiles/v0 \ -H "Authorization: Bearer " \ -F "containerId=cont_" \ -F "files=@/path/to/certificate1.pdf" \ -F "files=@/path/to/certificate2.pdf" ``` --- #### 3. Привязать контейнер к страховому заказу **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/updateCargoInsuranceCertificate/v0` Обновляет информацию о страховом сертификате и привязывает контейнер с файлами к заказу на страхование. После привязки контейнер защищается от автоматического удаления по TTL. **Параметры запроса**: - `id` (обязательный): ID заказа на страхование грузов. - `insuranceCertificateFileContainerId` (опциональный): ID контейнера с файлами, полученный на шаге 1. - `insuranceCertificateNumber` (опциональный): Номер страхового сертификата. - `insuranceCertificateDate` (опциональный): Дата страхового сертификата. - `insuranceCertificateExternalLink` (опциональный): Внешняя ссылка на сертификат. - `insuranceCertificateExternalId` (опциональный): Внешний ID сертификата. - `insurancePremium` (опциональный): Страховая премия. - `insurancePremiumCurrency` (опциональный): Валюта страховой премии. **Пример запроса**: ```json { "data": { "id": "ins_789012", "insuranceCertificateFileContainerId": "cont_", "insuranceCertificateNumber": "CERT-123456", "insuranceCertificateDate": "2025-07-22T20:21:19.773333823Z", "insurancePremium": 1500.0, "insurancePremiumCurrency": "RUB" } } ``` **Пример ответа**: ```json { "data": {} } ``` --- ### Получение файлов страховых сертификатов Для получения файлов страховых сертификатов необходимо выполнить 2 последовательных действия: #### 1. Получить список файлов **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/getInsuranceFiles/v0` Возвращает список всех файлов страхового сертификата для указанного заказа на страхование. **Параметры запроса**: - `id` (query parameter): ID заказа на страхование грузов. **Пример ответа**: ```json { "data": { "files": [ { "id": "if_", "name": "certificate.pdf", "isEnabled": true, "fsId": "fs_" }, { "id": "if_", "name": "certificate2.pdf", "isEnabled": true, "fsId": "fs_" } ] } } ``` Где: - `id` - ID файла в таблице `cargo_insurance.insurance_files` - `name` - Название файла - `isEnabled` - Признак, что файл отправлен в файловое хранилище - `fsId` - Идентификатор файла в файловом хранилище (используется для получения бинарника) --- #### 2. Получить бинарник файла **Эндпоинт**: `POST /api/insurance/cargoInsuranceForInsuranceOrganization/getFile/v0` Возвращает бинарное содержимое файла страхового сертификата. **Параметры запроса**: - `cargoInsuranceOrderId` (обязательный): ID заказа на страхование грузов. - `insuranceFileId` (обязательный): ID файла из таблицы `cargo_insurance.insurance_files` (получен на шаге 1). **Пример запроса**: ```json { "data": { "cargoInsuranceOrderId": "", "insuranceFileId": "if_" } } ``` ## Рекомендации по интеграции - **Регулярный опрос**: Рекомендуется регулярно (например, каждые 5-10 минут) запрашивать обновления заказов через эндпоинт `/api/insurance/cargoInsuranceForInsuranceOrganization/listCargoInsuranceOrdersUpdates/v0`. - **Подтверждение обработки**: После получения обновлений обязательно подтверждайте их обработку через эндпоинт `setCargoInsuranceOrdersUpdatesAcknowledge/v0`, чтобы система не отправляла их повторно при следующем запросе. - **Обработка статусов**: При получении заказов в статусе `awaiting_insurance` необходимо: - Проверить возможность страхования по параметрам заказа - Если невозможно застраховать - установить статус `cancelled_by_insurance_organization` через `/api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersCancelledByInsuranceOrganization/v0` - Если возможно застраховать - установить статус `received_by_insurance_organization` через `/api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersReceivedByInsuranceOrganization/v0` - После завершения процесса страхования установить статус `processed_by_insurance_organization` через `/api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersProcessedByInsuranceOrganization/v0` {% note warning %} Обновления, которые вы делаете, также будут отдаваться в `/api/insurance/cargoInsuranceForInsuranceOrganization/listCargoInsuranceOrdersUpdates/v0` {% endnote %} - **Добавление сертификатов**: После генерации страхового сертификата необходимо добавить его в заказ через эндпоинт `updateCargoInsuranceCertificate/v0`. - **Обработка ошибок**: Всегда проверяйте коды ответов API и корректно обрабатывайте ошибки.