| name | amocrm-api |
| description | amoCRM REST API reference. Use when building integrations with amoCRM, writing code that calls amoCRM API endpoints, debugging amoCRM integrations, or answering questions about amoCRM API capabilities, OAuth 2.0, webhooks, entities (leads, contacts, companies, tasks), rate limits. |
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
chmod 600 config/.env
Вариант 2 — настроить самому.
Пользователь выполняет локально:
cp config/.env.example config/.env
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.
Основные сущности
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}"
Полезные ссылки
