Обработка заказов по страхованию груза по API

Данный документ описывает процесс интеграции с API системы Магистрали для обработки заказов на страхование грузов.

Полезные ссылки

Описание API

Для описания интеграции с API Магистрали используется OpenAPI спецификация.

Спецификацию можно найти здесь.
Для тестирования и разработки используйте демонстрационный стренд здесь.

Диаграмма состояний заказов

Для лучшего понимания процесса интеграции, ниже представлена диаграмма состояний заказов на страхование груза:

Состояния заказов

Отображаемое имя	Состояние (API)	Описание
Черновик	`draft`	Заказ находится в разработке у клиента
Ожидает страхования	`awaiting_insurance`	Заказ отправлен и ожидает обработки страховой организацией
Получен страховой организацией	`received_by_insurance_organization`	Страховая организация получила заказ и начала обработку
Обработан страховой организацией	`processed_by_insurance_organization`	Страховая организация завершила обработку заказа
Отменён клиентом	`cancelled_by_customer`	Клиент отменил заказ
Отказ от страховой организации	`cancelled_by_insurance_organization`	Страховая организация отказалась от страхования

Общий процесс интеграции

Регулярно запрашивайте обновления заказов на страхование груза
Подтверждайте получение обновлений
Обрабатывайте заказы в статусе awaiting_insurance
Обновляйте статусы заказов в системе
При необходимости, добавляйте страховые сертификаты

Описание API эндпоинтов

Получение обновлений заказов

Эндпоинт: POST /api/insurance/cargoInsuranceForInsuranceOrganization/listCargoInsuranceOrdersUpdates/v0

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

Параметры запроса:

limit (опциональный): Количество обновлений. Если не указан, то возвращаются 100 обновлений.

Пример запроса:

{
    "data": {
        "limit": 100
    }
}

Пример ответа:

{
    "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 запросов.

Пример запроса:

{
    "data": {
        "ids": ["ins_789012"],
        "limit": 1000
    }
}

Пример ответа:

{
    "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: Идентификаторы обновлений, которые были обработаны.

Пример запроса:

{
    "data": {
        "updateIds": ["upd_123456"]
    }
}

Установка статуса "Получен страховой организацией"

Эндпоинт: POST /api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersReceivedByInsuranceOrganization/v0

Указание, что запросы на страхование грузов получены страховой организацией.

Параметры запроса:

ids: Идентификаторы запросов на страхование грузов.

Пример запроса:

{
    "data": {
        "ids": ["ins_789012"]
    }
}

Установка статуса "Обработан страховой организацией"

Эндпоинт: POST /api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersProcessedByInsuranceOrganization/v0

Указание, что запросы на страхование грузов обработаны страховой организацией.

Параметры запроса:

ids: Идентификаторы запросов на страхование грузов.

Пример запроса:

{
    "data": {
        "ids": ["ins_789012"]
    }
}

Установка статуса "Отказ от страховой организации"

Эндпоинт: POST /api/insurance/cargoInsuranceForInsuranceOrganization/setCargoInsuranceOrdersCancelledByInsuranceOrganization/v0

Указание, что запросы на страхование грузов отменены страховой организацией.

Параметры запроса:

ids: Идентификаторы запросов на страхование грузов.

Пример запроса:

{
    "data": {
        "ids": ["ins_789012"]
    }
}

Добавление страхового сертификата

Эндпоинт: POST /api/insurance/cargoInsuranceForInsuranceOrganization/updateCargoInsuranceCertificate/v0

Обновление параметров страхового сертификата или полиса.

Параметры запроса:

id (обязательный): Идентификатор запроса на страхование грузов.
insuranceCertificateExternalId (опциональный): Внешний ID страхового сертификата.
insuranceCertificateNumber (опциональный): Номер страхового сертификата.
insuranceCertificateDate (опциональный): Дата страхового сертификата.
insuranceCertificateExternalLink (опциональный): Ссылка на страховой сертификат.
insuranceCertificateFileContainerId (опциональный): ID контейнера с файлами сертификата (см. раздел "Загрузка файлов сертификата").
insurancePremium (опциональный): Страховая премия.
insurancePremiumCurrency (опциональный): Валюта страховой премии.

Если какой-то параметр не передан, он не будет обновлен.

Пример запроса:

{
    "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 день.

Пример запроса:

{
    "data": {}
}

Пример ответа:

{
    "data": {
        "id": "cont_<container_id>"
    }
}

Важно

Для каждого заказа на страхование нужен отдельный контейнер с файлами. Контейнеры не переиспользуемые.

2. Добавить файлы в контейнер

Эндпоинт: POST /api/storage/container/addFiles/v0

Загружает файлы в созданный контейнер. Файлы передаются в формате multipart/form-data.

Параметры запроса:

containerId (form-data): ID контейнера, полученный на шаге 1.
files (form-data, массив файлов): Файлы для загрузки.

Пример ответа:

{
    "data": {
        "files": {
            "filename1.pdf": "fs_<file_id_1>",
            "filename2.pdf": "fs_<file_id_2>"
        }
    }
}

Пример запроса:

curl -X POST https://yamagistrali.ru/api/storage/container/addFiles/v0 \
  -H "Authorization: Bearer <token>" \
  -F "containerId=cont_<container_id>" \
  -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 (опциональный): Валюта страховой премии.

Пример запроса:

{
    "data": {
        "id": "ins_789012",
        "insuranceCertificateFileContainerId": "cont_<container_id>",
        "insuranceCertificateNumber": "CERT-123456",
        "insuranceCertificateDate": "2025-07-22T20:21:19.773333823Z",
        "insurancePremium": 1500.0,
        "insurancePremiumCurrency": "RUB"
    }
}

Пример ответа:

{
    "data": {}
}

Получение файлов страховых сертификатов

Для получения файлов страховых сертификатов необходимо выполнить 2 последовательных действия:

1. Получить список файлов

Эндпоинт: POST /api/insurance/cargoInsuranceForInsuranceOrganization/getInsuranceFiles/v0

Возвращает список всех файлов страхового сертификата для указанного заказа на страхование.

Параметры запроса:

id (query parameter): ID заказа на страхование грузов.

Пример ответа:

{
    "data": {
        "files": [
            {
                "id": "if_<insurance_file_id>",
                "name": "certificate.pdf",
                "isEnabled": true,
                "fsId": "fs_<file_storage_id>"
            },
            {
                "id": "if_<insurance_file_id_2>",
                "name": "certificate2.pdf",
                "isEnabled": true,
                "fsId": "fs_<file_storage_id_2>"
            }
        ]
    }
}

Где:

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).

Пример запроса:

{
    "data": {
        "cargoInsuranceOrderId": "<cargo_insurance_order_id>",
        "insuranceFileId": "if_<insurance_file_id>"
    }
}

Обработка заказов по страхованию груза по API

Полезные ссылкиПолезные ссылки

Описание APIОписание API

Диаграмма состояний заказовДиаграмма состояний заказов

Состояния заказовСостояния заказов

Общий процесс интеграцииОбщий процесс интеграции

Описание API эндпоинтовОписание API эндпоинтов

Получение обновлений заказовПолучение обновлений заказов

Получение деталей заказовПолучение деталей заказов

Подтверждение получения обновленийПодтверждение получения обновлений

Установка статуса "Получен страховой организацией"Установка статуса "Получен страховой организацией"

Установка статуса "Обработан страховой организацией"Установка статуса "Обработан страховой организацией"

Установка статуса "Отказ от страховой организации"Установка статуса "Отказ от страховой организации"

Добавление страхового сертификатаДобавление страхового сертификата

Загрузка файлов сертификатаЗагрузка файлов сертификата

1. Создать контейнер для файлов1. Создать контейнер для файлов

2. Добавить файлы в контейнер2. Добавить файлы в контейнер

3. Привязать контейнер к страховому заказу3. Привязать контейнер к страховому заказу

Получение файлов страховых сертификатовПолучение файлов страховых сертификатов

1. Получить список файлов1. Получить список файлов

2. Получить бинарник файла2. Получить бинарник файла

Рекомендации по интеграцииРекомендации по интеграции

Полезные ссылки

Описание API

Диаграмма состояний заказов

Состояния заказов

Общий процесс интеграции

Описание API эндпоинтов

Получение обновлений заказов

Получение деталей заказов

Подтверждение получения обновлений

Установка статуса "Получен страховой организацией"

Установка статуса "Обработан страховой организацией"

Установка статуса "Отказ от страховой организации"

Добавление страхового сертификата

Загрузка файлов сертификата

1. Создать контейнер для файлов

2. Добавить файлы в контейнер

3. Привязать контейнер к страховому заказу

Получение файлов страховых сертификатов

1. Получить список файлов

2. Получить бинарник файла

Рекомендации по интеграции