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

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

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

{
    "DocumentId": "guid",           // идентификатор документа
    "AttachmentName": "string",     // имя файла одного из вложений
    "IsOutput": false,              // признак того, что нужно найти исходящий документ
    "IncludeEvents": false,         // признак того, что ответ должен включать события
    "IncludeAttachments": false,    // признак того, что ответ должен включать вложения
    "AllowDefault": false           // признак того, что запрос не должен возвращать Bad Request, если документ не найден
}

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

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

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

Документ можно искать двумя способами:

  • по идентификатору документа;

  • по имени одного из вложений и направлению документооборота.

Идентификатор передается в поле DocumentId.
Имя вложения передается в поле AttachmentName.
Направление определяется полем IsOutput:
  • если оно равно true, то ищется исходящий документ;

  • если оно равно false, то ищется входящий документ;

  • если оно не задано, то запрос вернет первый найденный документ, у которого есть вложение с заданным именем.

Поля IncludeEvents и IncludeAttachments управляют включением в ответ событий и вложений. По умолчанию события и вложения в ответ не включаются.

Если поле AllowDefault установлено в true и документ не был найден, то запрос возвращает HTTP-статус 200 (OK) с пустым телом ответа.
Если поле AllowDefault установлено в false и документ не был найден, то запрос возвращает HTTP-статус 400 (Bad Request).

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

Ответ на запрос содержит такой же JSON, как и в ответе на запрос информации о документе.

Опционально ответ дополняется событиями и вложениями:

{
    "Id": "guid",                                   // идентификатор документа
    "OperatorDocumentId": "string",                 // операторский идентификатор документа
    "PackageId": "guid",                            // идентификатор пакета документов
    "OperatorPackageId": "string",                  // операторский идентификатор пакета документов
    "OperatorId": "string",                         // идентификатор оператора ЭДО или EDI-провайдера
    "SenderBoxId": "string",                        // идентификатор ящика отправителя
    "SenderDepartmentId": "string",                 // идентификатор подразделения отправителя
    "ReceiverBoxId": "string",                      // идентификатор ящика получателя
    "ReceiverDepartmentId": "string",               // идентификатор подразделения получателя
    "OurBoxEnabled": false,                         // признак того, что ящик включен
    "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": [                              // связи документа
    ],
    "Events": [                                     // события документа
    ],
    "Attachments": [                                // вложения документа
    ]
}

События документа

Поле Events содержит коллекцию событий документа. Коллекция заполняется, если поле запроса IncludeEvents было установлено в true.

Структура данных события

{
    "EventId": "guid",                              // идентификатор события
    "StatusCode": {                                 // код статуса для события
        "CanChangeDocumentCurrentStatus": false,    // признак того, что этот код статуса может менять текущий статус документа
        "Value": "string",                          // значение кода статуса
        "Description": "string"                     // читаемое описание статуса
    },
    "Comment": "string",                            // комментарий к событию
    "OperatorDateTime": "YYYY-MM-DDThh:mm:ss.fffZ", // операторские дата и время события в UTC
    "ErrorText": "string",                          // текст ошибки, если событие сигнализирует об ошибке
    "IsOutput": false,                              // признак того, что событие относится к исходящему документу
    "Attachments": [                                // вложения события
    ]
}

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

Поле CanChangeDocumentCurrentStatus сигнализирует об изменении текущего статуса документа. Если оно равно true, то событие изменило текущий статус документа. В противном случае событие информационное, а текущий статус документа не изменился.

Комментарий к событию задается стороной документооборота, которая выполнила действие. Например, для событий отправки/получения здесь может содержаться комментарий к документу. Для событий отклонения или запроса на аннулирование - текстовое описание причины отклонения или аннулирования.

Вложения событий и документа

Запрос возвращает либо вложения для каждого события, либо вложения всего документа.

Если поля запроса IncludeEvents и IncludeAttachments были установлены в true, то возвращаются вложения событий, т.е. заполняется поле Attachments у событий.

Если поле запроса IncludeEvents было установлено в false, а поле IncludeAttachments - в true, то возвращаются вложения документа, т.е. заполняется поле Attachments у документа.

Структура данных вложения

Структура данных вложения одинакова для вложений события и для вложений документа.

{
    "EventId": "guid",  // идентификатор события, которому принадлежит вложение
    "Name": "string",   // имя файла вложения
    "Type": 1,          // тип вложения
    "LinkId": "string", // ссылка на вложение в архиве
    "IsValid": true,    // признак того, что вложение прошло валидацию
    "Signatures": [     // подписи под вложением
    ]
}

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

По ссылке, заданной в LinkId, можно загрузить содержимое вложения из архива.

Если в настройках Продукта включена валидация вложений, то поле IsValid содержит результат валидации вложения. Подробнее см. Валидация и подписи.

Структура данных подписи

Под вложением могут быть проставлены одна или несколько подписей. Структура данных подписи представлена ниже.

{
    "LinkId": "string",                             // ссылка на подпись в архиве
    "IsValid": true,                                // признак того, что подпись прошла валидацию
    "IsEnhanced": true,                             // признак того, что подпись является усовершенствованной (CADES)
    "OriginalLinkId": "string",                     // ссылка на оригинальную подпись в архиве
    "Type": 0,                                      // тип подписи
    "PowerOfAttorney": {                            // данные доверенности (МЧД)
    },
    "CertificateV2": {                              // данные сертификата
        "Thumbprint": "string",                     // отпечаток сертификата
        "ValidFrom": "YYYY-MM-DDThh:mm:ss.fffZ",    // дата и время, с которого действует сертификат
        "ValidTo": "YYYY-MM-DDThh:mm:ss.fffZ",      // дата и время, по которое действует сертификат
        "RawData": "base64",                        // данные сертификата в виде массива байт в Base64
        "PublicKeyRawData": "base64"                // публичный ключ сертификата в виде массива байт в Base64
        "SerialNumber": "string",                   // серийный номер сертификата
        "Surname": "string",                        // фамилия владельца сертификата
        "FirstName": "string",                      // имя владельца сертификата
        "MiddleName": "string",                     // отчество владельца сертификата
        "CommonName": "string",                     // общее имя владельца сертификата
        "Position": "string",                       // должность владельца сертификата
        "OrganizationName": "string",               // наименование организации, в которой работает владелец сертификата
        "OrganizationInn": "string",                // ИНН организации, в которой работает владелец сертификата
        "Inn": "string",                            // ИНН физического лица или ИП, которые владеют сертификатом
        "Snils": "string",                          // СНИЛС владельца сертификата
        "Email": "string",                          // e-mail владельца сертификата
        "Department": "string",                     // подразделение, в котором работает владелец сертификата
        "City": "string",                           // город (населенный пункт) организации, в которой работает владелец сертификата, или владельца сертификата
        "Street": "string",                         // улица и номер дома организации, в которой работает владелец сертификата, или владельца сертификата
        "Ogrn": "string",                           // ОГРН организации, в которой работает владелец сертификата
        "OrgnIp": "string",                         // ОГРНИП, в которой работает владелец сертификата
        "Region": "string",                         // регион организации, в которой работает владелец сертификата, или владельца сертификата
        "Locale": "string",                         // язык сертификата
        "RnsFss": "string",                         // регистрационный номер страхователя ФСС
        "IssuerSimpleName": "string",               // простое имя издателя сертификата
        "CertificateType": 0                        // тип сертификата
    }
}

По ссылке, заданной в LinkId, можно загрузить содержимое подписи из архива.

Если в настройках Продукта включена валидация подписей, то поле IsValid содержит результат валидации подписи. Если в настройках Продукта включено совершенствование подписей, то поле IsEnhanced содержит признак того, что подпись усовершенствована (т. е. является CADES-подписью). Подробнее см. Валидация и подписи.

По ссылке, заданной в OriginalLinkId, можно загрузить содержимое оригинальной подписи из архива.

Тип подписи определяет ее направление. В Продукте существует два типа подписей:

  • подпись отправителя вложения-контента (тип 14);

  • подпись получателя вложения-контента (тип 15).

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

Если для подписи была указана доверенность, то ее данные возвращаются в структуре PowerOfAttorney.

Поле Certificate содержит сведения о сертификате, с помощью которого сформировали подпись.