GetCounteragentEvents (V1)

Возвращает список событий по изменению отношений с контрагентами.

GET /V1/GetCounteragentEvents

Query Parameters:

boxId – идентификатор ящика организации.
afterIndexKey – ключ для постраничного получения списка найденных событий, указывающий на начало очередной страницы. Ключ может содержать недопустимые символы, поэтому должен быть закодирован в URL-формат. Необязательный параметр.
timestampFromTicks – метка времени, задающая начальную точку периода. Задается целое число тиков, прошедших с момента времени 00:00:00 01.01.0001. Необязательный параметр.
timestampToTicks – метка времени, задающая конечную точку периода. Задается целое число тиков, прошедших с момента времени 00:00:00 01.01.0001. Необязательный параметр.
limit – максимальное количество элементов, возвращаемых на одной странице в ответе. Не влияет на общее количество найденных событий BoxCounteragentEventList.TotalCount. Принимает значения от 1 до 100, по умолчанию равен 100. Необязательный параметр.

Request Headers:

Authorization – данные, необходимые для авторизации.

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:

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

Метод доступен только сотрудникам с доступом к ящику и разрешением OrganizationUserPermissions.CanManageCounteragents, которое позволяет видеть списки контрагентов и работать с ними.

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

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

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

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

В этом случае получить весь список найденных событий можно постранично. Для этого вызывайте метод GetCounteragentEvents с теми же параметрами запроса и с указанием параметра afterIndexKey до тех пор, пока список событий не будет вычитан полностью. В качестве параметра afterIndexKey нужно указывать ключ события из поля BoxCounteragentEvent.IndexKey, предварительно закодировав его в URL-формат.

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

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

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

Примеры использования

Пример HTTP-запроса:

GET /V1/GetCounteragentEvents?boxId={{boxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json; charset=utf-8

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

{
    "Events": [
        {
            "EventId": "765de718-442e-11ef-8007-828b06413688",
            "Counteragent": {
                "CounteragentBoxId": "09ae254c-5cd0-4082-84de-7ccb46d86f82",
                "Status": "IsRejectedByMe",
                "EventTimestampTicks": 638568119816675479,
                "LastEventComment": "удаление из списка контрагентов",
                "MessageToCounteragent": "удаление из списка контрагентов"
            },
            "IndexKey": "CNymUlqSJxhMJa4J0FyCQITefMtG2G+C",
            "EventTypes": [
                "IBrokeUpWithCounteragent"
            ]
        },
        {
            "EventId": "7c313a39-442e-11ef-8010-9fb6f747d48a",
            "Counteragent": {
                "CounteragentBoxId": "09ae254c-5cd0-4082-84de-7ccb46d86f82",
                "Status": "IsInvitedByMe",
                "EventTimestampTicks": 638568119914355510
            },
            "IndexKey": "CNymUmBlejlMJa4J0FyCQITefMtG2G+C",
            "EventTypes": [
                "IInvitedCounteragent"
            ]
        }
    ],
    "TotalCount": 2,
    "TotalCountType": "Equal"
}

См. также

Инструкции:

Лента событий по контрагентам

Методы для работы с событиями по контрагентам:

GetCounteragentEvents (V1) — возвращает список событий по изменению отношений с контрагентами