Как подключить amoCRM к n8n

После этой инструкции сценарий n8n сможет читать сделки amoCRM, создавать сделку с контактом, писать примечания и получать события через вебхуки. Всё работает через API v4.

Что понадобится

• Права администратора в amoCRM. Без них интеграцию не создать.
• n8n на своём сервере с HTTPS. Вебхуки amoCRM отправляет только на публичный адрес. Как поставить n8n, описано в отдельной инструкции.
• Поддомен аккаунта. Если вы входите по адресу https://mycompany.amocrm.ru, поддомен mycompany.

Встроенного узла amoCRM в n8n нет. В npm есть узлы от сообщества, например n8n-nodes-amocrm, но n8n их не проверяет. Мы работаем через узел HTTP Request. Так каждый запрос виден в истории выполнения, а сценарий не зависит от стороннего пакета.

Шаг 1. Создать приватную интеграцию

1. Откройте раздел амоМаркет и нажмите Создать интеграцию.
2. Заполните название и описание. Поле ссылки для перенаправления обязательное: укажите адрес своего сайта с HTTPS. Для долгосрочного токена обмен кодами авторизации не понадобится.
3. В доступах отметьте только то, что нужно сценарию.
4. Сохраните интеграцию.

По документации amoCRM, если аккаунт не технический, при подключении приватной интеграции клиент подписывает заявление об отказе от технической поддержки по ошибкам системы. Отозвать его нельзя. Консультации и вопросы оплаты это не затрагивает. Решите заранее, подходит ли вам это условие.

Шаг 2. Получить долгосрочный токен

С февраля 2024 года amoCRM выдаёт долгосрочные токены для приватных интеграций. Для работы с одним аккаунтом это самый простой способ: токен не нужно обновлять.

1. В окне интеграции откройте вкладку Ключи.
2. Нажмите Сгенерировать токен и выберите дату окончания. Срок от 1 дня до 5 лет.
3. Скопируйте токен сразу. Повторно его не покажут.

Токен получает права пользователя, который предоставил доступ. Обычно это администратор, поэтому храните токен как пароль. Отозвать его можно на вкладке Выданные доступы. Поставьте напоминание за пару недель до окончания срока.

В n8n создайте доступ типа Header Auth:

• Name: Authorization
• Value: Bearer ВАШ_ТОКЕН

Шаг 3. Проверить подключение

Все адреса API строятся по одной схеме: https://ПОДДОМЕН.amocrm.ru/api/v4/МЕТОД. Для проверки запросите данные аккаунта:

curl https://mycompany.amocrm.ru/api/v4/account \
  -H "Authorization: Bearer ВАШ_ТОКЕН"

Ответ с кодом 200 значит, что токен работает.

Шаг 4. Получить сделки

Узел HTTP Request:

• Method: GET
• URL: https://mycompany.amocrm.ru/api/v4/leads
• Authentication: Generic Credential Type → Header Auth → созданный доступ
• Send Query Parameters:
  • limit = 250, это максимум для метода;
  • with = contacts, чтобы получить связанные контакты;
  • filter[updated_at][from] = {{ $now.minus({ days: 1 }).toUnixInteger() }}.

Даты amoCRM принимает и отдаёт в Unix-времени в секундах. Сделки лежат в массиве _embedded.leads. Разложите его на отдельные элементы узлом Split Out.

Чтобы выбрать сделки на конкретном этапе, используйте фильтр по статусам:

filter[statuses][0][pipeline_id]=ID_ВОРОНКИ&filter[statuses][0][status_id]=ID_ЭТАПА

Если сделок больше 250, включите в Options → Pagination:

• Pagination Mode: Update a Parameter in Each Request
• Type: Query, Name: page, Value: {{ $pageCount + 1 }}
• Pagination Complete When: Other
• Complete Expression: {{ !$response.body?._links?.next }}
• Interval Between Requests (ms): 200

Шаг 5. Создать сделку с контактом

Метод POST /api/v4/leads/complex создаёт сделку вместе с контактом за один запрос. В запросе до 50 сделок, у каждой не больше одного контакта и одной компании.

[
  {
    "name": "Заявка с сайта",
    "price": 15000,
    "_embedded": {
      "contacts": [
        {
          "first_name": {{ JSON.stringify($json.name) }},
          "custom_fields_values": [
            {
              "field_code": "PHONE",
              "values": [{ "enum_code": "WORK", "value": {{ JSON.stringify($json.phone) }} }]
            },
            {
              "field_code": "EMAIL",
              "values": [{ "enum_code": "WORK", "value": {{ JSON.stringify($json.email) }} }]
            }
          ]
        }
      ]
    }
  }
]

Без pipeline_id и status_id сделка попадёт на первый этап главной воронки. В ответе придёт массив с полями id сделки, contact_id и merged. Значение merged: true означает, что контроль дублей нашёл существующий контакт и объединил данные.

Шаг 6. Добавить примечание

Примечание к сделке создаётся методом POST /api/v4/leads/notes:

[
  {
    "entity_id": {{ $json.id }},
    "note_type": "common",
    "params": {
      "text": "Итог звонка: клиент просит счёт до пятницы."
    }
  }
]

Так в карточку попадают, например, итоги анализа звонков.

Шаг 7. Принимать вебхуки из amoCRM

1. В n8n добавьте узел Webhook: метод POST, Respond: Immediately. Скопируйте Production URL. Он начнёт работать после публикации сценария.
2. В amoCRM откройте амоМаркет, нажмите WEB HOOKS в правом верхнем углу, вставьте адрес и выберите события, например добавление сделки или смену этапа.

amoCRM отправляет данные в формате x-www-form-urlencoded. n8n не раскладывает такие ключи во вложенные объекты, поэтому поля приходят с квадратными скобками в имени:

{{ $json.body['leads[add][0][id]'] }}
{{ $json.body['leads[status][0][status_id]'] }}

В вебхуке только основные поля. Полную карточку получите запросом GET /api/v4/leads/{id}?with=contacts.

amoCRM ждёт ответ не дольше 2 секунд. Если за 2 часа накопится больше 100 неудачных ответов, хук отключится. Поэтому узел Webhook должен отвечать сразу, а обработка идёт после. Подробнее о приёме вебхуков в статье про вебхуки в n8n.

В документации amoCRM указано, что работа с вебхуками через API доступна на тарифах «Расширенный» и «Профессиональный». Уточните условия своего тарифа.

Ограничения по частоте

• Не больше 7 запросов в секунду на одну интеграцию и до 50 в секунду на весь аккаунт.
• При превышении приходит код 429. При многократных нарушениях amoCRM блокирует API, и на любой запрос приходит 403.
• За один запрос можно создать или изменить до 250 сущностей, для стабильной работы рекомендуют не больше 50.

Если сценарий обрабатывает много элементов, включите в HTTP Request Options → Batching: Items per Batch 5, Batch Interval (ms) 1000.

Частые ошибки

• 401. Токен истёк, отозван или скопирован с пробелом. Проверьте срок на вкладке «Выданные доступы».
• 402. Аккаунт amoCRM не оплачен.
• Пустые значения из вебхука. В выражении написано $json.body.leads. Используйте ключ целиком со скобками, как в примере выше.
• Сценарий реагирует на свои же сделки. Если сценарий создаёт сделки и слушает событие добавления сделки, отфильтруйте свои сделки, например по тегу.
• Хук отключился. Сценарий отвечал дольше 2 секунд или с ошибкой. Включите хук снова в настройках вебхуков.
• Имена и телефоны в Telegram. В уведомления отправляйте номер сделки и ссылку на неё. Почему так, объясняем в статье про 152-ФЗ.