GetDocflowEvents (V4)
Возвращает список событий, произошедших с документами.
Под событием понимается появление нового документа или изменение уже существующего.
- POST /V4/GetDocflowEvents
- Query Parameters:
boxId – идентификатор ящика организации в формате GUID.
- Request Headers:
Authorization – данные, необходимые для авторизации.
- Request Body:
Тело запроса должно содержать запрос на получение событий, представленный структурой GetDocflowEventsRequest.
- Status Codes:
200 OK – операция успешно завершена.
400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
401 Unauthorized – в запросе отсутствует HTTP-заголовок
Authorizationили в этом заголовке содержатся некорректные авторизационные данные.402 Payment Required – у указанного ящика закончилась подписка на API.
403 Forbidden – доступ к ящику с предоставленным авторизационным токеном запрещен или у пользователя нет прав для доступа ко всем документам организации.
405 Method Not Allowed – используется неподходящий HTTP-метод.
500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка.
- Response Body:
Тело ответа содержит список событий, представленный структурой GetDocflowEventsResponseV4.
Для выполнения метода текущий пользователь должен иметь доступ к следующим подразделениям, иначе метод вернет ошибку 403 (Forbidden):
к подразделению, идентификатор которого указан в теле запроса в поле
DepartmentIdструктуры GetDocflowEventsRequest,ко всем подразделениям организации, если параметр
DepartmentIdструктуры GetDocflowEventsRequest не указан.
Метод вернет всю доступную информацию по событиям, в том числе содержимое документов и подписей, если это было указано в запросе. В некоторых случаях получить содержимое документов невозможно, подробнее об этом в описании структуры Content.
Обратите внимание, что суммарный размер содержимого всех сущностей, хранящихся в поле GetDocflowEventsResponse.Events.Document.Docflow.DocumentAttachment.Attachment.Entity.Content.Data, не может превышать 1 048 576 байт.
Если при добавлении содержимого очередного документа этот размер будет превышен, то такое содержимое не будет добавлено в ответ. Если для каких-то документов содержимое не было получено в ответе метода, его можно получить с помощью метода GetEntityContent (V4).
Каждое событие в ответе может содержать состояние документа на момент этого события и состояние на момент предыдущего события, если вы укажете свойства GetDocflowEventsRequest.PopulateDocuments и GetDocflowEventsRequest.PopulatePreviousDocumentStates соответственно. Таким образом можно сравнить две версии документа и узнать произошедшие изменения.
Список событий Events в ответе GetDocflowEventsResponseV4 может содержать не более того количества элементов, которое было указано в параметре limit. Поэтому:
Если количество найденных событий меньше указанного в
limit, то метод вернет их полностью.Если количество найденных событий больше указанного в
limit, то в ответеEventsвернется только первая часть элементов в запрошенном количестве. При этом параметрTotalCountбудет содержать общее количество найденных событий, а параметрTotalCountTypeпокажет, точно ли посчитано значениеTotalCountили подсчет был ограничен.В этом случае получить весь список найденных событий можно постранично. Для этого вызывайте метод
GetDocflowEventsс теми же параметрами запроса и с указанием параметраAfterIndexKeyструктуры запроса GetDocflowEventsRequest до тех пор, пока список событий не будет вычитан полностью. В качестве параметраAfterIndexKeyнужно указывать ключ события из поля DocflowEventV3.IndexKey.
В зависимости от значения параметра AfterIndexKey метод работает следующим образом:
Если в запросе отсутствует параметр
AfterIndexKey, то метод вернет начало списка найденных событий.Если в запросе указан параметр
AfterIndexKey, то метод вернет список событий, следующих за событием с ключомAfterIndexKey; событие с ключомAfterIndexKeyв этот список не попадает.
Примеры использования
Пример HTTP-запроса:
POST /V4/GetDocflowEvents?boxId={{boxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Content-Type: application/json charset=utf-8
Accept: application/json
Пример тела запроса:
{
"Filter": {
"SortDirectionValue": "Ascending",
"FromTimestamp": null,
"ToTimestamp": null,
"SortDirection": 1
},
"AfterIndexKey": null,
"PopulateDocuments": true,
"InjectEntityContent": false,
"PopulatePreviousDocumentStates": false,
"MessageTypes": [
"Letter"
],
"DocumentDirections": [
"Outbound"
],
"DepartmentId": "",
"TypeNamedIds": [
"Nonformalized"
],
"CounteragentBoxId": "{{boxId_recipient}}",
"Limit": 100
}
Пример тела ответа:
{
"TotalCount": 2,
"Events": [
{
"EventId": "14a36d8e-3aba-11f0-8000-0000bd216658",
"Timestamp": {
"Ticks": 638839199333068174
},
"DocumentId": {
"MessageId": "eac38039-9e64-4ef9-ab7e-84a41193fcee",
"EntityId": "79b6c3f5-0a74-4e4a-96b6-86a815dbdea8"
},
"IndexKey": "CN2c3fjXrY45gMPqZJ75Tqt+hKQRk/zu9cO2eXQKSk6WtoaoFdveqI5toxS6OvARgAAAAL0hZlg=",
"Document": {
"DocumentId": {
"MessageId": "eac38039-9e64-4ef9-ab7e-84a41193fcee",
"EntityId": "79b6c3f5-0a74-4e4a-96b6-86a815dbdea8"
},
"LastEvent": {
"EventId": "14a36d8e-3aba-11f0-8000-0000bd216658",
"Timestamp": {
"Ticks": 638839199333068174
}
},
"DocumentInfo": {
"FullVersion": {
"TypeNamedId": "Nonformalized",
"Function": "default",
"Version": "v1"
},
"MessageType": "Letter",
"WorkflowId": 1,
"Participants": {
"Sender": {
"BoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"IsRoaming": false
},
"Recipient": {
"BoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"IsRoaming": false
},
"IsInternal": false,
"IsCrossBorder": false
},
"DocumentDirection": "Outbound",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"Metadata": [
{
"Key": "FileName",
"Value": "FileName.txt"
},
{
"Key": "DocumentNumber",
"Value": "123"
},
{
"Key": "DocumentDate",
"Value": "2025-05-27T00:00:00.0000000Z"
}
],
"CustomData": [],
"DocumentLinks": {
"InitialIds": [],
"SubordinateIds": []
},
"PacketInfo": {
"LockMode": "None"
},
"IsRead": true,
"IsDeleted": false,
"IsInvitation": false,
"LetterInfo": {
"IsEncrypted": false,
"ForwardDocumentEvents": [],
"IsTest": false
},
"EditingSettingId": "",
"HasUnreadOutOfWorkflowUniversalMessages": false
},
"Docflow": {
"SenderTitle": {
"IsFinished": true,
"Attachment": {
"Attachment": {
"Entity": {
"EntityId": "79b6c3f5-0a74-4e4a-96b6-86a815dbdea8",
"CreationTimestamp": {
"Ticks": 638839199331554676
},
"Content": {
"Size": 32837
}
},
"AttachmentFilename": "FileName.txt",
"DisplayFilename": "FileName.txt"
},
"Signature": {
"Cms": {
"EntityId": "4b8b8421-9354-43cc-9b7c-d5df0ada3a04",
"CreationTimestamp": {
"Ticks": 638839199331554676
},
"Content": {
"Size": 3213
}
},
"SignerBoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000",
"IsValid": true,
"PowerOfAttorneyAttachmentStatus": {
"StatusName": "PowerOfAttorneyRequired",
"Comment": "Документ подписан сертификатом физ. лица без МЧД"
},
"SignatureTypeInfo": {
"SignatureType": "OnVerification"
}
},
"Comment": {
"EntityId": "50104639-d56d-4037-bb65-8764f6af62cd",
"CreationTimestamp": {
"Ticks": 638839199331554676
},
"Content": {
"Size": 40
}
},
"ContentTypeId": "nonformalized_01"
},
"SentAt": {
"Ticks": 638839199331554676
},
"SenderSignatureStatus": "SenderSignatureUnchecked"
},
"ResolutionEntities": {
"Requests": [],
"Resolutions": [],
"ApprovementSignatures": [],
"SignatureDenials": []
},
"OuterDocflows": [],
"OuterDocflowEntities": [],
"DocflowStatus": {
"PrimaryStatus": {
"Severity": "Info",
"StatusText": "Отправлен"
},
"PowerOfAttorneyGeneralStatus": {
"Severity": "Warning",
"StatusNamedId": "IsNotAttached",
"StatusText": "Не приложена доверенность",
"Errors": []
}
}
}
}
},
{
"EventId": "14e501cd-3aba-11f0-8000-0001d1a58d3a",
"Timestamp": {
"Ticks": 638839199337365965
},
"DocumentId": {
"MessageId": "eac38039-9e64-4ef9-ab7e-84a41193fcee",
"EntityId": "79b6c3f5-0a74-4e4a-96b6-86a815dbdea8"
},
"IndexKey": "CN2c3fkZQc05gMPqZJ75Tqt+hKQRk/zu9cO2eXQKSk6WtoaoFdveqM0B5RS6OvARgAAAAdGljTo=",
"Document": {
"DocumentId": {
"MessageId": "eac38039-9e64-4ef9-ab7e-84a41193fcee",
"EntityId": "79b6c3f5-0a74-4e4a-96b6-86a815dbdea8"
},
"LastEvent": {
"EventId": "14e501cd-3aba-11f0-8000-0001d1a58d3a",
"Timestamp": {
"Ticks": 638839199337365965
}
},
"DocumentInfo": {
"FullVersion": {
"TypeNamedId": "Nonformalized",
"Function": "default",
"Version": "v1"
},
"MessageType": "Letter",
"WorkflowId": 1,
"Participants": {
"Sender": {
"BoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"IsRoaming": false
},
"Recipient": {
"BoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"IsRoaming": false
},
"IsInternal": false,
"IsCrossBorder": false
},
"DocumentDirection": "Outbound",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"Metadata": [
{
"Key": "FileName",
"Value": "test.png"
},
{
"Key": "DocumentNumber",
"Value": "123"
},
{
"Key": "DocumentDate",
"Value": "2025-05-27T00:00:00.0000000Z"
}
],
"CustomData": [],
"DocumentLinks": {
"InitialIds": [],
"SubordinateIds": []
},
"PacketInfo": {
"LockMode": "None"
},
"IsRead": true,
"IsDeleted": false,
"IsInvitation": false,
"LetterInfo": {
"IsEncrypted": false,
"ForwardDocumentEvents": [],
"IsTest": false
},
"EditingSettingId": "",
"HasUnreadOutOfWorkflowUniversalMessages": false
},
"Docflow": {
"SenderTitle": {
"IsFinished": true,
"Attachment": {
"Attachment": {
"Entity": {
"EntityId": "79b6c3f5-0a74-4e4a-96b6-86a815dbdea8",
"CreationTimestamp": {
"Ticks": 638839199331554676
},
"Content": {
"Size": 32837
}
},
"AttachmentFilename": "test.png",
"DisplayFilename": "test.png"
},
"Signature": {
"Cms": {
"EntityId": "4b8b8421-9354-43cc-9b7c-d5df0ada3a04",
"CreationTimestamp": {
"Ticks": 638839199331554676
},
"Content": {
"Size": 3213
}
},
"CadesT": {
"EntityId": "56b1798b-c4c6-454d-b35d-0cb6368db90e",
"CreationTimestamp": {
"Ticks": 638839199335411783
},
"Content": {
"Size": 6845
}
},
"SignerBoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000",
"IsValid": true,
"DeliveredAt": {
"Ticks": 638839199335411783
},
"PowerOfAttorneyAttachmentStatus": {
"StatusName": "PowerOfAttorneyRequired",
"Comment": "Документ подписан сертификатом физ. лица без МЧД"
}
},
"Comment": {
"EntityId": "50104639-d56d-4037-bb65-8764f6af62cd",
"CreationTimestamp": {
"Ticks": 638839199331554676
},
"Content": {
"Size": 40
}
},
"ContentTypeId": "nonformalized_01"
},
"SentAt": {
"Ticks": 638839199331554676
},
"DeliveredAt": {
"Ticks": 638839199335411783
},
"SenderSignatureStatus": "SenderSignatureCheckedAndValid"
},
"Confirmation": {
"IsFinished": true,
"ConfirmationAttachment": {
"Attachment": {
"Entity": {
"EntityId": "a361ceff-39fa-4dc8-996b-ad5fb135d272",
"CreationTimestamp": {
"Ticks": 638839199335411783
},
"Content": {
"Size": 5208
}
},
"AttachmentFilename": "DP_PDPOL_2BM-6125600340-732644841-202407101103418496883_2BM_20250527_a361ceff-39fa-4dc8-996b-ad5fb135d272.xml",
"DisplayFilename": "Подтверждение даты получения"
},
"Signature": {
"Cms": {
"EntityId": "50440c06-474e-421a-868a-ec73567692f0",
"CreationTimestamp": {
"Ticks": 638839199335411783
},
"Content": {
"Size": 3532
}
},
"CadesT": {
"EntityId": "65b0d8cb-a0fe-404d-aa65-65ed29cecf1f",
"CreationTimestamp": {
"Ticks": 638839199335411783
},
"Content": {
"Size": 7163
}
},
"SignerBoxId": "00000000000000000000000000000000@diadoc.ru",
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000",
"IsValid": true,
"DeliveredAt": {
"Ticks": 638839199335411783
},
"PowerOfAttorneyAttachmentStatus": {
"StatusName": "PowerOfAttorneyNotRequired"
}
},
"ContentTypeId": "send_confirmation_133_01_03"
},
"ConfirmedAt": {
"Ticks": 638839199335411783
}
},
"ResolutionEntities": {
"Requests": [],
"Resolutions": [],
"ApprovementSignatures": [],
"SignatureDenials": []
},
"OuterDocflows": [],
"OuterDocflowEntities": [],
"DocflowStatus": {
"PrimaryStatus": {
"Severity": "Info",
"StatusText": "Документооборот завершен"
},
"PowerOfAttorneyGeneralStatus": {
"Severity": "Warning",
"StatusNamedId": "IsNotAttached",
"StatusText": "Не приложена доверенность",
"Errors": []
}
}
}
},
"PreviousEventId": "14a36d8e-3aba-11f0-8000-0000bd216658",
"PreviousDocumentState": {
"DocumentId": {
"MessageId": "eac38039-9e64-4ef9-ab7e-84a41193fcee",
"EntityId": "79b6c3f5-0a74-4e4a-96b6-86a815dbdea8"
},
"LastEvent": {
"EventId": "14a36d8e-3aba-11f0-8000-0000bd216658",
"Timestamp": {
"Ticks": 638839199333068174
}
},
"DocumentInfo": {
"FullVersion": {
"TypeNamedId": "Nonformalized",
"Function": "default",
"Version": "v1"
},
"MessageType": "Letter",
"WorkflowId": 1,
"Participants": {
"Sender": {
"BoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"IsRoaming": false
},
"Recipient": {
"BoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"IsRoaming": false
},
"IsInternal": false,
"IsCrossBorder": false
},
"DocumentDirection": "Outbound",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"Metadata": [
{
"Key": "FileName",
"Value": "e6a02dc1-a673-41a2-b217-7bd1379130fc_пример (1).png"
},
{
"Key": "DocumentNumber",
"Value": "123"
},
{
"Key": "DocumentDate",
"Value": "2025-05-27T00:00:00.0000000Z"
}
],
"CustomData": [],
"DocumentLinks": {
"InitialIds": [],
"SubordinateIds": []
},
"PacketInfo": {
"LockMode": "None"
},
"IsRead": true,
"IsDeleted": false,
"IsInvitation": false,
"LetterInfo": {
"IsEncrypted": false,
"ForwardDocumentEvents": [],
"IsTest": false
},
"EditingSettingId": "",
"HasUnreadOutOfWorkflowUniversalMessages": false
},
"Docflow": {
"SenderTitle": {
"IsFinished": true,
"Attachment": {
"Attachment": {
"Entity": {
"EntityId": "79b6c3f5-0a74-4e4a-96b6-86a815dbdea8",
"CreationTimestamp": {
"Ticks": 638839199331554676
},
"Content": {
"Size": 32837
}
},
"AttachmentFilename": "e6a02dc1-a673-41a2-b217-7bd1379130fc_пример (1).png",
"DisplayFilename": "E6a02dc1-a673-41a2-b217-7bd1379130fc_пример (1).png"
},
"Signature": {
"Cms": {
"EntityId": "4b8b8421-9354-43cc-9b7c-d5df0ada3a04",
"CreationTimestamp": {
"Ticks": 638839199331554676
},
"Content": {
"Size": 3213
}
},
"SignerBoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000",
"IsValid": true,
"PowerOfAttorneyAttachmentStatus": {
"StatusName": "PowerOfAttorneyRequired",
"Comment": "Документ подписан сертификатом физ. лица без МЧД"
},
"SignatureTypeInfo": {
"SignatureType": "OnVerification"
}
},
"Comment": {
"EntityId": "50104639-d56d-4037-bb65-8764f6af62cd",
"CreationTimestamp": {
"Ticks": 638839199331554676
},
"Content": {
"Size": 40
}
},
"ContentTypeId": "nonformalized_01"
},
"SentAt": {
"Ticks": 638839199331554676
},
"SenderSignatureStatus": "SenderSignatureUnchecked"
},
"ResolutionEntities": {
"Requests": [],
"Resolutions": [],
"ApprovementSignatures": [],
"SignatureDenials": []
},
"OuterDocflows": [],
"OuterDocflowEntities": [],
"DocflowStatus": {
"PrimaryStatus": {
"Severity": "Info",
"StatusText": "Отправлен"
},
"PowerOfAttorneyGeneralStatus": {
"Severity": "Warning",
"StatusNamedId": "IsNotAttached",
"StatusText": "Не приложена доверенность",
"Errors": []
}
}
}
}
}
],
"TotalCountType": "Equal"
}
Пример запроса с использованием C# SDK:
GetDocflowEventsResponseV4 GetDocflowEventsV4(string authToken, string boxId, GetDocflowEventsRequest request);
Получение всех событий в ящике за период с 13.11.2024 до 20.11.2024:
var request = new GetDocflowEventsRequest
{
Filter = new TimeBasedFilter
{
FromTimestamp = new Timestamp(new DateTime(2024, 11, 13).Ticks), // может отсутствовать
ToTimestamp = new Timestamp(new DateTime(2024, 11, 20).Ticks), // может отсутствовать
},
AfterIndexKey = null
};
while (true)
{
var response = api.Docflow.GetDocflowEventsV4(token, boxId, request);
if (!response.Events.Any())
break;
Console.Out.WriteLine("Events count: {0} (of total {1})", response.Events.Count, response.TotalCount);
request.AfterIndexKey = response.Events.Last().IndexKey;
}
См. также
- Инструкции:
- Методы для работы с документооборотом:
GetDocflowEvents (V4) — возвращает список событий, произошедших с документами
GetDocflowEvents (V5) — возвращает список событий, произошедших с документами, корректно отображая данные для многотитульных документов
GetDocflows (V4) — возвращает список документов с информацией о документообороте по их идентификаторам
GetDocflows (V5) — возвращает список документов с информацией о документообороте по их идентификаторам, корректно отображая данные для многотитульных документов
GetDocflowsByPacketId (V4) — возвращает список документов, находящихся в пакете
GetDocflowsByPacketId (V5) — возвращает список документов, находящихся в пакете, корректно отображая данные для многотитульных документов
SearchDocflows (V4) — выполняет поиск документов по строке запроса
SearchDocflows (V5) — выполняет поиск документов по строке запроса, корректно отображая данные для многотитульных документов