Перейти в сервис
ЭДО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

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

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

Загружаем необходимые для отправки документы, указывая свой идентификатор (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 Абонента в том сервисе ЭДО, который он использует
  • отказаться от подписания, указав причину и контактные данные для связи.
Сервис подготовит и передаст соответствующее выбранному действию контрагента сообщение в очередь сообщений.

Все статусы обработки документов автоматически передаются Сервисом в индивидуальную очередь сообщений в 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

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

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

Получить информацию об операторах, с которыми установлена роуминговая связь - /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)

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