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

GetDocflowEvents (V2)

warning

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

Метод GetDocflowEvents возвращает список событий, произошедших с документами в указанном ящике. Под событием понимается появление нового документа или изменение уже существующего.

POST /V2/GetDocflowEvents

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

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

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

Тело запроса

Тело запроса должно содержать структуру GetDocflowEventsRequest.

Коды ответа

  • 200 — операция успешно завершена.
  • 400 — данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
  • 401 — в запросе отсутствует HTTP-заголовок Authorization или в этом заголовке содержатся некорректные авторизационные данные.
  • 402 — у организации с указанным идентификатором boxId закончилась подписка на API.
  • 403 — доступ к ящику с предоставленным авторизационным токеном запрещен или у пользователя нет прав для доступа ко всем документам организации.
  • 405 — используется неподходящий HTTP-метод.
  • 500 — при обработке запроса возникла непредвиденная ошибка.

Тело ответа

Тело ответа содержит список событий, представленный структурой GetDocflowEventsResponse.

Для выполнения метода текущий пользователь должен иметь доступ ко всем документам в ящике, иначе метод вернет ошибку 403 (Forbidden).

Метод добавляет в ответ всю информацию, относящуюся к цепочке документооборота, в том числе бинарные представления документов и подписей, если они есть (возвращаемая цепочка может не содержать бинарного представления документов, подробнее об этом в описании структуры Content). Но метод имеет ограничение на суммарный размер всех бинарных представлений, хранящихся в поле GetDocflowEventsResponse.Events.Document.Docflow.DocumentAttachment.Attachment.Entity.Content.Data, — он не должен превышать 1048576 байт. Если при добавлении очередного бинарного представления суммарный размер превысит это значение, то оно не будет добавлено в ответ метода. Вы можете получить такое бинарное представление с помощью метода GetEntityContent (V4).

Каждое событие в ответе может содержать состояние документа на момент этого события и состояние на момент предыдущего события, если вы укажете свойства GetDocflowEventsRequest.PopulateDocuments и GetDocflowEventsRequest.PopulatePreviousDocumentStates соответственно. Таким образом можно сравнить две версии документа и узнать произошедшие изменения.

Список событий GetDocflowEventsResponse.Events может содержать не больше 100 элементов. Поэтому:

  • Если найденных событий меньше 100, то метод вернет их полностью.

  • Если найденных событий больше 100, то в ответе GetDocflowEventsResponse.Events вернутся только первые 100 элементов. При этом параметр GetDocflowEventsResponse.TotalCount будет содержать общее количество найденных событий, а параметр GetDocflowEventsResponse.TotalCountType покажет, точно ли посчитано значение TotalCount или подсчет был ограничен.

    В этом случае получить весь список найденных событий можно постранично. Для этого вызывайте метод GetDocflowEvents с теми же параметрами запроса и с указанием параметра AfterIndexKey структуры запроса GetDocflowEventsRequest до тех пор, пока список событий не будет вычитан полностью. В качестве параметра AfterIndexKey нужно указывать ключ события из поля DocflowEvent.IndexKey.

В зависимости от значения параметра AfterIndexKey метод работает следующим образом:

  • Если в запросе отсутствует параметр AfterIndexKey, то метод вернет начало списка найденных событий.
  • Если в запросе указан параметр AfterIndexKey, то метод вернет список событий, следующих за событием с ключом AfterIndexKey; событие с ключом AfterIndexKey в этот список не попадает.
SDK
GetDocflowEventsResponse GetDocflowEventsV2(string authToken, string boxId, GetDocflowEventsRequest request);

Пример использования (C#)

Получение всех событий в ящике за период с 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.GetDocflowEventsV2(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;
}

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

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

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