Пагинация

Все ресурсы (сделки, контакты, компании, задачи) поддерживают два режима работы метода list().

Режимы работы list()

Вызов

Поведение

Тип возврата

client.leads.list()

Авто-пагинация: обходит все страницы

Iterator[Lead]

client.leads.list(page=2)

Одна конкретная страница

list[Lead]

Авто-пагинация (рекомендуется)

Если page не передан, SDK автоматически запрашивает страницы одну за другой и выдаёт элементы по мере загрузки (ленивый Iterator). Цикл завершается, когда API возвращает пустую страницу или страницу с числом элементов меньше limit.

# Обойти все сделки
for lead in client.leads.list():
    print(lead.id, lead.name)

# Собрать всё в список
all_leads = list(client.leads.list())

# Кастомный размер страницы при авто-пагинации
for contact in client.contacts.list(limit=100):
    process(contact)

# С фильтром и сортировкой
for task in client.tasks.list(
    filter={"responsible_user_id": 42},
    order={"created_at": "desc"},
):
    print(task.text)

По умолчанию авто-пагинация запрашивает 50 элементов на страницу.

Одна страница

Передайте page явно — метод вернёт обычный list и сделает ровно один запрос:

leads = client.leads.list(page=1, limit=250)
contacts = client.contacts.list(page=3, limit=50, query="Иван")

Это поведение аналогично предыдущим версиям SDK.

Сигнал конца данных

SDK считает страницу последней в двух случаях:

  1. API вернул пустой список (_embedded.{entity} == []).

  2. Количество элементов на странице меньше limit (неполная страница).

Оба случая соответствуют поведению AmoCRM REST API (включая ответ 204, который _request возвращает как {}).