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

Запрос: POST /v2/documents/send
HTTP-заголовки:
Authorization: Bearer access_token
Content-Type: application/json
Accept: application/json

Тело запроса:

{
    "OperatorId": "string",                     // идентификатор оператора ЭДО или EDI-провайдера
    "Packages": [                               // пакеты документов для отправки
        {
            "Id": "guid",                       // идентификатор пакета
            "SenderBoxId": "string",            // идентификатор ящика отправителя
            "SenderDepartmentId": "string",     // идентификатор подразделения отправителя
            "ReceiverBoxId": "string",          // идентификатор ящика получателя
            "ReceiverFnsId": "string",          // ФНС-идентификатор получателя
            "ReceiverInn": "string",            // ИНН получателя
            "ReceiverKpp": "string",            // КПП получателя
            "ReceiverDepartmentId": "string",   // идентификатор подразделения получателя
            "IsPackageLocked": false,           // признак того, что пакет заблокирован
            "Documents": [                      // документы, которые должны быть отправлены без подписи
            ],
            "SignedDocuments": [                // подписанные документы
            ]
        }
    ]
}

Описание запроса

Запрос позволяет поставить одну или несколько задач на отправку документов одному оператору ЭДО или EDI-провайдеру, который задается полем OperatorId.

Для операторов ЭДО OperatorId - это код оператора, присвоенный ФНС (например, «2AL», «2AE», «2BM», и т.д.). Для EDI-провайдеров идентификатор определяется из настроек операторов (см. Операторы).

Документы объединяются в пакеты. Для каждого пакета в поле Id задается его идентификатор в системе, которая выполняет отправку.

Пакет документов должен содержать один документ, если оператор не поддерживает работу с пакетами документов на своей стороне. Пакет документов может содержать один или несколько документов, если оператор поддерживает работу с пакетами документов. В этом случае документы будут объединены в пакет и в сервисе оператора.

Пакет документов можно заблокировать, если передать в поле IsPackageLocked значение true. Для заблокированных пакетов все ответные действия (приемка, отклонение, аннулирование и т.д.) выполняются сразу для всех документов пакета, т.е. нельзя один документ принять, а другой - отклонить. Если оператор поддерживает работу с пакетами документов и у него есть поддержка блокировки пакетов, то пакет будет заблокирован и в сервисе оператора.

Адресация пакета документов

Каждый пакет документов содержит адресную информацию: от кого и кому он отправляется.

Отправитель задается идентификатором ящика в поле SenderBoxId и, опционально, идентификатором подразделения в поле SenderDepartmentId. Идентификатор подразделения указывается, если пакет нужно отправить из подразделения, а не из головной организации отправителя. Ящик отправителя должен быть подключен и настроен в Продукте (см. Операторы).

Для адресации получателя существует три способа:

  • Указать идентификатор ящика получателя в поле ReceiverBoxId и, опционально, идентификатор подразделения в поле ReceiverDepartmentId. Идентификатор подразделения указывается, если пакет нужно отправить в подразделение, а не в головную организацию получателя.

  • Указать ФНС-идентификатор получателя в поле ReceiverFnsId. Этот способ не работает для EDI-сообщений.

  • Указать ИНН и КПП получателя в полях ReceiverInn и ReceiverKpp. КПП не указывается, если получатель - ИП. Этот способ не работает для EDI-сообщений.

Примечание

Указывать адресную информацию получателя нужно одним из трех способов. Использовать более одного способа нельзя.

Идентификаторы ящиков, подразделений и ФНС-идентификаторы

Идентификатор ящика - это идентификатор учетной записи организации в сервисе оператора ЭДО или EDI-провайдера. Формат идентификаторов ящиков и подразделений зависит от выбранного оператора.

ФНС-идентификатор - это идентификатор участника ЭДО. Он выдается оператором при подключении организации и указывается в атрибутах ИдФайл формализованных вложений. Обычно ФНС-идентификатор - это строка вида «код оператора + guid».

В общем случае идентификатор ящика и ФНС-идентификатор - это разные данные. В частном случае они могут совпадать.

Особенности адресации ЭТрН

Для электронной товарно-транспортной накладной в SenderBoxId передается ящик грузоотправителя, а в ReceiverBoxId - ящик грузополучателя.

Ящик грузоперевозчика должен быть передан в атрибуте Etrn_CargoTransporterBoxId каждого документа:

{
    "Key": "Etrn_CargoTransporterBoxId",    // атрибут "Ящик грузоперевозчика"
    "Value": "string"                       // значение атрибута
}

Примечание

Возможность указания грузоперевозчика по ФНС-идентификатору или ИНН/КПП в настоящее время не поддерживается.

Документы в пакете

Документы в пакете могут быть двух видов:

  • Документы, которые должны быть отправлены без подписи. Это документы, для которых подпись не нужна, например, EDI-сообщения. Передаются в коллекции Documents пакета.

  • Подписанные документы. Это документы, для которых подпись уже сформирована. Передаются в коллекции SignedDocuments пакета.

Структура данных документа

Структура данных документа:

{
    "DocumentId": "guid",                   // идентификатор документа
    "Type": 0,                              // тип документа
    "ContentFileName": "string",            // имя файла документа с расширением
    "ContentLinkId": "string",              // ссылка на контент документа в архиве
    "IsReceiverSignatureRequired": false,   // признак того, что требуется подпись получателя
    "Comment": "string",                    // комментарий к документу
    "Name": "string",                       // наименование документа
    "Number": "string",                     // номер документа
    "Date": "YYYY-MM-DD",                   // дата документа
    "CustomType": "string",                 // дополнительный тип документа
    "Attributes": [                         // атрибуты документа
    ],
    "MetadataCollection": [                 // метаданные документа
    ],
    "DocumentLinks": [                      // связи документа
    ]
}

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

Примечание

Для формализованных XML-документов имя файла должно быть сформировано из значения атрибута ИдФайл плюс расширение xml.

Содержимое документа передается по ссылке, которая указана в поле ContentLinkId. Содержимое должно быть предварительно сохранено в архиве.

Если для документа требуется подпись получателя, то в поле IsReceiverSignatureRequired нужно передать зачение true. Это поле не имеет смысла передавать для документов, регламент обмена которыми однозначено определяет критерии отправки второго титула. Требование подписи будет передано получателю, только если сервис выбранного оператора поддерживает передачу этого признака. В противном случае значение поля будет проигнорировано.

Вместе с документом можно передать произвольный текстовый комментарий к нему в поле Comment. Комментарий не должен быть длинее 2000 символов. Он будет передан получателю, только если сервис выбранного оператора поддерживает передачу комментариев. В противном случае значение поля будет проигнорировано.

Типизация документа

Перечень типов документов для задания в поле Type можно запросить, выполнив справочный запрос к API.

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

Для полуформализованных документов в качестве типа передается значение 3, вид полуформализованного документа определяется значением поля CustomType.

Для EDI-сообщений в качестве типа передается значение 49, вид EDI-сообщения определяется значением поля CustomType.

Имя, номер и дата документа

Поля Name, Number и Date можно задавать только для неформализованных документов, полуформализованных документов, и EDI-сообщений.

Для формализованных документов эти поля задавать нельзя. Они будут определены автоматически, из содержимого документов.

Атрибуты документа

Атрибуты - это вспомогательная информация о документе, состав и обязательность которой определяется сервисом выбранного оператора (например, сумма документа, номер договора, и т.д.). Атрибуты передаются для полуформализованных документов.

Атрибуты представляют коллекцию элементов вида «ключ-значение». Структура атрибута:

{
    "Key": "string",    // ключ атрибута
    "Value": "string"   // значение атрибута
}

В поле Key передается ключ атрибута в виде, в котором он будет понятен оператору, в поле Value - значение атрибута.

Метаданные документа

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

Пример использования метаданных: автоматизированная машрутизация и обработка документов внутри информационных систем сторон документооборота.

Метаданные представляют коллекцию элементов вида «ключ-значение». Структура элемента метаданных:

{
    "Key": "string",    // ключ атрибута
    "Value": "string"   // значение атрибута
}

В поле Key передается ключ элемента метаданных, в поле Value - значение элемента.

Связи документа

Для исходящего документа можно задать взаимосвязь с другими документами. Это делается с помощью коллекции связей документа. Структура элемента коллекции:

{
    "LinkedDocumentId": "guid",             // идентификатор связанного документа
    "LinkedDocumentDescription": "string",  // описание связанного документа
    "LinkType": 0                           // тип связи
}

Тип связи задается в поле LinkType. Возможны три типа связей:

  • 0 - связанный документ;

  • 1 - родительский документ;

  • 2 - дочерний документ.

Если связь устанавливается с электронным документом, то в поле LinkedDocumentId передается идентификатор документа. Документ при этом может быть как входящим, так и исходящим.

Если связь устанавливается с «бумажным» документом, то в поле LinkedDocumentDescription передается его описание.

Примечание

Возможность задания того или иного типа связи, возможность связи с «бумажным» документом зависит от оператора ЭДО. См. Типы связи при передаче связанных документов.

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

Для подписанных документов структура данных документа дополняется этими полями:

{
    // ...
    "SignatureFileName": "string",  // имя файла подписи
    "SignatureLinkId": "string",    // ссылка на подпись в архиве
    "PowerOfAttorney": {            // данные доверенности (МЧД)
    }
}

Подпись передается по ссылке, которая указана в поле SignatureLinkId. Подпись должна быть предварительно сохранена в архиве.

Если для подписанта нужно указать доверенность (МЧД), то следует заполнить структуру PowerOfAttorney.

См. также:
Передача и получение сведений о доверенности

Формирование подписей

Продукт поддерживает два способа формирования подписей:

  • Локальное подписание - в этом случае формирование ЭП выполняется с помощью сертификата, установленного на машине пользователя средствами, работающими на этой же машине.

  • Серверное подписание - в этом случае формирование ЭП выполняется с помощью Crypto API Продукта. Сертификат для создания ЭП должен быть доступен для Crypto API.

В обоих случаях порядок отправки не меняется:

Ответ на запрос

Запрос ставит задачи на отправку интеграционному модулю Продукта и возвращает идентификаторы поставленных задач в виде коллекции:

[
    1,
    2,
    3,  // и т. д.
]

Для каждого пакета в запросе ставится отдельная задача на отправку.