Перейти в сервис
ЭДО24
2008—2024. ООО «НТСсофт». Электронная подпись документов. Включен в реестр Российского программного обеспечения.
Перейти в сервис

Описание методов 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

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

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

После загрузки формализованного документа (УПД), сервис автоматически выполняет запрос по визуализации документа. При завершении запроса формируется и передается в очередь сообщений для Организации Id pdf файла визуализации. При необходимости, запрашиваем визуализацию черновика документа в формате 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
  • Отправляем ссылку на подписание нужному сотруднику, указав идентификатор сотрудника, кто будет подписывать документы - /api/v1/sign/package-group/user.
Идентификатор Сотрудника можно получить методом /{orgId}/users

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

При отсутствии кода Абонента, Сервис подготовит ссылку для подписания загруженных документов и отправит ее на указанный e-mail получателя.
Получатель, пройдя по ссылке сможет: подписать документ / указать нужный код Абонента в том сервисе ЭДО, который он использует / отказаться от подписания, указав причину и контактные данные для связи.
Сервис подготовит и передаст соответствующее выбранному действию контрагента сообщение в очередь.

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

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

swagger

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

Загрузка формализованного документа УПД (через json) - /api/v1/documents/upd.
Модель json описана в swagger

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

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

Получение файла из сервиса - /api/v1/documents/{id}/file

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

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

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

swagger

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

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

Обновить группу пакетов - /api/v1/package-groups/{id}
Метод Put
Удалить группу пакетов - /api/v1/package-groups/{id}
Метод Delete

Получить информацию о группе пакетов - /api/v1/package-groups/{id}/info

Получить информацию о пакете - /api/v1/packages/{id}/info

Скачать файлы пакета - /api/v1/packages/{id}/files

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

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

swagger

Подготовка к подписанию группы пакетов - получение хэшей документов - /api/v1/sign/package-group/prepare

Финальный метод подписания группы пакета - формирование подписей документов - /api/v1/sign/package-group/finish

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

Подписать группу пакетов серверным сертификатом по имени контейнера - /api/v1/sign/package-group
Указывается имя контейнера и при необходимости идентификатор МЧД

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

swagger

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

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

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

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

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


Сотрудники

swagger

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

Получить сведения по сотруднику - /api/v1/orgs/{orgId}/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

Получить информацию об операторах, с которыми установлена роуминговая связь - /api/v1/operators
Массив сведений об операторах:
"code", "companyName", "productName", "inn", "kpp"

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

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

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

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

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

Событие - название очереди:
Контрагенты
Пакеты
Визуализация