Metadata-Version: 2.4
Name: amocrm-sdk
Version: 0.3.0
Summary: Simple Python SDK for AmoCRM API
Project-URL: Homepage, https://github.com/MikhailMurashov/amocrm-sdk
Project-URL: Repository, https://github.com/MikhailMurashov/amocrm-sdk
Project-URL: Documentation, https://amocrm-sdk.readthedocs.io
Requires-Python: >=3.10
Requires-Dist: requests>=2.32
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-rtd-theme; extra == 'docs'
Requires-Dist: sphinx>=8.0; extra == 'docs'
Description-Content-Type: text/markdown

# amocrm-sdk

[![PyPI](https://img.shields.io/pypi/v/amocrm-sdk)](https://pypi.org/project/amocrm-sdk/)
[![Docs](https://readthedocs.org/projects/amocrm-sdk/badge/?version=latest)](https://amocrm-sdk.readthedocs.io)

Python SDK for the [AmoCRM REST API](https://www.amocrm.ru/developers/content/crm_platform/api-reference).

## Installation

```bash
uv add amocrm-sdk
# or
pip install amocrm-sdk
```

## Quick Start

### OAuth2 setup

```python
from amocrm import AmoCRM, OAuthConfig
from amocrm.auth import DjangoTokenStorage

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

# Первый запуск — обменять код авторизации на токены
client = AmoCRM.from_code(subdomain="your-company", code=auth_code, oauth=oauth)

# Последующие запуски — токены загружаются из storage автоматически
client = AmoCRM(subdomain="your-company", oauth=oauth)
```

### Глобальный менеджер (Django / Flask)

```python
from amocrm.manager import exchange_code, get_client

# OAuth callback view
exchange_code(subdomain="your-company", code=request.GET["code"], oauth=oauth)

# В любом месте приложения
client = get_client(subdomain="your-company", oauth=oauth)
```

### Кастомное хранилище токенов

```python
from amocrm import TokenStorage

class RedisTokenStorage:
    def save(self, access_token: str, refresh_token: str) -> None:
        redis.set("amo:access", access_token)
        redis.set("amo:refresh", refresh_token)

    def load(self) -> tuple[str, str]:
        return redis.get("amo:access"), redis.get("amo:refresh")
```

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

```python
# Сделки — авто-пагинация (обходит все страницы, возвращает 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.id, 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.id, 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)`.

## Models

| Класс | Описание |
|-------|----------|
| `Lead` | Сделка. Поля: `id`, `name`, `price`, `status_id`, `pipeline_id`, `tags`, `custom_fields_values`, `contacts`, `company`, … |
| `Contact` | Контакт. Поля: `id`, `name`, `first_name`, `last_name`, `tags`, `custom_fields_values`, … |
| `Company` | Компания. Поля: `id`, `name`, `tags`, `custom_fields_values`, … |
| `Task` | Задача. Поля: `id`, `text`, `complete_till`, `task_type_id`, `responsible_user_id`, `is_completed`, `entity_id`, `entity_type`, `result`, … |
| `Tag` | Тег. Поля: `id`, `name` |
| `CustomFieldValue` | Значение кастомного поля. Поля: `field_id`, `values` |
| `Pipeline` | Воронка. Поля: `id`, `name`, `statuses` |

Все модели — `@dataclass` с методами `from_dict` / `to_dict`. `to_dict()` исключает `None`-поля, что даёт чистый API payload.

## Features

- OAuth2 с auto-refresh токенов по 401
- Гибкое хранилище токенов — любой класс с `save()` / `load()` (Django ORM, Redis, etc.)
- `DjangoTokenStorage` из коробки
- Глобальный менеджер (`exchange_code` / `get_client`) для Django/Flask
- Typed DTO models — никаких сырых словарей
- Leads (сделки): list, get, create, update, update_one, create_complex; `get()` подгружает контакты по умолчанию; лимит 50 сделок за запрос
- Contacts (контакты): list, get, create, update, update_one
- Companies (компании): list, get, create, update, update_one
- Pipelines (воронки): list, get, create, update, delete + statuses CRUD
- Tasks (задачи): list, get, create, update, update_one
- Custom fields support
- Авто-пагинация — `list()` без `page` автоматически обходит все страницы и возвращает `Iterator[T]`

## Links

- [PyPI](https://pypi.org/project/amocrm-sdk/)
- [Documentation](https://amocrm-sdk.readthedocs.io)
- [AmoCRM API Reference](https://www.amocrm.ru/developers/content/crm_platform/api-reference)
- [OAuth2 guide](https://www.amocrm.ru/developers/content/oauth/oauth)


# TODO

- https://www.amocrm.ru/developers/content/api/recommendations
- https://www.amocrm.ru/developers/content/crm_platform/account-info
- ~~https://www.amocrm.ru/developers/content/crm_platform/leads-api~~
- https://www.amocrm.ru/developers/content/crm_platform/unsorted-api
- ~~https://www.amocrm.ru/developers/content/crm_platform/leads_pipelines~~
- https://www.amocrm.ru/developers/content/crm_platform/filters-api
- ~~https://www.amocrm.ru/developers/content/crm_platform/contacts-api~~
- ~~https://www.amocrm.ru/developers/content/crm_platform/companies-api~~
- https://www.amocrm.ru/developers/content/crm_platform/catalogs-api
- https://www.amocrm.ru/developers/content/crm_platform/entity-links-api
- ~~https://www.amocrm.ru/developers/content/crm_platform/tasks-api~~
- https://www.amocrm.ru/developers/content/crm_platform/custom-fields
- https://www.amocrm.ru/developers/content/crm_platform/tags-api
- https://www.amocrm.ru/developers/content/crm_platform/events-and-notes
- https://www.amocrm.ru/developers/content/crm_platform/customers-api
- https://www.amocrm.ru/developers/content/crm_platform/customers-statuses-api
- https://www.amocrm.ru/developers/content/crm_platform/users-api
- https://www.amocrm.ru/developers/content/crm_platform/products-api
- https://www.amocrm.ru/developers/content/crm_platform/webhooks-api
- https://www.amocrm.ru/developers/content/crm_platform/widgets-api
- https://www.amocrm.ru/developers/content/crm_platform/calls-api
- https://www.amocrm.ru/developers/content/crm_platform/talks-api
- https://www.amocrm.ru/developers/content/crm_platform/subscriptions-api
- https://www.amocrm.ru/developers/content/crm_platform/sources-api
- https://www.amocrm.ru/developers/content/api/salesbot-api
- https://www.amocrm.ru/developers/content/crm_platform/short_links
- https://www.amocrm.ru/developers/content/crm_platform/chat-templates-api
- https://www.amocrm.ru/developers/content/crm_platform/duplication-control
