GetDocflowEvents (V3)
Метод устарел и будет удален из API после 03 апреля 2027 года. Подробнее в истории изменений. Используйте актуальную версию метода — GetDocflowEvents (V5).
Возвращает список событий, произошедших с документами.
Под событием понимается появление нового документа или изменение уже существующего.
POST /V3/GetDocflowEvents
Параметры запроса
boxId— идентификатор ящика организации.
Заголовки запроса
Authorization— данные, необходимые для авторизации.
Тело запроса
Тело запроса должно содержать запрос на получение событий, представленный структурой GetDocflowEventsRequest.
Коды ответа
200— операция успешно завершена.400— данные в запросе имеют неверный формат или отсутствуют обязательные параметры.401— в запросе отсутствует HTTP-заголовокAuthorizationили в этом заголовке содержатся некорректные авторизационные данные.402— у указанного ящика закончилась подписка на API.403— доступ к ящику с предоставленным авторизационным токеном запрещен или у пользователя нет прав для доступа ко всем документам организации.405— используется неподходящий HTTP-метод.500— при обработке запроса возникла непредвиденная ошибка.
Тело ответа
Тело ответа содержит список событий, представленный структурой GetDocflowEventsResponseV3.
Для выполнения метода текущий пользователь должен иметь доступ к следующим подразделениям, иначе метод вернет ошибку 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 в ответе GetDocflowEventsResponseV3 может содержать не более того количества элементов, которое было указано в параметре limit. Поэтому:
-
Если количество найденных событий меньше указанного в
limit, то метод вернет их полностью. -
Если количество найденных событий больше указанного в
limit, то в ответеEventsвернется только первая часть элементов в запрошенном количестве. При этом параметрTotalCountбудет содержать общее количество найденных событий, а параметрTotalCountTypeпокажет, точно ли посчитано значениеTotalCountили подсчет был ограничен.В этом случае получить весь список найденных событий можно постранично. Для этого вызывайте метод
GetDocflowEventsс теми же параметрами запроса и с указанием параметраAfterIndexKeyструктуры запроса GetDocflowEventsRequest до тех пор, пока список событий не будет вычитан полностью. В качестве параметраAfterIndexKeyнужно указывать ключ события из поля DocflowEventV3.IndexKey.
В зависимости от значения параметра AfterIndexKey метод работает следующим образом:
- Если в запросе отсутствует параметр
AfterIndexKey, то метод вернет начало списка найденных событий. - Если в запросе указан параметр
AfterIndexKey, то метод вернет список событий, следующих за событием с ключомAfterIndexKey; событие с ключомAfterIndexKeyв этот список не попадает.
Примеры использования
Пример HTTP-запроса:
POST /V3/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
Пример тела запроса:
{
"MessageTypes": [
"Letter"
],
"DocumentDirections": [
"Outbound"
]
}
Пример тела ответа:
{
"TotalCount": 7,
"Events": [
{
"EventId": "382c1700-1a91-11f0-8000-00006b8759b7",
"Timestamp": {
"Ticks": 638803839463479040
},
"DocumentId": {
"MessageId": "a73ca2e3-3d5c-4207-886c-9b854c179e15",
"EntityId": "d084afd4-ec41-4fb6-9b5b-cf3e3ac5bef7"
},
"IndexKey": "CN18tRxgVwDjojynXD0HQohsm4VMF54V1K+E0EHstk+bW88+OsW+9wAXLDiRGvARgAAAAGuHWbc="
},
{
"EventId": "386e8b9e-1a91-11f0-8000-00006b8759b7",
"Timestamp": {
"Ticks": 638803839467834270
},
"DocumentId": {
"MessageId": "a73ca2e3-3d5c-4207-886c-9b854c179e15",
"EntityId": "d084afd4-ec41-4fb6-9b5b-cf3e3ac5bef7"
},
"IndexKey": "CN18tRyiy57jojynXD0HQohsm4VMF54V1K+E0EHstk+bW88+OsW+956LbjiRGvARgAAAAGuHWbc=",
"PreviousEventId": "382c1700-1a91-11f0-8000-00006b8759b7"
},
{
"EventId": "c8822c05-849d-11f0-8001-0001ef016cd1",
"Timestamp": {
"Ticks": 638920441657191429
},
"DocumentId": {
"MessageId": "4366e677-38a1-4c42-ad60-caebfdbaed0f",
"EntityId": "e33d3903-6125-4542-9548-73000b94d852"
},
"IndexKey": "CN3mway2bAV35mZDoThCTK1gyuv9uu0PAzk94yVhQkWVSHMAC5TYUgUsgsidhPARgAEAAe8BbNE="
},
{
"EventId": "c8ba64bd-849d-11f0-8000-000214efb30b",
"Timestamp": {
"Ticks": 638920441660875965
},
"DocumentId": {
"MessageId": "4366e677-38a1-4c42-ad60-caebfdbaed0f",
"EntityId": "e33d3903-6125-4542-9548-73000b94d852"
},
"IndexKey": "CN3mwazupL135mZDoThCTK1gyuv9uu0PAzk94yVhQkWVSHMAC5TYUr1kusidhPARgAAAAhTvsws=",
"PreviousEventId": "c8822c05-849d-11f0-8001-0001ef016cd1"
},
{
"EventId": "d5d35788-d5bd-11f0-8000-000168dfe96f",
"Timestamp": {
"Ticks": 639009639761418120
},
"DocumentId": {
"MessageId": "ef8d67b0-7734-49bd-abbe-f0eade812f63",
"EntityId": "88c0088a-fec8-40bd-ad4c-5a22fd165683"
},
"IndexKey": "CN434boHl4iwZ43vNHe9Sau+8OregS9jigjAiMj+vUCtTFoi/RZWg4hX09W91fARgAAAAWjf6W8="
},
{
"EventId": "d60a32f6-d5bd-11f0-8000-0000844f4d83",
"Timestamp": {
"Ticks": 639009639765013238
},
"DocumentId": {
"MessageId": "ef8d67b0-7734-49bd-abbe-f0eade812f63",
"EntityId": "88c0088a-fec8-40bd-ad4c-5a22fd165683"
},
"IndexKey": "CN434bo+cvawZ43vNHe9Sau+8OregS9jigjAiMj+vUCtTFoi/RZWg/YyCta91fARgAAAAIRPTYM=",
"PreviousEventId": "d5d35788-d5bd-11f0-8000-000168dfe96f"
},
{
"EventId": "d875caa6-d5bd-11f0-8000-000168dfe96f",
"Timestamp": {
"Ticks": 639009639805618854
},
"DocumentId": {
"MessageId": "ef8d67b0-7734-49bd-abbe-f0eade812f63",
"EntityId": "88c0088a-fec8-40bd-ad4c-5a22fd165683"
},
"IndexKey": "CN434byqCqawZ43vNHe9Sau+8OregS9jigjAiMj+vUCtTFoi/RZWg6bKddi91fARgAAAAWjf6W8=",
"PreviousEventId": "d60a32f6-d5bd-11f0-8000-0000844f4d83"
}
],
"TotalCountType": "Equal"
}
Пример запроса с использованием C# SDK:
GetDocflowEventsResponseV3 GetDocflowEventsV3(string authToken, string boxId, GetDocflowEventsRequest request);
Получение всех событий в ящике за период с 13.11.2013 до 20.11.2013:
var request = new GetDocflowEventsRequest
{
Filter = new TimeBasedFilter
{
FromTimestamp = new Timestamp(new DateTime(2013, 11, 13).Ticks), // может отсутствовать
ToTimestamp = new Timestamp(new DateTime(2013, 11, 20).Ticks), // может отсутствовать
},
AfterIndexKey = null
};
while (true)
{
var response = api.Docflow.GetDocflowEventsV3(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) — выполняет поиск документов по строке запроса, корректно отображая данные для многотитульных документов