# Как ходить в amoCRM из своего сервиса

*Для разработчиков. Подробности устройства — в README репозитория `Buharestskie/amo_queue`.*

## Коротко

Если ваш сервис **читает** данные amoCRM — читайте их из реплики, см. «Реплика amoCRM (amo\_db)». Если сервис **пишет** в amoCRM или ему нужно то, чего в реплике нет, — ходите через шлюз `https://amo-queue.donula26.ru`, а не напрямую в amoCRM.

## Зачем шлюз

amoCRM пускает не больше 7 запросов в секунду от одной интеграции и не больше 50 от всего аккаунта. Превышение — ошибка `429`, повторные превышения — блокировка всего аккаунта: встают все виджеты, дашборды и телефония разом.

Каждый сервис по отдельности может аккуратно держать свои 7 запросов, но про соседей он не знает — и вместе они пробивают общие 50. Шлюз ставит запросы всех сервисов в одну очередь и следит за обоими лимитами сразу.

## Как подключиться

Поменять в конфиге сервиса один адрес — больше ничего:

<table id="bkmrk-%D0%91%D1%8B%D0%BB%D0%BE%D0%A1%D1%82%D0%B0%D0%BB%D0%BE-https%3A%2F%2Fdo"><thead><tr><th>Было</th><th>Стало</th></tr></thead><tbody><tr><td>`https://donula.amocrm.ru/api/v4/leads?with=contacts`</td><td>`https://amo-queue.donula26.ru/api/v4/leads?with=contacts`</td></tr></tbody></table>

Пути, методы, тело запроса и заголовок `Authorization: Bearer <токен>` остаются прежними. Регистрировать сервис в шлюзе не нужно: он отличает интеграции по токену.

Обязательно передавайте имя сервиса в заголовке `X-Integration-Name`:

```
curl https://amo-queue.donula26.ru/api/v4/account \
  -H "Authorization: Bearer $AMO_TOKEN" \
  -H "X-Integration-Name: my-service"
```

Без имени в статистике и алертах виден только кусок хэша токена, и понять, чей это сервис, уже нельзя. Имя — латиница, цифры, точка, дефис, подчёркивание, до 40 символов.

## Что может ответить шлюз

Почти всегда вы получаете ответ самой amoCRM без изменений. Свои ответы шлюз отдаёт в четырёх случаях:

<table id="bkmrk-%D0%9A%D0%BE%D0%B4%D0%A7%D1%82%D0%BE-%D0%B7%D0%BD%D0%B0%D1%87%D0%B8%D1%82%D0%A7%D1%82%D0%BE-%D0%B4%D0%B5%D0%BB"><thead><tr><th>Код</th><th>Что значит</th><th>Что делать</th></tr></thead><tbody><tr><td>`401`</td><td>Нет заголовка `Authorization`</td><td>Передать токен</td></tr><tr><td>`429` с телом `gateway queue is full`</td><td>Ваш сервис прислал больше, чем его очередь разгребает за 10 секунд</td><td>Повторить через `Retry-After` и растянуть отправку во времени. Это не amoCRM и не сбой шлюза — это ваш сервис шлёт пачкой</td></tr><tr><td>`502`</td><td>amoCRM недоступна</td><td>Повторить позже</td></tr><tr><td>`504`</td><td>amoCRM не ответила за 30 секунд</td><td>Повторить позже; если повторяется — упростить запрос</td></tr></tbody></table>

## Сколько можно слать

На один токен — 6 запросов в секунду, на все сервисы вместе через шлюз — 30. Оставшиеся до 50 — запас для тех, кто в amoCRM ходит напрямую: реплика, телефония, сторонние виджеты.

Запросы сверх 6 в секунду не отбрасываются сразу, а ждут своей очереди до 10 секунд. Поэтому короткие всплески проходят незаметно, а массовые выгрузки — нет: их надо отправлять равномерно или разбивать на части с паузами.

Если фоновая выгрузка мешает быстрым запросам того же сервиса (кнопки в виджете начинают тормозить), заведите для фоновой задачи отдельную интеграцию в amoCRM со своим токеном — у неё будет своя очередь.

## Лендинги ходят не сюда

Бэкенды квиз-лендингов (mfctest, bfl\_fspp, do-nula-refinancing-2 и подобные) отправляют заявки не через шлюз, а через отдельный сервис `amocrm-service` — `https://donula26.ru/service/amocrm/`. Причины:

- **Токен amoCRM не лежит на лендинге.** Лендинг присылает готовую сделку, контакт и примечание, а токен знает только amocrm-service.
- **Защита от спама с форм.** Не больше 9 заявок с одного IP посетителя в час и 10 сущностей на один телефон в сутки. Поэтому в каждом запросе лендинг передаёт `ip` посетителя и его `phone`.
- **Заявка не теряется, если amoCRM тормозит.** `POST /leads/async` ставит цепочку «контакт → сделка → примечание» в очередь и сразу отвечает посетителю; дальше её доводит воркер.

Пускают туда только известные адреса. Новый лендинг — это новая строка в списке доступа сервиса: попросите администратора добавить его до запуска, иначе на каждую заявку будет ответ `403 Caller IP is not permitted`. Всё остальное — ручки, коды ответов, что делать при сбое — в README репозитория `Buharestskie/amocrm-service`.

## Как посмотреть, что с вашим сервисом

- `https://amo-queue.donula26.ru/stats` — сейчас: темп, очередь и счётчики ответов по каждому сервису. Главное число — `queue_seconds`: сколько секунд ждёт запрос, пришедший прямо сейчас. Около нуля — всё хорошо.
- `https://amo-queue.donula26.ru/stats/history?hours=24` — то же по часам, до 7 суток назад.

Если у вашего сервиса растёт `queue_full` в счётчиках — он шлёт пачками, и часть запросов до amoCRM не доходит.