GetNewEvents

Метод GetNewEvents возвращает ленту событий в ящике.

GET /V7/GetNewEvents
Query Parameters:

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

  • afterEventId – идентификатор последнего полученного события. Параметр устарел. Рекомендуем использовать параметр afterIndexKey.

  • afterIndexKey – уникальный ключ, позволяющий итерироваться по списку событий. Нельзя указывать одновременно с afterEventId. Необязательный параметр.

  • departmentId – идентификатор подразделения, из которого производится выборка документов.

  • messageType –

    тип cообщения. Можно указать несколько значений через запятую. Необязательный параметр. Принимает значения:

    • Draft — черновик,

    • Letter — письмо,

    • Template — шаблон.

  • typeNamedId – строковый идентификатор типа документа. Доступные типы можно получить с помощью метода GetDocumentTypes. Можно указать несколько значений через запятую. Необязательный параметр.

  • documentDirection –

    направление документа относительно текущего ящика. Можно указать несколько значений через запятую. Необязательный параметр. Принимает значения:

    • Inbound — входящие,

    • Outbound — исходящие,

    • Internal — внутренние.

  • timestampFromTicks – метка времени, задающая начальную точку периода. Задается целое число тиков, прошедших с момента времени 00:00:00 01.01.0001. Необязательный параметр.

  • timestampToTicks – метка времени, задающая конечную точку периода. Задается целое число тиков, прошедших с момента времени 00:00:00 01.01.0001. Необязательный параметр.

  • counteragentBoxId – идентификатор ящика контрагента. Необязательный параметр.

  • orderBy – порядок сортировки документов в выдаче по времени возникновения события. Может принимать значения: Ascending, Descending. Необязательный параметр. По умолчанию имеет значение Ascending.

  • limit – максимальное количество документов в ответе. Может принимать значение от 1 до 100. Необязательный параметр. По умолчанию имеет значение 100.

Request Headers:
Status Codes:

  • 200 OK – операция успешно завершена.

  • 400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры.

  • 401 Unauthorized – в запросе отсутствует HTTP-заголовок Authorization или в этом заголовке содержатся некорректные авторизационные данные.

  • 402 Payment Required – у организации с указанным идентификатором boxId отсутствует или закончилась подписка на API.

  • 403 Forbidden – доступ к ящику с предоставленным авторизационным токеном запрещен.

  • 405 Method Not Allowed – используется неподходящий HTTP-метод.

  • 500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка.

Response Body:

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

Если у пользователя есть доступ ко всем документам организации, параметр departmentID можно не указывать, иначе он является обязательным: укажите в нем идентификатор подразделения, к документам которого у пользователя есть доступ. Подразделение указано в поле UserDepartmentId структуры OrganizationUserPermissions. Уровень доступа указан в поле DocumentAccessLevel структуры OrganizationUserPermissions.

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

Важно

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

Если у пользователя есть доступ ко всем документам организации, в ленту попадут события по всему ящику. Доступ пользователя можно увидеть в поле DocumentAccessLevel структуры OrganizationUserPermissions, для пользователя с доступом ко всем документам организации значение будет DocumentAccessLevel = AllDocuments.

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

Список BoxEventList.Events может содержать не более 100 элементов. Чтобы получить остальные элементы, вызовите метод GetNewEvents с теми же параметрами и с указанием afterIndexKey. В зависимости от значения параметра afterIndexKey метод работает следующим образом:

  • Если в запросе отсутствует параметр afterIndexKey, то метод вернет начало списка событий, удовлетворяющих фильтру.

  • Если в запросе указан параметр afterIndexKey, то возвращенный список начнется с события, следующего за событием с ключом afterIndexKey; событие с ключом afterIndexKey в этот список не попадает.

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

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

Сохраните в своем интеграционном решении идентификатор BoxEvent.IndexKey для конкретного ящика. При следующем вызове метода GetNewEvents укажите его в параметре afterIndexKey: так вы сможете узнать, какие изменения произошли в ящике с момента последнего вызова.

См. также

Другие методы для работы с событиями:

  • GetEvent — возвращает информацию о конкретном событии

  • GetForwardedDocumentEvents — возвращает список событий пересылки документов в ящик

  • GetLastEvent — возвращает последнее событие в ящике