Работа с МЧД
Эта страница описывает, как передать машиночитаемую доверенность вместе с титулом перевозочного документа и как обработать результат ее проверки.
Машиночитаемая доверенность (МЧД) — электронный документ в формате XML, с помощью которого руководитель организации передает сотруднику полномочия для подписания документов.
Когда нужна МЧД
МЧД обязательна только в том случае, если подписант действует по электронной доверенности.
МЧД не нужна, если:
- подписант действует без доверенности, например, руководитель организации;
- подписант действует по бумажной доверенности: полномочия подтверждает бумажный документ, реквизиты которого указаны внутри титула.
Данные электронной подписи указаны в структуре Signature. Поле PowerOfAttorneyAttachmentStatus этой структуры показывает, приложена ли МЧД к подписи. По значению поля StatusName структуры PowerOfAttorneyAttachmentStatus можно понять, нужна ли МЧД.
Способы передачи МЧД
МЧД можно передать вместе с титулом следующими способами:
- файл;
- реквизиты конкретной МЧД для их записи в метаданные документа;
- МЧД по умолчанию.
Формат каждого типа документа содержит комментарии о том, как правильно указать МЧД: обращайте внимание на эти указания.
Передача файлом
Чтобы приложить к титулу МЧД в виде файла, передайте в поле Contents структуры PowerOfAttorneyToPost:
- содержимое файла МЧД в поле
Content; - подпись под МЧД в поле
Signature.
В поле Contents нужно передать:
- для МЧД без передоверия — содержимое файла МЧД;
- для передоверенной МЧД — содержимое файлов передоверенной МЧД и родительских МЧД в произвольном порядке.
Этим способом можно передать МЧД только если она не зарегистрирована в реестре ФНС или хранится во внешней системе.
Передача по реквизитам
Чтобы указать МЧД по реквизитам, передайте содержимое файла МЧД в поле PowerOfAttorney структуры SignedContent, а данные МЧД укажите в структуре PowerOfAttorneyToPost.
В запрос вызова метода в этом случае сама доверенность не попадает. В идентификаторе FullId передайте три значения, по которым МЧД можно найти в реестре ФНС:
RegistrationNumber— регистрационный номер доверенности;IssuerInn— ИНН доверителя;RepresentativeInn— ИНН представителя.
МЧД по умолчанию
Чтобы использовать МЧД по умолчанию, в структуре PowerOfAttorneyToPost установите признак UseDefault = true.
Настройте МЧД по умолчанию заранее — в веб-интерфейсе Диадока или методом UpdateEmployeePowerOfAttorney.
Определение способа передачи МЧД
Каким способом передана МЧД — показывает поле SendingType структуры PowerOfAttorneyInfo. В зависимости от его значения можно определить способ передачи:
Способ передачи МЧД
| Значение | Что означает |
|---|---|
Metadata | Переданы только реквизиты МЧД: регистрационный номер, ИНН доверителя и ИНН представителя |
File | Вместе с документом передают содержимое файла МЧД и электронную подпись под ним; при передоверии также могут передаваться родительские МЧД и подписи под ними. |
DocumentContent | МЧД содержится непосредственно внутри XML-документа |
Отправка и получение МЧД
МЧД в новом сообщении
Так можно отправить:
- первичные титулы электронной транспортной накладной (ЭТрН): Т1, Т3, Т5, Т7 и Т8;
- титулы Т1—Т4 авианакладной;
- титулы Т1—Т5 железнодорожной накладной;
- все титулы электронного путевого листа (ЭПЛ);
- титул Т1 заказа-заявки (ЭЗЗ);
- титул Т1 поручения экспедитору (ПЭ);
- титул экспедиторской расписки;
- титул складской расписки (СР).
Для отправки вызовите метод PostMessage (V3). Данные МЧД укажите в структуре SignedContent внутри DocumentAttachment.
Значения TypeNamedId, Function и Version в примере указаны для ЭЗЗ.
{
"FromBoxId": "{{diadocBoxId}}",
"ToBoxId": "{{toBoxId}}",
"DocumentAttachments": [
{
"TypeNamedId": "LogisticsOrderRequest",
"Function": "default",
"Version": "zakzvper_05_01_01",
"SignedContent": {
"Content": "{{base64EncodedXml}}",
"Signature": "{{sig}}",
"PowerOfAttorney": {
"FullId": {
"RegistrationNumber": "{{registrationNumber}}",
"IssuerInn": "{{issuerInn}}",
"RepresentativeInn": "{{representativeInn}}"
}
}
}
}
]
}
МЧД в дополнении сообщения
МЧД можно приложить к дополнению в следующих сценариях:
Сценарии отправки дополнением
| Сценарий | Где находятся данные МЧД в дополнении | Вложение |
|---|---|---|
| Отправка ответного титула | RecipientTitles | RecipientTitleAttachment |
| Отправка отказа вместо ответного титула | XmlSignatureRejections | XmlSignatureRejectionAttachment |
| Добавление подписи к ранее отправленному документу | Signatures | DocumentSignature
|
В следующем примере показана отправка дополнения: доверенность добавляется к ранее отправленному титулу:
{
"BoxId": "{{diadocBoxId}}",
"MessageId": "{{messageId}}",
"Signatures": [
{
"ParentEntityId": "<EntityId подписываемого документа>",
"Signature": "<подпись документа в Base64>",
"PowerOfAttorney": {
"FullId": {
"RegistrationNumber": "{{poaRegNumber}}",
"IssuerInn": "{{issuerInn}}",
"RepresentativeInn": "{{representativeInn}}"
}
}
}
]
}
Титул можно отправить без подписи, например, с отложенным подписанием, а подпись добавить отдельным запросом. В таком случае МЧД будет получена вместе с подписью, а не с исходным документом.
Получение МЧД
Получатель видит МЧД как отдельную сущность, привязанную к подписи: МЧД отображается отдельно и связана с подписью. Данные МЧД можно найти в поле Attachment.Signature.PowerOfAttorney.
Ошибки МЧД
Доверенность не приложена
В этом случае в ответе методов GetDocument (V3), GetDocuments (V3) и GetDocumentsByMessageId в поле DocflowStatus.PowerOfAttorneyGeneralStatus появится предупреждение:
Пример предупреждения:
{
"PowerOfAttorneyGeneralStatus": {
"Severity": "Warning",
"StatusNamedId": "IsNotAttached",
"StatusText": "Не приложена доверенность",
"Errors": []
}
}
Значение Severity = Warning означает, что документооборот не остановлен.
Доверенность не прошла проверку
В этом случае Диадок отправляет результат проверки отдельным событием с признаками:
EntityType = Attachment,AttachmentType = PowerOfAttorneyStatus.
Информация о МЧД находится в структуре PowerOfAttorneyInfo:
Пример ошибки:
{
"PowerOfAttorneyInfo": {
"FullId": {
"RegistrationNumber": "8d375c94-49a0-477c-8cc9-eca49ba0d88a",
"IssuerInn": "3812125023",
"RepresentativeInn": "662518094912"
},
"Status": {
"Severity": "Error",
"StatusNamedId": "ValidationError",
"StatusText": "При проверке доверенности произошла ошибка",
"OperationError": {
"Code": "PowerOfAttorneyNotFound",
"Text": "Доверенность не найдена в реестре ФНС"
}
},
"SendingType": "Metadata"
}
}
Чтобы понять результат проверки, изучите поле StatusNamedId:
- при
ValidationErrorиCanNotBeValidatedкод ошибки находится в полеOperationError, - при
IsNotValidиHasWarningsподробности находятся в полеValidationProtocol.
Поле StatusNamedId содержит итог проверки:
IsValid— МЧД действительна;IsNotValid— МЧД недействительна;HasWarnings— МЧД принята, но при проверке обнаружены замечания;CanNotBeValidated— проверить МЧД не удалось, например из-за недоступности реестра;ValidationError— при проверке произошла ошибка;UnknownStatus— результат проверки неизвестен.
Поле OperationError содержит подробную причину, если проверку не удалось завершить. При анализе результата ориентируйтесь на код в поле Code, а не на общее описание в поле StatusText.
Например:
{
"Code": "PowerOfAttorneyNotFound",
"Text": "Доверенность не найдена в реестре ФНС"
}
Код PowerOfAttorneyNotFound означает, что МЧД не найдена в реестре ФНС.
Подпись не соответствует документу
Подпись должна соответствовать байтам отправленного документа. Даже изменение переносов строк или повторное сохранение XML после подписания может нарушить это соответствие. Само по себе кодирование в Base64 с последующим декодированием не меняет байты, если оба преобразования выполнены без ошибок.
В случае ошибки проверьте подпись для двух пар:
- Документ и подпись до отправки.
- Документ и подпись, скачанные после отправки.
Для проверки используйте Контур.Крипто или локальные инструменты КриптоПро. Если первая пара не проходит проверку, проверьте этап подписания. Если первая проходит, а вторая нет, сравните байты документа и подписи и проверьте, что произошло между подписанием и получением документов обратно.
Распространенные ошибки
В таблице приведены распространенные ошибки МЧД и способы их решения:
Распространенные ошибки МЧД
| Ошибка | Что проверить | Что делать |
|---|---|---|
Поле DocflowStatusV3.PowerOfAttorneyGeneralStatus = IsNotAttached | МЧД не приложена к одной из подписей документа | Проверьте, передан ли PowerOfAttorney в SignedContent приотправке титула |
Поле Entity.PowerOfAttorneyAttachmentStatus = PowerOfAttorneyRequired | Для подписи нужно подтверждение полномочий | Сверьте данные подписанта в титуле: приложите МЧД или исправьте его статус, если он указан неверно |
| При генерации титула возникает ошибка валидации подписанта | У подписанта указан статус доверенности, но не заполненыPowerOfAttorney и StorageId | Заполните одно из этих полей |
Поле PowerOfAttorneyValidationStatus.StatusNamedId = IsNotValid | МЧД не прошла проверку | Проверьте саму МЧД и причину в ValidationProtocol |
Поле PowerOfAttorneyValidationStatus.StatusNamedId = CanNotBeValidatedили ValidationError | Проверку МЧД не удалось завершить | Изучите код ошибки в OperationError. Не отправляйтедокумент повторно, пока не выясните причину |
| МЧД проходит проверку на сайте ФНС, но ошибка остается | Проверка МЧД на сайте не объясняет ошибку при отправке документа | Проверьте подпись и код ошибки в ответе Диадока |
| Документ не соответствует подписи | После подписания могли измениться байты документа | Сравните байты, которые подписали, с байтами, отправленными в Диадок |
| В Диадоке больше титулов, чем вы отправили в текущей попытке | В документообороте могли остаться титулы от предыдущих попыток | Проверьте историю отправок и воспроизведите ошибку на новом документообороте |