Описание методов API сервиса ЭДО.МИГ24

Точки входа

Тестовая среда - https://test-edo.ntssoft.ru/ Продуктовая среда - https://edo.mig24.online/

Запрос вашего код авторизации АПИ - info@mig24.ru
Telegram поддержки https://t.me/NTSsupport

Тестовый Swagger https://test-edo.ntssoft.ru/api-docs
Продуктовый Swagger https://edo.mig24.online/api-docs

Авторизация

Для доступа к сервису необходимо указать следующий заголовок:
Authorization: Bearer <token>
Токен для авторизации однозначно связан с организацией - Абонентом ЭДО.МИГ24.
Для каждого Абонента необходимо получение своего токена.

Перед запросом доступа Абонент должен зарегистрироваться в сервисе.

Запросить token можно через info@mig24.ru или в Telegram https://t.me/NTSsupport
Предоставление доступа к тестовой среде - бесплатно на 30 дней.
Предоставление доступа к продуктовой среде осуществляется на платной основе. При окончании оплаченного срока (или тестового периода) доступа авторизация возвращает ошибку: "Оплаченный срок доступа истек".



Базовый сценарий работы

swagger

В сервисе используется понятия:
  • Документ - файл с данными
  • Пакет - набор файлов (копия Документа, его подпись, сопутствующие технологические квитанции, титулы и т.п. неразрывно связанные с документом)
  • Группа пакетов - набор Пакетов (по сути документов), имеющих общего отправителя и получателя, передающихся одновременно. Может состоять из одного пакета (документа).

Порядок работы:

Загружаем необходимые для отправки документы, указывая свой идентификатор (GUID) для каждого загружаемого файла:
  • неформализованный - /api/v1/documents/{DocumentId}/informal,
  • формализованный УПД (json) - /api/v1/documents/upd.
  • с авто определением типа - /api/v1/documents/{id}

После загрузки формализованного документа, сервис автоматически выполняет визуализацию этого документа в pdf-формате.
При успешном завершении визуализации формируется идентификатор {id} полученного файла визуализации (id) и передается в очередь сообщений.
При необходимости, запросить визуализацию черновика документа в формате pdf можно через /api/v1/documents/upd/draft-visualization/{id}.

Создаем группу пакетов методом - /api/v1/package-groups, указывая код абонента получателя документов recipientAbonentCode или, если код абонента не известен, заполняем блок recipientOrg (e-mail, название, ИНН, КПП, ОГРН получателя документов), при этом для каждого документа создается Пакет внутри Группы пакетов (т.е. любой документ всегда "завернут" в пакет и далее группу пакетов).
Для каждого документа проставляется отдельным параметром необходимость подписания его получателем.
При необходимости добавить пакеты в уже созданную группу это делается методом - /api/v1/package-groups/{id}/packages.

Подписываем документы:
  • Пользовательским сертификатом: Запрашиваем хеши документов пакета для подписания, передавая сертификат подписанта - /api/v1/sign/package-group/prepare, подписываем хеши на клиенте и завершаем подписание методом - /api/v1/sign/package-group/finish
  • Серверным сертификатом, указав UserId сотрудника, чей сертификат хранится на сервере - /api/v1/sign/package-group/user
  • Сертификатом КЭП сотрудника на его рабочем месте, для этого сервис отправляет ссылку на подписание на e-mail этого сотрудника. Нужно указать идентификатор сотрудника, кто будет подписывать документы - /api/v1/sign/package-group/user.
Идентификатор Сотрудника можно получить методом /api/v1/organization-users

После подписания документов в пакете, для которого был указан ID Абонента, Сервис проверит наличие связи (дружбы) с указанным Абонентом, и если ее нет - Сервис самостоятельно вышлет приглашение этому Абоненту. При наличии установленной связи, или когда Контрагент примет приглашение, сервис опять же самостоятельно отправит подготовленный документ получателю.

После подписания документов в пакете, для которых НЕ был указан ID Абонента, Сервис подготовит ссылку для подписания документов этого пакета Получателем и отправит ее на указанный e-mail получателя в виде письма-уведомления о необходимости подписать документ.
Получатель, пройдя по полученной ссылке сможет на выбор:
  • подписать документ КЭП уполномоченного лица
  • указать нужный (другой) ID Абонента в том сервисе ЭДО, который он использует
  • отказаться от подписания, указав причину и контактные данные для связи.
Сервис подготовит и передаст соответствующее выбранному действию контрагента сообщение в очередь сообщений.

Все статусы обработки документов автоматически передаются Сервисом в индивидуальные очереди сообщений. Так же в эту очередь передаются все факты принятия или отказа приглашений для обмена документами (дружба).

Статусы, которые может принимать пакет

swagger

Работа с документами

swagger

POST Загрузка документа с автоматическим определением типа - -/api/v1/documents/{id}
Id - guid документа, присваивается пользователем самостоятельно.
Используется для загрузки в сервис уже готовых xml.

POST Загрузка неформализованного документа -/api/v1/documents/{Id}/informal
Id - guid документа, присваивается пользователем самостоятельно

POST Создание формализованного документа УПД (json) - /api/v1/documents/upd
Схема json, пример

POST Создание формализованного документа Акт сверки (json) - /api/v1/documents/checking-payments-act
Модель json описана в swagger

GET Получение списка документов, загруженных в сервис - /api/v1/documents
Для авторизовавшегося пользователя.
Возвращается массив сведений о документах: id, название, id файла подписи, дата создания.

GET Получение сведений о документе - /api/v1/documents/{id}

GET Получение документа из сервиса - /api/v1/documents/{id}/file

GET Получение визуализации черновика загруженного документа - /api/v1/documents/upd/draft-visualization/{id}
При загрузке УПД через API выполняется запрос по визуализации документа. При завершении запроса формируется Id, по которому можно скачать PDF файл. Id подготовленного файла присылается в очередь сообщений.

Работа с пакетами документов

swagger

POST Создание группы пакетов документов -/api/v1/package-groups

POST Добавление пакетов в группе пакетов - /api/v1/package-groups/{id}/packages

PUT Обновить группу пакетов - /api/v1/package-groups/{id}

GET Получить список групп пакетов - /api/v1/package-groups

DELETE Удалить группу пакетов - /api/v1/package-groups/{id}

GET Получить информацию о группе пакетов - /api/v1/package-groups/{id}
Результат:
{ "id": "ea51ebce-c0e2-4ee5-9d59-65a45717c6c6", // Идентификатор PackageGroup
 "sender": { // Реквизиты отправителя
  "inn": "1234567891",
  "ogrn": "2222222222221",
  "kpp": "568643355",
  "name": "ООО \"Скверные моторы\""  
},
 "recipient": { // Реквизиты получателя
  "inn": "8857137300",
  "ogrn": "9255392446861",
  "kpp": "998721016",
  "name": "ООО \"Рога и Копыта\""
 },
 "creationDateTime": "2025-06-29T07:11:38.978152Z", // Дата создания
 "packages": [
  {
   "id": "f41d82a2-52ee-4bfc-9028-ee6addf5ef01", // Идентификатор Package
   "name": "УПД", // Наименование пакета
   "providerFileInfo": {
    "packageFileId": "96b4d139-45be-42c3-a400-6c053efc02cf", // Идентификатор PackageFile первичного документа
    "name": "ON_NSCHFDOPPR_2JF-ED5146DE-A98C-42F0-B803-6B971530A01E_XXX-E13FB48B-7E73-4BC0-9650-38C0EA244D2A_20231212_34e852e9-2283-46ed-9969-d98904e19dac_0_0_0_0_0_00.xml",
    "number": "test_updsfaktdop", // Номер документа
    "date": "2025-06-29T07:11:38.978152Z", // Дата документа
    "formalizedDocType": "ProviderUTD" // Тип документа
   },
   "statusId": 4, // Номерной статус пакета
   "statusName": "Подписан", // Наименование статуса пакета
   "creationDateTime": "2025-06-29T07:11:38.978829Z", // Дата создания пакета
   "modificationDateTime": "2025-06-29T07:15:18.812369Z" // Дата модификации пакета
  }
 ]
}

GET Получить информацию о пакете - /api/v1/packages/{id}/info
Результат:
{
 "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "name": "Счет-Фактура", <- Именование документа/пакета
 "providerDocumentNumber": "string",
 "providerDocumentDateTime": "2025-09-12T12:41:18.665Z",
 "sender": {
  "inn": "string",
  "ogrn": "string",
  "kpp": "string",
  "name": "string",
  "code": "string"
 },
 "recipient": {
  "inn": "string",
  "ogrn": "string",
  "kpp": "string",
  "name": "string",
  "code": "string"
 },
 "creationDateTime": "2025-09-12T12:41:18.665Z",
 "modificationDateTime": "2025-09-12T12:41:18.665Z",
 "statusId": 0,
 "status": "string",
 "statusName": "string",
 "packageFiles": [
  {
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "fileName": "string",
   "isWaitRecipientSignature": true,
   "isProviderFile": true,
   "isCustomerFile": true,
   "fileType": "Unknown",
   "contentType": "string",
   "formalizedDocType": "None",
   "nonFormalizedDocType": "NonFormalized",
   "serviceDocType": "None",
   "documentNumber": "string",
   "documentDateTime": "2025-09-12T12:41:18.665Z",
   "senderAbonentCode": "string",
   "recipientAbonentCode": "string"
  }
 ]
}

GET Получение списка возможных действий с пакетом - /api/v1/packages/{id}/actions
Возвращает список возможных действий в виде json
Пример json:
{ "packageId": "e569cb00-43c0-4070-8d13-80b867c60e0e",
 "actions": [   {    "type": "AddSenderSign", - тип действия
   "isAvailable": false - признак возможно ли действие   },
  {    "type": "AddCancellation",
   "isAvailable": false   },
  {   "type": "AddCancellationAccept",
   "isAvailable": false   },
  {    "type": "AddCancellationRefuse",
   "isAvailable": false  }
 ]}
Методы создания действий с пакетом:
Сформировать Извещение о получении
Тип действия - AddReceiptNotice
POST /api/v1/packages/{id}/actions/receipt-notice

Сформировать Уведомление об уточнении
Тип действия - AddClarification
POST /api/v1/packages/{id}/actions/clarification

Сформировать 2-й титул УПД
Тип действия - AddSecondTitle
POST /api/v1/packages/{id}/actions/utd-second-title

Сформировать подпись получателя неформализованного документа
Тип действия - AddRecipientSign
POST /api/v1/packages/{id}/actions/recipient-sign

Сформировать Предложение об аннулировании
Тип действия - AddCancellation
POST /api/v1/packages/{id}/actions/cancellation-offer

Принять предложение об аннулировании (сформировать ответную подпись)
Тип действия - AddCancellationAccept
POST /api/v1/packages/{id}/actions/accept-cancellation

Отказать в предложении об аннулировании (сформировать УоУ)
Тип действия - AddCancellationRefuse
POST /api/v1/packages/{id}/actions/refuse-cancellation

Методы возвращают Json со следующим содержанием:
json {
 "packageActionId": "8188f66d-0329-4c7b-b285-4b817293b086", - Идентификатор действия
 "actionStatus": "SigningExpected", - Статус действия
 "signingRequests": [ - Запросы на подписание
  {    "id": "251bacb6-fb1c-49d2-ad11-4fc35e2824e9"   }  ] }

GET Скачать файлы пакета архивом - /api/v1/packages/{id}/files

GET Скачать выбранный файл из пакета - /api/v1/packages/{id}/files/{packageFileId}

GET Скачать первичный файл пакета - /api/v1/packages/{id}/provider-file

GET Запросить текущий статус пакета асинхронно - /api/v1/packages/{id}/status/async


Подписание документов

swagger

В ближайшее время методы sign будут заменены на SigningRequest
Предоставление сертификата КЭП подписанта, запрос хеша документов для подписания
Шаг 1 POST /api/v1/sign/package-group/prepare
Подписание полученного хеша документов на стороне внешней ИС, отправка подписей хешей в сервис, завершение формирования подписей документов
Шаг 2 POST /api/v1/sign/package-group/finish

POST Подписать группу пакетов серверным сертификатом по идентификатору сотрудника - /api/v1/sign/package-group/user
Указывается идентификатор сотрудника


Подписание документа - SigningRequest
Шаг1 POST /api/signing-transactions/prepare - Метод получения hash документов, требующих подписания
Шаг2 POST /api/signing-transactions/finish - Финальный метод подписания, принимает подпись hash

Методы выполняют подписания файлов хранящихся в запросах на подписания "SigningRequest", которые создаются вместе со созданием PackageAction


Проверка подписи документа

swagger

При получении сервисов подписи документа (хоть входящего, хоть исходящего) автоматически запускается ее проверка. По итогу проверки формируется событие в очередь "Завершение проверки подписи документа - GET /api/v1/events/signature-validation-complete"
Для каждого события передается:

"EventId": Идентификатор события
"Id": Идентификатор проверки
"PackageId": Идентификатор Пакета
"PackageFileId": Идентификатор подписанного документа
"PackageSignatureId": Идентификатор файла подписи
"CreationDateTime": дата время проведения проверки
"ModificationDateTime": Дата время изменения проверки
"Status": код статуса проверки
"StatusString": текст статуса проверки
(3 -Проверка пройдена, подпись валидна, 4 - Проверка пройдена, подпись невалидна, 5 - Проверка не пройдена, возникли ошибки при проверке)

GET Получение расширенных результатов проверки подписи - /api/v1/validation/{id}
Возвращается общий статус проверки, информация о подписанте, а также результат проведения 13 возможных проверок.

POST Создание новой проверки подписи документа - /api/v1/validation
"packageId": Идентификатор пакета,
"packageFileId": Идентификатор документа в пакете
"isSender": true/false - запросить подпись отправителя или получателя

GET Получение списка проверок для пакета - /api/v1/validation/packages/{packageId}

Списки контрагентов и приглашения

swagger

Для того, чтобы можно было обмениваться документами, необходимо обменяться приглашениями
Для этого сторонами высылаются приглашения, которые могут быть в сервисе в разных статусах:
New - приглашение сформировано, не отправлено/ Sent - приглашение отправлено / Delivered - приглашение доставлено / Accepted - приглашение принято / Rejected - приглашение отклонено.

POST - Отправить приглашение к ЭДО - /api/v1/counteragent-requests
Отправляются Идентификатор ЭДО, ИНН/КПП/ОГРН/Название/email получателя приглашения, внутреннее примечание, комментарий для получателя.

GET Получить все входящие приглашения - /api/v1/counteragent-requests/inbox
Ответом является массив данных, содержащих информацию из приглашений: Id Абонента, название, ИНН, КПП сторон, комментарии, статус и его дата.

GET Получить все исходящие приглашения - /api/v1/counteragent-requests/outbox
Ответом является массив данных, содержащих информацию из приглашений: Id Абонента, название, ИНН, КПП сторон, комментарии, статус и его дата.

GET Получить список контрагентов, для которых установлен обмен - /api/v1/counteragents
Ответом является массив данных, содержащих список контрагентов, с которыми успешно завершен обмен приглашениями (ID Абонента, название, ИНН, КПП, дата, idКонтрагента в сервисе)

Получение события успешного добавления контрагента (успешный обмен приглашениями) и отказа принять приглашение (или разрыв существующей связи) осуществляется через сервис очередей или сервис очередей RabbitMQ



Сотрудники

swagger

GET Получить информацию о сотрудниках организации -/api/v1/organization-users
Возвращается массив данных: Id сотрудника, СНИЛС, ФИО, название серверного контейнера КЭП, должность

GET Получить сведения по сотруднику - /api/v1/organization-users/{userId}
"userId": "b25fb305-e1ca-480e-89bc-27ee31ed5d65", "snils": "15989387255", "organizationId": "95e84dfb-0ca7-4511-b33a-14cd3bc8364c", "isAdmin": true, "canCreateDocs": false, "canDeleteAndRestoreDocs": false, "canSignDocs": false, "canAgreeDocs": false, "canSignDocsByAnotherUser": false, "isRequireAuthenticationForFileAccess": true, "isRequireSameOrganizationForFileAccess": true, "canEditContractors": false, "mchdInfoId": null, "certContainerName": null, "position": null



Сервисные функции

swagger

GET Получение информации об операторах ЭДО, с кем возможен обмен - /api/v1/operators
Массив сведений об операторах:
"code", "companyName", "productName", "inn", "kpp"

GET Получение данных Контрагента по коду Абонента - /api/v1/abonents/{code}/requisites
Если доступ к указанному коду открыт в ФНС, сервис вернет реквизиты данного Абонента

GET Получение списка известных ФНС кодов Абонента - /api/v1/abonents/by-requisites
По ИНН вернется список всех известных ФНС кодов Абонента у различных операторов ЭДО (для всех КПП этого ЮЛ), включая комментарии к коду, при их наличии, статус активности абонента (0 –неактивный, 1 – малоактивный, 2 – активный, 3 – новый) и перечень лиц, для которых зарегистрированы в ФНС их сертификаты КЭП (ФИО). При необходимости можно сузить запрос, указав дополнительно КПП.

GET Получение информации о привязанном к токену Абоненте - /api/v1/abonents/me
При успешном выполнении возвращает следующий JSON:
{
 "id": "527dc1fd-96c4-46f3-b73d-272a7aabc0bf", // Идентификатор абонента
 "orgId": "ed5146de-a98c-42f0-b803-6b971530a01e", // Идентификатор организации абонента
 "inn": "8857137300", // ИНН
 "ogrn": "9255392446861", // ОГРН
 "kpp": "998721016", // КПП
 "name": "ООО \"Рога и Копыта\"", // Наименование организации
 "code": "2JF-ED5146DE-A98C-42F0-B803-6B971530A01E" // Код абонента организации
}

POST Проверка кодов маркировки в ИС Честный знак - /api/v1/mark-produkt/check-codes
Принимает на вход массив кодов маркировки
Ответ:
[ {
"code": "01046363324553462151AhFPC",
"found": true, //Признак наличия КМ в ГИС МТ
"type": "Cis",
"groups": [ 15 ],
"productGroupInfos": [ { "code": 15, "name": "beer", "description": "Пиво, напитки, изготавливаемые на основе пива, слабоалкогольные напитки" } ],
"valid": true,
"printView": "01046363324553462151AhFPC" //Структура КМ для передачи в ЭДО-документах
}]

type:
• cis - код маркировки товара (групповой или обычный код идентификации);
• sscc - код идентификации транспортной упаковки;
• atk - агрегированный таможенный код.

productGroupInfos: человекочитаемое описание группы товаров

POST Подключение нового Абонента Интегратором - /integration-api/v1/tokens
Метод предназначен для создания новых Абонентов.
Необходимо передать набор сведений:
{
"certificate": "string", // сертификат КЭП сотрудника Абонента, строка в base64
"organizationType": "string", UL / IP / SZ / FL
"kpp": "string", КПП для ЮЛ
}
Возвращается код доступа (токен) к API от имени созданного Абонента.


Очередь обмена сообщениями API

swagger

Все сообщения, подготовленные сервисом для пользователя помещаются в соответствующие отдельные очереди событий.

Существуют следующие очереди:
Возвращается список последних (25 штук по умолчанию) событий
Тело ответа:
{ "meta": { "totalCount": 0, "currentPage": 2, "limit": 10 }, "data": [] }


В каждом событии есть уникальное поле eventId.

Метод POST /api/v1/events/<eventId>/ack подтверждает получение конкретного события.
Метод POST /api/v1/events/ack подтверждает получение списка событий.

После подтверждения получения событие не отображается в очереди.


Очередь обмена сообщениями Rabbit

Брокер сообщений — программное обеспечение и определённый архитектурный паттерн, который позволяет выстроить действия в информационных системах таким образом, чтобы обеспечить асинхронный обмен сообщениями между сервисами.

Асинхронный обмен предполагает отправку запроса или сообщения от одного сервиса к другому, при этом деятельность сервиса-отправителя не приостанавливается в ожидании ответа от получателя. Также обеспечивается надежная доставка, если произошла перезагрузка брокера или клиента, то сообщение никуда не пропадет и будет доставлено.

Мы используем RabbitMQ. Клиенты есть для всех популярных языков - https://www.rabbitmq.com/client-libraries/devtools

Подключение:
  • Сообщаете нам ip-адрес, с которого будете осуществлять работу.
  • Мы создаем пользователя (логин и пароль) и vhost. vhost - абстракция, где хранятся очереди и сообщения только для конкретного пользователя.
  • Выдаем Вам логин, пароль, vhost и адрес сервера. Очереди уже будут созданы и будут получать сообщения с событиями системы
  • Вы выбираете библиотеку для подключения, указывает хост, логин, пароль и vhost и название очереди, из которой должны считываться сообщения. Пример в документации (раздел Subscribe - https://www.rabbitmq.com/tutorials#3-publishsubscribe)

Сценарий многостороннего подписания
swagger

Сервис позволяет организовать процесс многостороннего подписания загруженного документа сотрудниками организаций - Абонентами ЭДО.МИГ24.
Блок методов в swagger- Mig24SharedFileApi

GET /api/v1/mig24/users - Запрос идентификатора подписанта как сотрудника необходимой организации или как физического лица. По СНИЛС предоставляется перечень организаций, в которых указанное лицо добавлено в сервисе ЭДО.МИГ24 как сотрудник.
Для каждой найденной записи возвращается:
Сведения о подписанте ("id": идентификатор, "name": ФИО, "snils": СНИСЛ, "inn": ИНН, "email":email, "phone": телефон) и сведения об организации "organization": { "id": идентификатор", "name": названия, "ogrn": ОГРН, "inn": ИНН, "kpp": КПП}

POST /api/v1/mig24/files/{id} - Загрузка необходимого файла на сервер.
Указывается идентификатор (guid)

POST /api/v1/mig24/shared-file Подготовка документа к подписанию.
Необходимо подготовить запрос
"fileId": Идентификатор(ы) загруженного файла, который необходимо подписать,
"targetSignatureType": формат подписи "Detached" открепленная,
"signerRequirements": - перечень подписантов {
"signerOrgUserId": идентификатор подписанта,
"notificationEmail": email подписанта -при указания данного параметра сервис отправит на указанный email уведомления о необходимости подписать документ }
"signatureSettings": параметры подписи {
"isBase64": true -подпись в pem формате,
"isOneLine": true - подпись в base64 в одну строку,
"cadesType": "cadesbes" - ,
"extractFromZip": true - подписать все файлы в архиве,
"typeSigning": "Parallel" - (Sequential,Parallel) последовательное или параллельное подписание,
"isPaid": true - проставление признака оплаты подписания документа (необходимое для оплаты количество пакетов спишется с организации, инициатора подписания)
"organizationId": идентификатор организации - инициатора подписания.

После успешного выполнения метода возвращается набор параметров:
"registryInfoId": идентификатор документа (пакета), подготовленного к подписанию
"url": ссылка на страницу подписания.
Документ появляется в специальной папке в сервисе ЭДО у каждого из указанных подписантов с возможностью подписания этого документа в сервисе.

При необходимости подгрузить КЭП к загруженному для подписания файлу, созданную не в сервисе ЭДО.МИГ24 можно, предварительно загрузив файл подписи через POST /api/v1/mig24/files/{id}, использовать метод POST /api/v1/mig24/shared-file/append { "userFileInfos": [ { "sourceUserFileId": идентификатор подписанного файла, "userFileId": идентификатор файла загруженной подписи, "userFileType": DetachedSig - описание типа загруженного файла, "signerOrgUserId": идентификатор подписанта } ], "sharedFileId": идентификатор подготовленного для подписания файла (пакета)}
При добавлении подписи этим методом сервис проверит корректность этой подписи, действительность сертификата КЭП и при положительном результате присоединит эту подпись к документу в сервисе.

После каждого успешного получения подписи сервис формирует соответствующее событие в очередь подписания GET /api/v1/events/mig24-signature-completed
В событии можно получить
"EventId": идентификатор события, "SharedFileId": идентификатор подписанного документа, "SignatureUserFileId": идентификатор файла подписи, "SignerOrgUserId": идентификатор подписанта, "CreationDateTime": дата время подписания" },
После успешного получения информации о событии необходимо подтвердить получение методом POST /api/v1/events/{eventId}/ack или POST /api/v1/events/ack

Нужный файл подписи скачивается GET /api/v1/mig24/files/{id}/file

Архив, содержащий подписываемый документ и все файлы подписей, сформированные на момент запроса можно скачать - GET /api/v1/mig24/shared-file/{id}/last-file

После завершения подписания документа всеми сторонами можно скачать подготовленную в pdf справку-отчет POST /api/v1/mig24/shared-file/{sharedFileId}/report.