.. _Integration_IntegrationApi_Helpers_WorkingWithDocuments_GettingExtendedDocumentInfo: Получение расширенной информации о документе ############################################ | Запрос: ``POST /v3/documents/info`` | HTTP-заголовки: .. code-block:: Authorization: Bearer access_token Content-Type: application/json Accept: application/json Тело запроса: .. code-block:: JSON { "DocumentId": "guid", // идентификатор документа "AttachmentName": "string", // имя файла одного из вложений "IsOutput": false, // признак того, что нужно найти исходящий документ "IncludeEvents": false, // признак того, что ответ должен включать события "IncludeAttachments": false, // признак того, что ответ должен включать вложения "AllowDefault": false // признак того, что запрос не должен возвращать Bad Request, если документ не найден } Описание запроса **************** Запрос позволяет получить расширенную информацию о документе. Его можно использовать вместо :ref:`запроса информации о документе `, если внешней системе требуется больше сведений, например, если планируется хранить полную информацию о событиях и вложениях документа. Документ можно искать двумя способами: * по идентификатору документа; * по имени одного из вложений и направлению документооборота. | Идентификатор передается в поле ``DocumentId``. | Имя вложения передается в поле ``AttachmentName``. | Направление определяется полем ``IsOutput``: * если оно равно ``true``, то ищется исходящий документ; * если оно равно ``false``, то ищется входящий документ; * если оно не задано, то запрос вернет первый найденный документ, у которого есть вложение с заданным именем. Поля ``IncludeEvents`` и ``IncludeAttachments`` управляют включением в ответ событий и вложений. По умолчанию события и вложения в ответ не включаются. | Если поле ``AllowDefault`` установлено в ``true`` и документ не был найден, то запрос возвращает HTTP-статус 200 (``OK``) с пустым телом ответа. | Если поле ``AllowDefault`` установлено в ``false`` и документ не был найден, то запрос возвращает HTTP-статус 400 (``Bad Request``). Ответ на запрос *************** Ответ на запрос содержит такой же JSON, как и в ответе на :ref:`запрос информации о документе `. Опционально ответ дополняется событиями и вложениями: .. code-block:: 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``. Структура данных события ------------------------ .. code-block:: JSON { "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`` у *документа*. Структура данных вложения ------------------------- Структура данных вложения одинакова для вложений события и для вложений документа. .. code-block:: JSON { "EventId": "guid", // идентификатор события, которому принадлежит вложение "Name": "string", // имя файла вложения "Type": 1, // тип вложения "LinkId": "string", // ссылка на вложение в архиве "IsValid": true, // признак того, что вложение прошло валидацию "Signatures": [ // подписи под вложением ] } Тип вложения позволяет определить, что содержится во вложении, без анализа самого вложения. Перечень типов вложений можно запросить, выполнив справочный :ref:`запрос ` к API. По ссылке, заданной в ``LinkId``, можно :ref:`загрузить ` содержимое вложения из архива. Если в настройках Продукта включена валидация вложений, то поле ``IsValid`` содержит результат валидации вложения. Подробнее см. :ref:`Setup_Integration_AdvancedSetup_ValidationAndSignatures`. Структура данных подписи ^^^^^^^^^^^^^^^^^^^^^^^^ Под вложением могут быть проставлены одна или несколько подписей. Структура данных подписи представлена ниже. .. code-block:: JSON { "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``, можно :ref:`загрузить ` содержимое подписи из архива. Если в настройках Продукта включена валидация подписей, то поле ``IsValid`` содержит результат валидации подписи. Если в настройках Продукта включено совершенствование подписей, то поле ``IsEnhanced`` содержит признак того, что подпись усовершенствована (т. е. является CADES-подписью). Подробнее см. :ref:`Setup_Integration_AdvancedSetup_ValidationAndSignatures`. По ссылке, заданной в ``OriginalLinkId``, можно :ref:`загрузить ` содержимое оригинальной подписи из архива. Тип подписи определяет ее направление. В Продукте существует два типа подписей: * подпись отправителя вложения-контента (тип ``14``); * подпись получателя вложения-контента (тип ``15``). В большинстве случаев подпись является подписью отправителя, за исключением подписей принимающей стороны под неформализованными документами и предложениями об аннулировании. | Если для подписи была указана доверенность, то ее данные возвращаются в структуре ``PowerOfAttorney``. | См. также: | :ref:`Integration_IntegrationApi_PowerOfAttorney_PowerOfAttorneyConcept_SendingAndReceiving` Поле ``Certificate`` содержит сведения о сертификате, с помощью которого сформировали подпись.