Получение информации о документе

Запрос: GET /v3/documents/info/{documentId}
HTTP-заголовки:
Authorization: Bearer access_token
Accept: application/json

где {documentId} - идентификатор документа.

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

Запрос позволяет получить основные сведения о документе по его идентификатору.

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

В ответ приходит JSON с основными сведениями о документе.

{
    "Id": "guid",                                   // идентификатор документа
    "OperatorDocumentId": "string",                 // операторский идентификатор документа
    "PackageId": "guid",                            // идентификатор пакета документов
    "OperatorPackageId": "string",                  // операторский идентификатор пакета документов
    "OperatorId": "string",                         // идентификатор оператора ЭДО или EDI-провайдера
    "SenderBoxId": "string",                        // идентификатор ящика отправителя
    "SenderDepartmentId": "string",                 // идентификатор подразделения отправителя
    "ReceiverBoxId": "string",                      // идентификатор ящика получателя
    "ReceiverDepartmentId": "string",               // идентификатор подразделения получателя
    "Type": 0,                                      // тип документа
    "Name": "string",                               // наименование документа
    "Number": "string",                             // номер документа
    "Date": "YYYY-MM-DD",                           // дата документа, заданная отправителем, в часовом поясе отправителя
    "OperatorDateTime": "YYYY-MM-DDThh:mm:ss.fffZ", // дата и время поступления документа в сервис оператора, UTC
    "Total": 0,                                     // сумма документа
    "TotalVat": 0,                                  // сумма НДС документа
    "Currency": "string",                           // строковый код валюты документа
    "IsPackageLocked": false,                       // признак того, что пакет документов заблокирован
    "IsReceiverSignatureRequired": false,           // признак того, что требуется подпись получателя
    "Comment": "string",                            // комментарий к документу
    "IsOutput": false,                              // признак того, что документ является исходящим
    "CustomType": "string",                         // дополнительный тип документа
    "CurrentStatus": "string",                      // код текущего статуса документа
    "RoamingOperatorId": "string",                  // идентификатор роумингового оператора ЭДО, если документ роуминговый
    "HasValidationErrors": false,                   // признак того, что у вложений документа или подписей под ними есть ошибки валидации
    "PackageDocuments": [                           // идентификаторы других документов этого же пакета
        "guid"
    ],
    "Tags": [                                       // теги документа
        "string"
    ],
    "Attributes": [                                 // аттрибуты документа
    ],
    "MetadataCollection": [                         // метаданные документа
    ],
    "DocumentLinks": [                              // связи документа
    ]
}
Ответ не содержит информацию о событиях и вложениях.
Чтобы получить информацию о документе, включая события и/или вложения, см. Получение расширенной информации о документе

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

Идентификатор оператора ЭДО или EDI-провайдера позволяет понять, через какого оператора идет документооборот.

Поле SenderBoxId содержит идентификатор ящика отправителя документа. Если документ входящий и получен из подразделения, а не из головной организации, то поле SenderDepartmentId содержит идентификатор подразделения отправителя.

Поле ReceiverBoxId содержит идентификатор ящика получателя документа. Если документ исходящий и отправлен в подразделение, а не в головную организацию, то поле ReceiverDepartmentId содержит идентификатор подразделения получателя.

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

Идентификатор роумингового оператора заполняется только для ЮЗЭДО-документов и позволяет определить, является ли документ роуминговым. Если RoamingOperatorId задан и его значение отлично от null, то документ роуминговый.

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

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

В ReceiverBoxId указывается:

  • ящик грузополучателя, если запрос информации о документе выполнен из ящика грузополучателя;

  • ящик перевозчика, если запрос информации о документе выполнен из ящика грузоперевозчика.

Поэтому при обработке ЭТрН во внешней системе рекомендутся использовать атрибуты для разбора адресной информации.

Идентификаторы документа и пакета

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

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

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

Примечание

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

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

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

Для формализованных документов указывается только Type.

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

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

Имя, номер, дата, суммы и валюта документа

Поля Name, Number, Date, Total, TotalVat и Currency для формализованных документов определяются из первичного вложения. Для неформализованных документов эти поля заполняются теми значениями, которые указал отправитель, если оператор позволяет передавать эту информацию.

Требование подписи получателя

В поле IsReceiverSignatureRequired передается признак того, что требуется подпись получателя.

Если оно передано, и равно true, то для документа следует отправить второй титул (например, УПД, УКД) или подпись получателя.

Если оно передано, и равно false, то для документов не нужно отправлять второй титул или подпись получателя.

Если оно не передано, то необходимость отправки второго титула или подписи получателя определяется исходя из регламента документооборота для заданного типа документа.

Теги документа

Теги документа указываются в поле Tags. Коллекция тегов заполняется при отправке исходящего документа или при получении входящего документа интеграционным модулем Продукта. Каждый элемент коллекции содержит значение тега (см. настройки тегов).

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

Атрибуты указываются в поле Attributes. Атрибуты заполняются для полуформализованных документов.

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

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

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

Особенности атрибутов ЭТрН

Для электронной товарно-транспортной накладной коллекция атрибутов заполняется предопределенными значениями:

  • Etrn_CargoSenderBoxId - идентификатор ящика грузоотправителя;

  • Etrn_CargoReceiverBoxId - идентификатор ящика грузополучателя;

  • Etrn_CargoTransporterBoxId - идентификатор ящика грузоперевозчика;

  • Etrn_MinTransId - идентификатор ЭТрН в ГИС ЭПД.

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

Метаданные указываются в поле MetadataCollection. Метаданные могут заполняться для всех типов документов, если сервис выбранного оператора поддерживает передачу метаданных.

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

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

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

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

Связи документа указываются в поле DocumentLinks. Структура элемента коллекции:

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

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

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

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

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

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

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

Примечание

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