Обмен пакетами
Информация о разделе
Страница содержит сценарии использования API для обмена пакетами документов.
Общая информация
Пакет — набор документов, объединенных одним общим идентификатором пакета. Идентификатор пакета представляет собой 36-символьный уникальный номер UUID (Universally Unique Identifier), присваиваемый пакету системой интегратора.
Ограничения на объединение и отправку документов в пакете:
- Размер файла каждого документа в пакете не превышает 60 Мб.
- Получателем всех документов пакета является один контрагент (ИдЭДО), с которым у отправителя настроена связь
Примечание — ограничений на количество документов в одном пакете нет.
При работе с пакетом документов доступны следующие действия:
- Создать пакет документов (Импортировать и отправить пакет документов)
- Добавить документ в пакет
- Удалить документ из пакета
- Получить состав пакета (черновика)
- Отправить документ в составе пакет
- Получить информацию об исходящем/входящем пакете
Работа с пакетами
[Обязательно] Создать пакет документов.
Для формирования пакета следует воспользоваться методом [POST]/api/v3/drafts или [POST]/api/v3/drafts/withoutModify, указав в параметре PackageId идентификатор пакета. Вызов метода позволит поочередно загрузить документы в виде черновиков и, если во входных параметрах передан идентификатор пакета, то будет создан пакет документов, куда можно будет добавлять черновики, так же указывая идентификатор уже сформированного пакета.
ВАЖНО: Если в качестве входных параметров будет дополнительно передана открепленная подпись к каждому документу, то после успешного подписания всех документов пакета, они будут переданы указанному получателю.
Если используется метод импорта документа с возможностью модификации, в качестве входных параметров для метода загрузки черновика, который требуется добавить в пакет, необходимо передать:
- идентификатор организации (ИдЭДО абонента),
- файл черновика для импорта в систему,
- индикатор, показывающий, что черновик доступен только на чтение (по умолчанию значение равно false),
- идентификатор пакета (если пакета еще не существует, то он будет создан),
- (необязательно) внутренние идентификаторы контрагентов-получателей (ИдЭДО контрагента),
- признак необходимости ответной подписи (данный флаг имеет значение только для НЕформализованного документооборота).
Если используется метод импорта документа без возможности модификации, в качестве входных параметров для метода загрузки черновика, который требуется добавить в пакет, необходимо передать:
- (необязательно) номер доверенности (МЧД),
- (необязательно) файл подписи,
- идентификатор организации (ИдЭДО абонента),
- файл черновика для импорта в систему,
- индикатор, показывающий, что черновик доступен только на чтение (по умолчанию значение равно false),
- идентификатор пакета (если пакета еще не существует, то он будет создан),
- (необязательно) внутренние идентификаторы контрагентов-получателей (ИдЭДО контрагента),
- признак необходимости ответной подписи (данный флаг имеет значение только для НЕформализованного документооборота).
При использовании метода импорта документа без возможности модификации, если дополнительно передается электронная подпись к документу, она должна пройти следующие проверки:
- ЭП пользователя не отозвана
- ЭП имеет актуальный срок действия
- Сертификат ЭП выпущен аккредитованным УЦ
- ЭП принадлежит текущему абоненту
- ЭП соответствует документу, к которому она передана
При использовании метода импорта документа без возможности модификации, если дополнительно передается машиночитаемая доверенность к подписи, она должна пройти следующие проверки:
- МЧД входит в состав используемых МЧД
- МЧД не просрочена
- МЧД не аннулирована
- МЧД соответствует подписи
При успешной инициализации запроса, первым этапом проверяются обязательные параметры. Если проверка входных параметров не пройдена, то сервер вернет ошибку с HTTP-кодом 40х и текстовым описанием причины в теле ответа (См. таблицу 1). Затем проверяются загруженные документы на наличие расхождений в сведениях об отправителе и получателе. В случае выявления расхождений, сервер вернет ошибку с HTTP-кодом 400 и текстовым описанием причины в теле ответа (См. таблицу 2). Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200.
Если используется метод импорта документа с возможностью модификации, то в положительном ответе будут присутствовать следующие данные:
- Идентификатор импортированного черновика
- Признак изменения сведений об отправителе в документе
- Признак изменения сведений о получателе в документе
- Сообщение об изменениях в загруженном черновике (если есть)
- Тип документа
- Список получателей (если есть)
- Ошибка при попытке импорта (если есть)
Если используется метод импорта документа без возможности модификации, то в положительном ответе вернется только идентификатор загруженного черновика.
Таблица 1. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Аккаунт пользователя не содержит абонента с указанным идентификатором |
| У черновика не указан получатель | Формат данных невалидный, либо отсутствует связь с указанным получателем |
| Отсутствует импортируемый документ Не указано наименование файла | Отсутствуют файлы |
Таблица 2. Ошибки при расхождениях в документах
| Описание ошибки | Причина |
|---|---|
| Некорректное имя файла | Имя загружаемого файла не соответствует ожидаемому (Проверить в имени файла ИД отправителя и получателя) |
| Идентификатор отправителя '2AE508FED8B-2245-48C4-8D73-BCFED3DC30EB', ожидалось '2AE8BA5442D-B1F3-460C-8293-1A98947EF9C7' | Указанный в документе отправитель отличается от текущего |
| ИНН отправителя '966848963411', ожидалось '9648276693' | ИНН отправителя указанный в документе отличается от того, от которого выполняется попытка загрузки документа |
| Получатель не найден | В документе указан получатель, с которым не настроена связь |
| Некорректный формат идентификатора ИДЭДО получателя. Значение 1658087524_720601001 содержит недопустимые символы; Некорректные сведения об операторе ЭДО, ожидалось: <СвОЭДОтпр НаимОрг=\"АО Калуга Астрал\" ИННЮЛ=\"4029017981\" ИдОперЭДО=\"2AE\" />. | Документ не прошёл проверку по xsd схеме |
| Получатель документа не указан или не совпадает с получателем пакета | Получатель документа не указан или не совпадает с получателем пакета |
Диаграмма метода по добавлению документа в пакет
[Опционально] Удаление документа из пакета
Для удаления документа из пакета необходимо вызвать метод [PATCH]/api/v1/packages/{packageId}/drafts/{draftId}/remove, который переместит документ из состава пакета в реестр "Черновики". В результате успешной проверки входных параметров документ, из состава пакета, будет перемещен в реестр "Черновики".
В противном случае, сервер вернет ошибку с описанием в теле ответа. (См. таблицу 3).
Таблица 3. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId}. | Указанный идентификатор абонента не найден в учетной записи пользователя |
| Сущность DraftDocument с ключом {draftId} не найдена. | Не найден идентификатор документа, который необходимо удалить из пакета. Не найден идентификатор пакета, из которого необходимо удалить документ |
Диаграмма метода по удалению документа из пакета
[Обязательно] Отправка документа в составе пакета
Для отправки подписанного документа необходимо выполнить запрос с помощью метода [POST]/api/v2/drafts/{draftId}/dispatch, который вернет идентификатор получателя документа и идентификатор запущенного документооборота в модели StartedDocflow.
В случае неуспешной проверки входных параметров сервер вернет ошибку с описанием в теле ответа. (См. таблицу 4).
Таблица 4. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId}. | Указанный идентификатор абонента не найден в учетной записи пользователя |
| Документ не готов к отправке. | Документ уже отправлен |
| Ошибка отправки документа. Нет подписи. | Документ не подписан ЭП |
| Сущность DraftDocument с ключом {draftId} не найдена. | Документ не найден |
Диаграмма метода по отправке документа в составе пакета
Если к документу не прикреплена ЭП, необходимо вызвать метод [POST]/api/v2/drafts/{draftId}/sign, который подпишет черновик документа.
При успешной проверке входных параметров, будет выполнена проверка ЭП, в результате вернется модель AttachSignatureResult с информацией о валидности подписи. Если ЭП валидна, то она будет прикреплена к документу, иначе будет указана причина невалидности ЭП.
В случае неуспешной проверки входных параметров сервер вернет ошибку с описанием в теле ответа. (См. таблицу 5.)
Таблица 5. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Произошла ошибка прикрепления подписи: Невозможно прикрепить подпись к данному черновику! | Для документа не выбран получатель (актуально для документов не в составе пакета) |
| Идентификатор абонента не указан. | Не передан идентификатор абонента |
| Отсутствует подпись. | Не передана ЭП |
| Произошла ошибка прикрепления подписи: Для черновика {draftId} подпись неверна. | ЭП не соответствует документу |
| Пользователь {userId} не имеет доступа к абоненту {abonentId}. | Указанный идентификатор абонента не найден в учетной записи пользователя |
| Сущность DraftDocument с ключом {draftId} не найдена. | Не найден идентификатор документа, к которому необходимо прикрепить ЭП |
Диаграмма метода по подписанию документов
Получение информации по пакету
[Опционально] Получение состава пакета по его идентификатору
Для получения состава пакета, находящегося в реестре "Черновики", необходимо вызвать метод [GET]/api/v1/packages/{packageId}/drafts, который вернет информацию обо всех документах, принадлежащих пакету. В результате успешного запроса метод вернет модель DraftPackageInfo, которая будет содержать число документов в пакете и модель DraftDocument, где будет подробная информацию о каждом документе.
В противном случае, сервер вернет ошибку с описанием в теле ответа. (См. таблицу 6).
Таблица 6. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Идентификатор абонента не указан. | Не передан идентификатор абонента |
| Пользователь {userId} не имеет доступа к абоненту {abonentId}. | Указанный идентификатор абонента не найден в учетной записи пользователя |
| Пакет не существует. | Не найден идентификатор пакета |
Диаграмма метода по получению состава пакета по его идентификатору
[Опционально] Получение информации об исходящем/входящем пакете
Для получения состава исходящего/входящего пакета необходимо вызвать метод [GET]/api/v1/packages/{packageId}/docflows, который вернет информацию обо всех документах, принадлежащих отправленному/полученному пакету.
В результате успешного запроса метод вернет модель DocflowPackageInfo, которая будет содержать число документов в пакете и модель DocflowSummary, где будет подробная информацию о каждом документе.
В противном случае, сервер вернет ошибку с описанием в теле ответа. (См. таблицу 7).
Таблица 7. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Идентификатор абонента не указан. | Не передан идентификатор абонента |
| Пользователь {userId} не имеет доступа к абоненту {abonentId}. | Указанный идентификатор абонента не найден в учетной записи пользователя |
| Идентификатор пакета не валидный. | Не найден идентификатор пакета |
Диаграмма метода по получению информации об исходящем/входящем пакете
