Работа с универсальным сообщением
Подробная информация о переходе на универсальные сообщения приведена на странице Переход на универсальные сообщения.
Генерация универсального сообщения
Сгенерировать универсальное сообщение можно с помощью метода GenerateUniversalMessage. В запросе нужно передать идентификатор ящика получателя (boxId), идентификатор отправленного сообщения (messageId) и идентификатор родительской сущности, на которую нужно сформировать универсальное сообщение (attachmentId). Эти значения можно получить из структуры Message.
В теле запроса нужно передать XML-файл с данными для формирования универсального сообщения, соответствующий упрощенной XSD-схеме.
Пример HTTP-запроса метода GenerateUniversalMessage:
POST GenerateUniversalMessage?boxId={{boxId}}&messageId={{messageId}}&attachmentId={{attachmentId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Content-Type: application/xml
Пример тела запроса метода GenerateUniversalMessage:
<UniversalMessage>
<UniversalMessageInfos>
<UniversalMessageInfo StatusCode="1999">
<PlainText>123</PlainText>
</UniversalMessageInfo>
</UniversalMessageInfos>
<Sender Position="Сотрудник" UseDefaultPersonInfo="false">
<Fio FirstName="Иван" LastName="Иванов" MiddleName="Иванович"/>
<Contacts OtherContactInfo="OtherContactInfo">
<Phones>
<Phone>8-343-123-4567</Phone>
</Phones>
<Emails>
<Email>email@sample.com</Email>
</Emails>
</Contacts>
</Sender>
<Recipient Position="Сотрудник" UseDefaultPersonInfo="false">
<Fio FirstName="Петров" LastName="Петр" MiddleName="Петрович"/>
<Contacts OtherContactInfo="OtherContactInfo">
<Phones>
<Phone>8-343-123-4567</Phone>
</Phones>
<Emails>
<Email>email@sample.com</Email>
</Emails>
</Contacts>
</Recipient>
</UniversalMessage>
Пример тела ответа метода GenerateUniversalMessage:
<?xml version="1.0" encoding="windows-1251"?>
<Файл ИдФайл="DP_UNISOOBSCH_2BM-6125600340-732644841-202407101103418496883_2BM-9147414342-757645784-202407101104400484330_20250529_3839e349-99d5-4a54-9b5f-546bffbfb44a" ВерсПрог="Diadoc 1.0" ВерсФорм="5.01">
<Документ КНД="1115144">
<СведУС ДатаФорм="29.05.2025" ВремФорм="13.53.27" ИмяПолФайл="ON_NSCHFDOPPR_2BM-9147414342-757645784-202407101104400484330_2BM-6125600340-732644841-202407101103418496883_20250207_30f13ccc-deb2-4d49-8201-0ab211e8683d" />
<СвСобытДок СтатусУС="1999">
<ТекстУС>123</ТекстУС>
</СвСобытДок>
<ОтпрУС ИдОтпрУС="2BM-9147414342-757645784-202407101104400484330">
<СвЛицОтпрУС Должн="Сотрудник">
<ФИО Фамилия="Иванов" Имя="Иван" Отчество="Иванович" />
<Контакт>
<Тлф>8-343-123-4567</Тлф>
<ЭлПочта>email@google.com</ЭлПочта>
<ИнКонт>OtherContactInfo</ИнКонт>
</Контакт>
</СвЛицОтпрУС>
</ОтпрУС>
<ПолучУС ИдПолучУС="2BM-6125600340-732644841-202407101103418496883">
<СвЛицПолучУС Должн="Сотрудник">
<ФИО Фамилия="Петр" Имя="Петров" Отчество="Петрович" />
<Контакт>
<Тлф>8-343-123-4567</Тлф>
<ЭлПочта>email@google.com</ЭлПочта>
<ИнКонт>OtherContactInfo</ИнКонт>
</Контакт>
</СвЛицПолучУС>
</ПолучУС>
</Документ>
</Файл>
В ответе метод вернет сформированный XML-файл универсального сообщения, соответствующий XSD-схеме, для сущности attachmentId из сообщения messageId в ящике boxId. Отправить полученный XML-файл можно с помощью метода PostMessagePatch (V4), передав его в поле UniversalMessages структуры MessagePatchToPostV2. Инструкция об отправке документа приведена в разделе Отправка универсального сообщения.
Получение универсального сообщения
Чтобы получить универсальное сообщение, можно воспользоваться следующими способами:
методы работы с сообщениями, например, GetMessage (V6),
методы работы с документооборотом, например, GetDocflows (V4).
Метод GetMessage
Чтобы получить универсальное сообщение методом GetMessage (V6), нужно передать в запросе:
boxId— идентификатор ящика отправителя,
messageId— идентификатор отправленного сообщения,
entityId— идентификатор родительской сущности, на которую сформировано универсальное сообщение.
Эти значения можно получить из структуры Message.
В ответе метод вернет структуру Message с вложенной структурой Entity. Универсальное сообщение будет представлено структурой Entity со следующими полями:
EntityType = Attachment,
AttachmentType = UniversalMessage.
Информация об универсальном сообщении будет храниться в поле Entity.UniversalMessageInfo в виде структуры UniversalMessageInfo.
Пример HTTP-запроса метода GetMessage:
GET /V6/GetMessage?boxId={{boxId}}&messageId={{messageId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json
Пример ответа метода GetMessage:
{
"CreatedFromDraftId": "",
"DraftIsLocked": false,
"DraftIsRecycled": false,
"DraftIsTransformedToMessageIdList": [
],
"Entities": [
{
"AttachmentType": "XmlTorg12",
<...>
},
{
"AttachmentType": "XmlTorg12BuyerTitle",
<...>
},
{
"AttachmentType": "InvoiceReceipt",
"AuthorUserId": "",
"Content": {
"Size": 5575
},
"ContentTypeId": "receipt_133_01_03",
"EntityId": "529b4e21-a982-4364-a52b-fff1f1cd8409",
"EntityType": "Attachment",
"FileName": "DP_IZVPOL_2BM-7743911253-774301001-201512151245491116742_2BM-7717704518-770101001-201708200655456926042_20250528_7ce74dc9-0943-4fb9-90cd-327d445e5198.xml",
"IsApprovementSignature": false,
"IsEncryptedContent": false,
"Labels": [
],
"NeedReceipt": false,
"NeedRecipientSignature": false,
"ParentEntityId": "e9bfc749-51e7-4575-a587-7033b9f2e882",
"RawCreationDate": 638840213353178450
},
{
"AttachmentType": "UniversalMessage",
"AuthorUserId": "",
"Content": {
"Size": 856
},
"ContentTypeId": "receipt_uni_01",
"EntityId": "647250f0-c833-4cd2-a6b1-afe2ee812986",
"EntityType": "Attachment",
"FileName": "DP_UNISOOBSCH_2BM-7743911253-774301001-201512151245491116742_2BM-7717704518-770101001-201708200655456926042_20250528_6ca0fdf6-0ab4-461b-9c67-1b5d9c200bbb.xml",
"IsApprovementSignature": false,
"IsEncryptedContent": false,
"Labels": [
],
"NeedReceipt": false,
"NeedRecipientSignature": false,
"ParentEntityId": "e9bfc749-51e7-4575-a587-7033b9f2e882",
"RawCreationDate": 638840213353178450,
"UniversalMessageInfo": {
"CodeGroup": "Receipt",
"Events": [
{
"PlainText": "",
"StatusCode": 1999
}
]
}
}
],
"FromBoxId": "eab6c66b8f644ada8cf04c6a2b7ba915@diadoc.ru",
"FromTitle": "Отправитель",
"IsDeleted": false,
"IsDraft": false,
"IsInternal": false,
"IsProxified": false,
"IsReusable": false,
"IsTest": false,
"LastPatchTimestampTicks": 638840428633821944,
"LockMode": "None",
"MessageId": "d213fc6e-1c0c-4ced-ae35-9078c895b92b",
"MessageType": "Letter",
"PacketIsLocked": false,
"ProxyBoxId": "",
"ProxyTitle": "",
"TimestampTicks": 638840213224709349,
"ToBoxId": "1234b472842f47baa1a309100064ace4@diadoc.ru",
"ToTitle": "Получатель"
}
Метод GetMessage (V6) не возвращает содержимое универсального сообщения, а только информацию о нем. Чтобы получить содержимое, используйте метод GetEntityContent (V4).
Метод GetDocflows
Чтобы получить универсальное сообщение методом GetDocflows (V4), нужно передать в запросе идентификатор ящика отправителя boxId, а в теле запроса — идентификатор документа в виде пары MessageId и EntityId.
Эти значения можно получить из структуры Message.
В ответе метод вернет структуру GetDocflowBatchResponseV4 с вложенной структурой Documents.Docflow, в которой универсальное сообщение UniversalMessageAttachmentDocflow вернется в поле UniversalMessage одной из следующих структур:
ReceiptDocflowV4 — для извещения о получении,
AmendmentRequestDocflowV4 — для уведомления об уточнении,
SignatureRejectionDocflowV4 — для отказа в подписи.
Пример HTTP-запроса метода GetDocflows:
POST /V4/GetDocflows?boxId={{boxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Content-Type: application/json charset=utf-8
Accept: application/json
Пример тела запроса метода GetDocflows:
{
"Requests": [
{
"DocumentId": {
"MessageId": "d213fc6e-1c0c-4ced-ae35-9078c895b92b",
"EntityId": "e9bfc749-51e7-4575-a587-7033b9f2e882"
}
}
]
}
Пример ответа метода GetDocflows:
{
"Documents": [
{
"Docflow": {
"Confirmation": {...},
"DocflowStatus": {...},
"OuterDocflowEntities": [...],
"OuterDocflows": [...],
"RecipientReceipt": {
"Confirmation": {...},
"DeliveredAt": {...},
"IsFinished": true,
"ReceiptAttachment": {
"Attachment": {
"AttachmentFilename": "DP_IZVPOL_2BM-7743911253-774301001-201512151245491116742_2BM-7717704518-770101001-201708200655456926042_20250528_7ce74dc9-0943-4fb9-90cd-327d445e5198.xml",
"DisplayFilename": "Извещение о получении исправления",
"Entity": {
"Content": {
"Size": 5575
},
"CreationTimestamp": {
"Ticks": 638840213353178450
},
"EntityId": "529b4e21-a982-4364-a52b-fff1f1cd8409"
}
},
"ContentTypeId": "receipt_133_01_03",
"Signature": {
"CadesT": {
"Content": {
"Size": 7098
},
"CreationTimestamp": {
"Ticks": 638840213356162462
},
"EntityId": "5a6cdfb3-973f-47b2-b1cb-19b228d1eb2f"
},
"Cms": {
"Content": {
"Size": 3466
},
"CreationTimestamp": {
"Ticks": 638840213353178450
},
"EntityId": "620dcec7-1a09-4525-8ccd-4e6a273201ab"
},
"DeliveredAt": {
"Ticks": 638840213356162462
},
"IsValid": true,
"PowerOfAttorneyAttachmentStatus": {
"StatusName": "PowerOfAttorneyNotRequired"
},
"SignerBoxId": "4926b472842f47baa1a309100064ace4@diadoc.ru",
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000"
}
},
"SentAt": {...},
"Status": "Finished",
"UniversalMessage": {
"Attachment": {
"AttachmentFilename": "DP_UNISOOBSCH_2BM-7743911253-774301001-201512151245491116742_2BM-7717704518-770101001-201708200655456926042_20250528_6ca0fdf6-0ab4-461b-9c67-1b5d9c200bbb.xml",
"DisplayFilename": "Извещение о получении исправления",
"Entity": {
"Content": {
"Size": 856
},
"CreationTimestamp": {
"Ticks": 638840213353178450
},
"EntityId": "647250f0-c833-4cd2-a6b1-afe2ee812986"
}
},
"ContentTypeId": "receipt_uni_01",
"MessageInfo": {
"CodeGroup": "Receipt",
"Events": [
{
"PlainText": "",
"StatusCode": 1999
}
]
}
}
},
"RecipientResponse": {...},
"ResolutionEntities": {...},
"SenderReceipt": {...},
"SenderTitle": {...}
},
"DocumentId": {...},
"DocumentInfo": {...},
"LastEvent": {...}
}
]
}
Парсинг универсального сообщения
XML-файл универсального сообщения можно распарсить с помощью методов:
ParseUniversalMessageXml — парсит XML-файл, соответствующий
XSD-схеме, переданный в теле запроса метода;ParseUniversalMessage — парсит XML-файл универсального сообщения, который в виде сущности содержится внутри сообщения; будет работать после окончания переходного периода.
В ответе оба этих метода вернут упрощенный XML-файл универсального сообщения, соответствующий упрощенной XSD-схеме.
Обратите внимание, что во время переходного периода метод ParseUniversalMessage не работает и возвращает ошибки — он будет доступен только после окончания переходного периода. Для парсинга универсального сообщения во время переходного периода используйте метод ParseUniversalMessageXml.
Пример HTTP-запроса метода ParseUniversalMessageXml:
POST /ParseUniversalMessageXml HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Пример тела запроса метода ParseUniversalMessageXml:
<Файл ИдФайл="DP_UNISOOBSCH_2BM-1828306960-861201692-202407101103418496883_2BM-3990015462-927043935-202407101104400484330_20250207_80ca9e70-de3e-4af0-8cda-2b7205540ab9" ВерсПрог="Diadoc 1.0" ВерсФорм="5.01">
<Документ КНД="1115144">
<СведУС ДатаФорм="07.02.2025" ВремФорм="15.35.12" ИмяПолФайл="ON_NSCHFDOPPR_2BM-3990015462-927043935-202407101104400484330_2BM-1828306960-861201692-202407101103418496883_20250207_d1902c29-f5d4-4490-bbe0-a5e2de067e53" />
<СвСобытДок СтатусУС="3999">
<ТекстУС>Отказываю в подписи</ТекстУС>
</СвСобытДок>
<ОтпрУС ИдОтпрУС="2BM-3990015462-927043935-202407101104400484330">
<СвЛицОтпрУС Должн="Сотрудник">
<ФИО Фамилия="Иванов" Имя="Иван" Отчество="Иванович" />
</СвЛицОтпрУС>
</ОтпрУС>
<ПолучУС ИдПолучУС="2BM-1828306960-861201692-202407101103418496883" />
</Документ>
</Файл>
Пример тела ответа метода ParseUniversalMessageXml:
<?xml version="1.0" encoding="utf-8"?>
<UniversalMessage>
<UniversalMessageInfos>
<UniversalMessageInfo StatusCode="3999">
<PlainText>Отказываю в подписи</PlainText>
</UniversalMessageInfo>
</UniversalMessageInfos>
<Sender UseDefaultPersonInfo="false" Position="Сотрудник">
<Fio LastName="Иванов" FirstName="Иван" MiddleName="Иванович" />
</Sender>
</UniversalMessage>