GetNewEvents

Метод для получения ленты событий в ящике.

Имя ресурса: /V7/GetNewEvents

HTTP метод: GET

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

  • boxId: идентификатор ящика;
  • afterEventId: идентификатор последнего полученного события (может отсутствовать);
  • afterIndexKey: ключ события, используемый для постраничной выгрузки (может отсутствовать);
  • departmentId: идентификатор подразделения, из которого производится выборка документов. Параметр может отсутствовать, если пользователь имеет доступ ко всем документам организации. Пользователю с ограниченным доступом необходимо задать параметр. Указать можно любое подразделение, к документам которого пользователь имеет доступ;
  • messageType: тип сообщения (Draft, Letter, Template) (может отсутствовать). Возможно указание нескольких идентификаторов через запятую;
  • typeNamedId: строковый идентификатор типа документа (может отсутствовать). Возможно указание нескольких идентификаторов через запятую;
  • documentDirection: направление документа относительно данного ящика (Inbound, Outbound, Internal) (может отсутствовать). Возможно указание нескольких идентификаторов через запятую;
  • timestampFromTicks: метка времени, задающая начальную точку периода (может отсутствовать). Задается целое число тиков (100-наносекундных интервалов), прошедших с момента времени 00:00:00 01.01.0001;
  • timestampToTicks: метка времени, задающая конечную точку периода (может отсутствовать). Задается целое число тиков (100-наносекундных интервалов), прошедших с момента времени 00:00:00 01.01.0001;
  • counteragentBoxId: идентификатор ящика контрагента (может отсутствовать);
  • orderBy: задает порядок сортировки документов в выдаче по времени возникновения события, принимает значение Ascending или Descending (может отсутствовать, значение по умолчанию - Ascending);
  • limit: максимальное количество документов в ответе (может отсутствовать, в этом случае в ответе будет не больше 100 документов). Может принимать значения от 1 до 100.

В запросе должен присутствовать HTTP-заголовок Authorization с необходимыми данными для авторизации.

Ленту событий по всему ящику могут получить пользователи с доступом ко всем документам организации. В данном случае параметр departmentId не задается.

Если у пользователя ограниченный доступ, то необходимо задать параметр departmentId. Указать можно любое подразделение, к документам которого пользователь имеет доступ.

Если задан параметр departmentId, метод вернет события только по указанному подразделению.

Подразделение организации, в котором состоит пользователь, можно найти в структуре OrganizationUserPermissions, в поле UserDepartmentId. Уровень доступа возвращается в поле DocumentAccessLevel.

Примечание

Так как черновики не имеют привязки к подразделению, то все события по черновикам доступны только пользователям, имеющим доступ ко всем документам организации.

Важно

К подразделению организации привязываются все события, произошедшие с 15.03.2017. События, произошедшие до 15.03.2017, может получить только пользователь, который имеет доступ ко всем документам организации.

В теле ответа содержится список событий в ящике boxId, следующих за событием с идентификатором afterEventId или afterIndexKey в хронологическом порядке. Одновременно afterIndexKey и afterEventId не могут быть заданы.

При этом само событие с идентификатором afterEventId или afterIndexKey в этот список не включается. Список возвращается в виде сериализованной структуры данных BoxEventList.

Содержимое документов, ассоциированных с событиями из списка, в структуру данных не сохраняется, то есть возвращается только метаинформация об изменениях, в ящике. Такой подход гарантирует, что ответ на запрос имеет предсказуемый и небольшой размер.

Если список изменений содержит более 100 элементов, то в ответе возвращаются первые 100 событий, а поле BoxEventList.TotalCount содержит общее количество событий, удовлетворяющим параметрам запроса. Поле BoxEventList.TotalCountType указывает, точно ли посчитано значение TotalCount или подсчет был ограничен соответствующим значением. Если параметры afterEventId или afterIndexKey отсутствует в запросе, то метод возвращает самые старые события из ящика boxId (с начала истории изменений в ящике).

Предполагается, что интеграционное решение будет помнить идентификатор последнего прочитанного события (BoxEvent.EventId) для конкретного ящика. Соответственно, данный метод позволяет интеграционному решению узнать, какие изменения произошли в ящике с момента последнего подключения интеграционного решения к Диадоку.

Возможные HTTP-коды возврата:

  • 200 (OK) - операция успешно завершена;
  • 400 (Bad Request) - данные в запросе имеют неверный формат или отсутствуют обязательные параметры;
  • 401 (Unauthorized) - в запросе отсутствует HTTP-заголовок Authorization, или в этом заголовке содержатся некорректные авторизационные данные;
  • 403 (Forbidden) - доступ к ящику с предоставленным авторизационным токеном запрещен;
  • 405 (Method not allowed) - используется неподходящий HTTP-метод;
  • 500 (Internal server error) - при обработке запроса возникла непредвиденная ошибка.