Получение расширенной информации о документе¶
POST /v3/documents/infoAuthorization: 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 содержит сведения о сертификате, с помощью которого сформировали подпись.