esporykhin amoCRM API
REST API для amoCRM — управление сделками, контактами, компаниями, задачами, воронками, webhooks и т.п. Все запросы идут на поддомен конкретного аккаунта.
Workflow
- Проверь наличие
config/.env. Если его нет — запусти onboarding (см. Authentication). - Для любого вызова используй
./scripts/amocrm-request.sh METHOD PATH [--data ...] [--query ...]— он сам подгрузит токен. - Если не знаешь эндпоинт — смотри reference по сущности в
references/. - Для write-операций сначала тест на 1 объекте, затем batch.
Base URL
https://{subdomain}.amocrm.ru/api/v4/{endpoint}
Для amoCRM.com аналогично: https://{subdomain}.amocrm.com/api/v4/. Это отдельная платформа — токены между .ru и .com не совместимы.
Authentication — долгосрочный токен
Используем долгосрочный токен приватной интеграции. Не требует рефреша, работает как обычный Bearer. Хранится в config/.env внутри скилла (файл в .gitignore).
Все запросы: Authorization: Bearer ${AMOCRM_ACCESS_TOKEN}.
Onboarding: если config/.env не настроен
Агент должен спросить у пользователя subdomain + токен и предложить ровно два варианта:
Вариант 1 — передать токен в чат (агент настроит сам).
Пользователь присылает subdomain и долгосрочный токен. Агент создаёт config/.env:
cp config/.env.example config/.env
# потом перезаписывает значения AMOCRM_SUBDOMAIN и AMOCRM_ACCESS_TOKEN
chmod 600 config/.env
Вариант 2 — настроить самому. Пользователь выполняет локально:
cp config/.env.example config/.env
# отредактировать AMOCRM_SUBDOMAIN и AMOCRM_ACCESS_TOKEN вручную
chmod 600 config/.env
Где взять долгосрочный токен
- amoCRM → Настройки → Интеграции → Создать интеграцию → Внутренняя интеграция
- Заполнить название и scopes (сделки, контакты, и т.п.)
- Созданная интеграция → вкладка "Ключи и доступы" → "Сгенерировать долгосрочный токен"
- Выбрать срок жизни (до нескольких лет) и скопировать токен — показывается один раз
Также нужны:
- subdomain — для
mycompany.amocrm.ruэтоmycompany - домен —
amocrm.ruилиamocrm.com(переменнаяAMOCRM_DOMAIN, по умолчаниюamocrm.ru)
Подробнее: config/README.md.
Приоритет источников
- Переменные окружения (
AMOCRM_SUBDOMAIN=... ./scripts/amocrm-request.sh ...) — для one-off вызовов config/.env— стандартное хранилище внутри скилла
Когда нужен OAuth 2.0
Если делаешь публичную интеграцию из каталога amoCRM (для сторонних аккаунтов) — тогда нужен полный OAuth flow (authorization_code → access + refresh, access живёт 24 часа). Для приватной интеграции в свой аккаунт — достаточно долгосрочного токена.
Request / Response format
- Body:
application/json - Успех:
Content-Type: application/hal+json, HTTP 200/204 - Ошибка:
Content-Type: application/problem+json, HTTP 400/401/402/403/404
Общие query параметры (GET-списки)
| Параметр | Описание |
|---|---|
page |
Страница (от 1) |
limit |
До 250 |
query |
Поиск по значениям полей |
with |
Включить связанные данные (зависит от сущности) |
filter[...] |
Фильтрация (filter[id][]=1, filter[created_at][from]=...) |
order[...] |
Сортировка (order[updated_at]=desc) |
HAL-формат
Связанные объекты возвращаются в _embedded, пагинация — в _links.next/prev.
Основные сущности
| Раздел | Reference |
|---|---|
| Сделки (Leads) | references/leads.md |
| Контакты (Contacts) | references/contacts.md |
| Компании (Companies) | references/companies.md |
| Задачи (Tasks) | references/tasks.md |
| Webhooks | references/webhooks.md |
| Общее (аккаунт, кастом-поля, воронки, теги, события, неразобранное) | references/common.md |
Limits и best practices
limitна списках — максимум 250.- Пакетное создание/обновление — до 50 объектов (в
leads/complexтакже 50). - До 40 custom fields на сущность в одном запросе.
- Webhooks: 100 подписок на аккаунт.
- Rate limits в публичной доке не фиксированы жёстко; на практике держись ≤ 7 rps на интеграцию, при 429 — экспоненциальный backoff.
- Для массовых операций используй batch-эндпоинты (
POST/PATCH /api/v4/leadsс массивом), а не цикл по одиночным запросам. - Сразу сохраняй новую пару токенов после refresh — старый refresh умирает моментально.
Быстрый пример
Через обёртку (рекомендуется):
./scripts/amocrm-request.sh GET /api/v4/leads --query limit=50 --query with=contacts
./scripts/amocrm-request.sh POST /api/v4/leads \
--data '[{"name":"Новая сделка","price":10000,"pipeline_id":123,"status_id":456}]'
Через curl (если нужен прямой вызов):
source config/.env
curl -s "https://${AMOCRM_SUBDOMAIN}.${AMOCRM_DOMAIN:-amocrm.ru}/api/v4/leads?limit=50" \
-H "Authorization: Bearer ${AMOCRM_ACCESS_TOKEN}"
Полезные ссылки
- Обзор: https://www.amocrm.ru/developers/content/crm_platform/api-reference
- OAuth step-by-step: https://www.amocrm.ru/developers/content/oauth/step-by-step
- Фильтрация и сортировка: https://www.amocrm.ru/developers/content/crm_platform/filters-api