amocrm-sdk — документация amocrm-sdk 0.1.0

# amocrm-sdk

Python SDK для работы с REST API AmoCRM. Предоставляет удобный интерфейс для авторизации, сделок, контактов, компаний, задач и воронок.

## Установка

    pip install amocrm-sdk

## Типичный порядок работы

    from amocrm import OAuthConfig, Lead, Contact, Company
    from amocrm.auth import DjangoTokenStorage
    from amocrm.manager import exchange_code, get_client

    oauth = OAuthConfig(
        client_id="...",
        client_secret="...",
        redirect_uri="https://yourapp.com/oauth/callback",
        storage=DjangoTokenStorage(AmoCRMToken.objects.get(id=1)),
    )

    # 1. Обмен кода авторизации на токены (OAuth callback)
    exchange_code(subdomain="your-company", code=auth_code, oauth=oauth)
    client = get_client(subdomain="your-company", oauth=oauth)

    # 2. Создание сделки с контактом и компанией (create_complex)
    lead = Lead(
        name="Новая сделка",
        price=100000,
        contacts=[Contact(name="Иван Иванов")],
        company=Company(name="ООО Ромашка"),
    )
    created = client.leads.create_complex([lead])
    lead_id = created[0].id

    # 3. Получение лида с контактом и компанией (contacts подгружаются по умолчанию)
    lead = client.leads.get(lead_id)
    contact = lead.contacts[0]   # Contact
    company = lead.company        # Company

    # 4. Обновление контакта
    contact.name = "Иван Петров"
    client.contacts.update_one(contact)

    # 5. Обновление компании
    company.name = "ООО Лютик"
    client.companies.update_one(company)

## Работа с ресурсами

    # Сделки — авто-пагинация (обходит все страницы, возвращает Iterator)
    for lead in client.leads.list():
        print(lead.id, lead.name, lead.price)

    # Одна страница — передайте page явно
    leads = client.leads.list(page=1, limit=50)

    # get() автоматически подгружает контакты (with=contacts по умолчанию)
    lead = client.leads.get(42)
    print(lead.contacts)       # list[Contact] | None
    lead.price = 9000
    client.leads.update_one(lead)

    new_lead = Lead(name="Big Deal", price=50000, tags=[Tag(name="vip")])
    created = client.leads.create([new_lead])
    print(created[0].id)

    # Создать сделку вместе с контактом и компанией (max 1 контакт, max 50 сделок)
    from amocrm import Contact, Company
    lead = Lead(
        name="Complex Deal",
        contacts=[Contact(name="Иван Иванов")],
        company=Company(name="ООО Ромашка"),
    )
    client.leads.create_complex([lead])

    # Контакты — авто-пагинация
    for contact in client.contacts.list(query="Иван"):
        print(contact.name)

    client.contacts.create([Contact(name="Иван Иванов", first_name="Иван")])

    # Компании — авто-пагинация
    for company in client.companies.list():
        print(company.name)

    client.companies.create([Company(name="Рога и копыта")])

    # Задачи — авто-пагинация
    from amocrm import Task

    for task in client.tasks.list():
        print(task.id, task.text, task.complete_till)

    task = client.tasks.get(10)
    task.text = "Updated text"
    client.tasks.update_one(task)

    new_task = Task(text="Call client", task_type_id=1, complete_till=1700000000, entity_id=lead.id, entity_type="leads")
    created = client.tasks.create([new_task])
    print(created[0].id)

## Пагинация

Методы `list()` у всех ресурсов поддерживают два режима:

Вызов | Поведение | Возвращает
--- | --- | ---
`client.leads.list()` | Авто-пагинация — обходит все страницы | `Iterator[Lead]`
`client.leads.list(page=2)` | Одна конкретная страница | `list[Lead]`

По умолчанию авто-пагинация запрашивает по 50 элементов на страницу. Для кастомного размера: `client.leads.list(limit=250)`.

Документация

- Сделки (Leads)
  - Получение сделок
  - Создание и обновление
  - Связанные сущности: контакты и компании
  - Обработка ошибок
- Теги (Tags)
  - Чтение тегов
  - Создание сущности с тегами
  - Обновление тегов
  - Фильтрация по тегам
  - Сериализация
  - Модель Tag
- Пагинация
  - Режимы работы `list()`
  - Авто-пагинация (рекомендуется)
  - Одна страница
  - Сигнал конца данных
- Управление токенами
  - Реактивное обновление по 401
  - Проактивное обновление по истечению срока
  - Хранилище токенов
- Кодогенератор (Codegen)
  - Обзор
  - Быстрый старт
  - Пример сгенерированного файла
  - Подключение к клиенту через `configure_dto`
  - Транслитерация имён
  - Запись значений через сеттеры
  - Конфигурация
  - Использование без записи в файл
  - API-справочник
- API Reference
  - Клиент
  - Авторизация
  - Менеджер (синглтон)
  - Исключения
  - Ресурсы
  - Модели