Перейти к основному содержимому

GetDocflowEvents (V3)

warning

Метод устарел и будет удален из API после 03 апреля 2027 года. Подробнее в истории изменений. Используйте актуальную версию метода — GetDocflowEvents (V5).

Возвращает список событий, произошедших с документами.

Под событием понимается появление нового документа или изменение уже существующего.

POST /V3/GetDocflowEvents

Параметры запроса

  • boxId — идентификатор ящика организации.

Заголовки запроса

Тело запроса

Тело запроса должно содержать запрос на получение событий, представленный структурой 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) — выполняет поиск документов по строке запроса, корректно отображая данные для многотитульных документов

Оцените материал страницы

Нашли ошибку или столкнулись с проблемой?

СКБ Контурс 1988 года