GetDocflowEvents (V4)

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

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

POST /V4/GetDocflowEvents

Query Parameters:

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

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

Пример тела запроса:

{
    "Requests": {
        "DocumentId": "{{documentId}}"
    }
}

Пример тела ответа:

{
    "Events": [
        {
            "DocumentId": {
                "EntityId": "4bf9d9b4-93e6-4bda-85ed-5c83e1b075cb",
                "MessageId": "3ebd9963-9c29-4cd7-a28b-93b9c5e294cc"
            },
            "EventId": "b40c3a5d-3eae-11ef-8000-0000bb7ed571",
            "IndexKey": "CNyg0phAel1jmb0+KZzXTKKLk7nF4pTMtNn5S+aT2kuF7VyD4bB1y106DLSuPu8RgAAAALt+1XE=",
            "Timestamp": {
                "Ticks": 638562073537706589
            }
        },
        {
            "DocumentId": {
                "EntityId": "4bf9d9b4-93e6-4bda-85ed-5c83e1b075cb",
                "MessageId": "3ebd9963-9c29-4cd7-a28b-93b9c5e294cc"
            },
            "EventId": "b450a59b-3eae-11ef-8000-00017c848bc8",
            "IndexKey": "CNyg0piE5Ztjmb0+KZzXTKKLk7nF4pTMtNn5S+aT2kuF7VyD4bB1y5ulULSuPu8RgAAAAXyEi8g=",
            "PreviousEventId": "b40c3a5d-3eae-11ef-8000-0000bb7ed571",
            "Timestamp": {
                "Ticks": 638562073542190491
            }
        },
        {
            "DocumentId": {
                "EntityId": "341808f8-2cfb-48d8-a6fa-8bb26659f67d",
                "MessageId": "e28ec2d1-3eeb-4fd0-851e-0da0c487249a"
            },
            "EventId": "fa1f7c22-3ebd-11ef-8000-00017c848bc8",
            "IndexKey": "CNyg4d5TvCLRwo7i6z7QT4UeDaDEhySa+AgYNPss2Eim+ouyZln2fSJ8H/q9Pu8RgAAAAXyEi8g=",
            "Timestamp": {
                "Ticks": 638562139137883170
            }
        }
    ],
    "TotalCount": 3,
    "TotalCountType": "Equal"
}

Пример запроса с использованием C# SDK:

GetDocflowEventsResponseV4 GetDocflowEvents(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.GetDocflowEvents(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 (V3) — возвращает список событий, произошедших с документами
GetDocflowEvents (V4) — возвращает список событий, произошедших с документами
GetDocflows (V3) — возвращает список документов с информацией о документообороте по их идентификаторам
GetDocflows (V4) — возвращает список документов с информацией о документообороте по их идентификаторам
GetDocflowsByPacketId (V3) — возвращает список документов, находящихся в пакете
GetDocflowsByPacketId (V4) — возвращает список документов, находящихся в пакете
SearchDocflows (V3) — выполняет поиск документов по строке запроса
SearchDocflows (V4) — выполняет поиск документов по строке запроса

Предыдущие версии метода:

GetDocflowEvents (V3)

Устаревшие версии метода:

GetDocflowEvents (V2)