# Amocrm Api

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-esporykhin-claude-code-skills-amocrm-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [esporykhin](https://agentstack.voostack.com/s/esporykhin)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [esporykhin](https://github.com/esporykhin)
- **Source:** https://github.com/esporykhin/claude-code-skills/tree/main/amocrm-api

## Install

```sh
agentstack add skill-esporykhin-claude-code-skills-amocrm-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# amoCRM API

REST API для amoCRM — управление сделками, контактами, компаниями, задачами, воронками, webhooks и т.п. Все запросы идут на поддомен конкретного аккаунта.

## Workflow

1. Проверь наличие `config/.env`. Если его нет — запусти onboarding (см. Authentication).
2. Для любого вызова используй `./scripts/amocrm-request.sh METHOD PATH [--data ...] [--query ...]` — он сам подгрузит токен.
3. Если не знаешь эндпоинт — смотри reference по сущности в `references/`.
4. Для 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`:

```bash
cp config/.env.example config/.env
# потом перезаписывает значения AMOCRM_SUBDOMAIN и AMOCRM_ACCESS_TOKEN
chmod 600 config/.env
```

**Вариант 2 — настроить самому.**
Пользователь выполняет локально:
```bash
cp config/.env.example config/.env
# отредактировать AMOCRM_SUBDOMAIN и AMOCRM_ACCESS_TOKEN вручную
chmod 600 config/.env
```

### Где взять долгосрочный токен

1. amoCRM → **Настройки → Интеграции → Создать интеграцию → Внутренняя интеграция**
2. Заполнить название и scopes (сделки, контакты, и т.п.)
3. Созданная интеграция → вкладка **"Ключи и доступы"** → **"Сгенерировать долгосрочный токен"**
4. Выбрать срок жизни (до нескольких лет) и скопировать токен — показывается один раз

Также нужны:
- **subdomain** — для `mycompany.amocrm.ru` это `mycompany`
- **домен** — `amocrm.ru` или `amocrm.com` (переменная `AMOCRM_DOMAIN`, по умолчанию `amocrm.ru`)

Подробнее: [config/README.md](config/README.md).

### Приоритет источников

1. Переменные окружения (`AMOCRM_SUBDOMAIN=... ./scripts/amocrm-request.sh ...`) — для one-off вызовов
2. `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](references/leads.md) |
| Контакты (Contacts) | [references/contacts.md](references/contacts.md) |
| Компании (Companies) | [references/companies.md](references/companies.md) |
| Задачи (Tasks) | [references/tasks.md](references/tasks.md) |
| Webhooks | [references/webhooks.md](references/webhooks.md) |
| Общее (аккаунт, кастом-поля, воронки, теги, события, неразобранное) | [references/common.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 умирает моментально.

## Быстрый пример

Через обёртку (рекомендуется):
```bash
./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 (если нужен прямой вызов):
```bash
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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [esporykhin](https://github.com/esporykhin)
- **Source:** [esporykhin/claude-code-skills](https://github.com/esporykhin/claude-code-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-esporykhin-claude-code-skills-amocrm-api
- Seller: https://agentstack.voostack.com/s/esporykhin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.