Сделки (Leads)

Ресурс client.leads предоставляет полный набор методов для работы со сделками AmoCRM.

Получение сделок

Список сделок

Авто-пагинация (рекомендуется): без page метод возвращает Iterator[Lead] и автоматически обходит все страницы, запрашивая по 50 элементов:

for lead in client.leads.list():
    print(lead.id, lead.name, lead.price)

# Или собрать в список сразу
all_leads = list(client.leads.list())

Одна страница: передайте page явно — метод вернёт list[Lead]:

leads = client.leads.list(page=1, limit=50)

Доступные параметры:

page — номер страницы (начиная с 1); если не передан — авто-пагинация
limit — количество сделок на странице (максимум 250; по умолчанию 50 при авто-пагинации)
query — строка полнотекстового поиска
filter — словарь фильтров: {"status_id": 123} → filter[status_id]=123
order — словарь сортировки: {"created_at": "desc"}
with_ — дополнительные связанные данные (см. ниже)

См. также

Пагинация — подробнее про авто-пагинацию и оба режима работы list().

Одна сделка по ID

lead = client.leads.get(42)

По умолчанию get() автоматически добавляет with=contacts, поэтому поле lead.contacts будет заполнено без дополнительных параметров.

Чтобы отключить подгрузку контактов, передайте пустой список:

lead = client.leads.get(42, with_=[])

Чтобы запросить дополнительные данные, передайте нужные ключи явно:

lead = client.leads.get(42, with_=["contacts", "loss_reason"])

Создание и обновление

from amocrm import Lead

# Создать одну или несколько сделок (не более 50 за запрос)
new_leads = client.leads.create([
    Lead(name="Новая сделка", price=5000, status_id=1234),
])

# Обновить (не более 50 за запрос, каждая сделка должна содержать id)
client.leads.update([Lead(id=10, price=9000)])

# Обновить одну сделку по ID
client.leads.update_one(Lead(id=10, price=9000))

Предупреждение

За один запрос можно передать не более 50 сделок. При превышении лимита выбрасывается AmoCRMError.

Связанные сущности: контакты и компании

Загрузка при чтении

get() подгружает контакты автоматически (with=contacts по умолчанию). Для компаний добавьте "companies" явно:

lead = client.leads.get(42, with_=["contacts", "companies"])

if lead.contacts:
    for contact in lead.contacts:
        print(contact.id, contact.name)

if lead.company:
    print(lead.company.id, lead.company.name)

Поля модели Lead:

contacts: list[Contact] | None — список связанных контактов (API может вернуть несколько)
company: Company | None — первая связанная компания (берётся _embedded.companies[0])

Создание сделок со связанными сущностями (complex)

Эндпоинт POST /api/v4/leads/complex позволяет за один запрос создать сделку вместе с контактом и компанией:

from amocrm import Lead, Contact, Company

lead = Lead(
    name="Комплексная сделка",
    price=15000,
    contacts=[Contact(name="Иван Иванов", first_name="Иван")],
    company=Company(name="ООО Ромашка"),
)

result = client.leads.create_complex([lead])

Ограничения create_complex:

не более 50 сделок за запрос
не более 1 контакта на сделку

При нарушении любого ограничения выбрасывается AmoCRMError до отправки запроса.

Сериализация в `to_dict`

При передаче в API контакты и компания попадают в ключ _embedded:

lead = Lead(
    name="Сделка",
    contacts=[Contact(id=5)],
    company=Company(id=10),
)
lead.to_dict()
# {
#     "name": "Сделка",
#     "_embedded": {
#         "contacts": [{"id": 5}],
#         "companies": [{"id": 10}],
#     }
# }

Примечание

Теги (tags) остаются на верхнем уровне словаря — это соглашение AmoCRM API для операций записи. Связанные сущности (контакты, компании) при записи передаются через _embedded.

Обработка ошибок

from amocrm.exceptions import AmoCRMError, AmoCRMAPIError

try:
    client.leads.create([Lead(name=f"Deal {i}") for i in range(51)])
except AmoCRMError as e:
    print(e)  # create allows at most 50 items per request

try:
    lead = Lead(contacts=[Contact(id=1), Contact(id=2)])
    client.leads.create_complex([lead])
except AmoCRMError as e:
    print(e)  # create_complex allows at most 1 contact per lead