Сделки (Leads) — документация amocrm-sdk 0.1.0

# Сделки (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