Перейти к основному содержимому

Приложения Zapier, Make и n8n

По одному приложению на платформу поверх публичного API и подписок REST-хуков (/api/v1/hooks/subscriptions, вебхуки). Код и тесты: integrations/zapier (определение для Zapier Platform CLI, обычный JavaScript, без зависимостей времени выполнения), integrations/make (декларативное определение приложения app.json и средство запуска тестов), integrations/n8n (пакет community-узла, TypeScript). make automation-apps-test запускает три набора (Node >= 22.18 или Docker node:lts). Тесты работают против имитации API АТС (test/fake-pbx.js: аутентификация Bearer, подписки, набор номера одним нажатием, SMS, контакты, заметки к звонкам); ни реальная платформа, ни реальная АТС не вызываются.

Подключение​

Клиент вводит адрес АТС и API-ключ (Консоль > Админ > API-ключи), который отправляется как Authorization: Bearer <key>. Дайте ключу integrations:write (подписки) и то, что нужно триггерам и действиям: право на событие каждого триггера (см. «Кто что получает» в вебхуках; подписка на событие, которое ключ получать не может, отклоняется с 400), self:read для набора номера, отправки SMS и контактов. Изоляция тенантов обеспечивается API: ключ видит и меняет только свою компанию.

Триггеры (мгновенные, REST-хук)​

ТриггерСобытиеПримечания
Звонок начат / завершёнcall.started, call.ended
Новое голосовое сообщениеvoicemail.message_left
Получено SMSsms.received
Новое сообщение в чатеchat.message_created
ИИ-сводка звонка готоваcall.summary_readydetail.summary содержит текст (поле только для вебхука)
ИИ-сводка голосовой почты готоваvoicemail.summary_ready

Включение Zap/сценария/воркфлоу вызывает POST /api/v1/hooks/subscriptions ({target_url, event, source: "zapier"|"make"|"n8n"}); выключение вызывает DELETE /api/v1/hooks/subscriptions/{id} с id, который сохранила платформа. Ответ на подписку один раз содержит подписывающий secret. Каждая доставка — конверт события {id, type, occurred_at, data}: Zapier разворачивает data рядом с id/type/occurred_at (id убирает дубликаты); Make отдаёт body.data; n8n выдаёт развёрнутый объект и проверяет подпись Standard Webhooks (webhook-id, -timestamp, -signature, окно 5 минут, безопасно при ротации) сохранённым секретом. Zapier и Make не могут проверять подписи; их целевые URL — неугадываемые https-адреса, и исходящая защита АТС действует как для любого вебхука.

Действия​

ДействиеAPIВвод
Начать звонокPOST /api/v1/calls/click-to-callномер назначения, необязательный id устройства. Звонит на устройство владельца ключа, затем набирает от его имени (действуют план набора, права и ограничения защиты от мошенничества; экстренные номера отклоняются).
Отправить SMSPOST /api/v1/sms/messagesот (номер SMS компании), кому, текст. Несёт Idempotency-Key запуска, поэтому повтор платформы отправляет одно сообщение.
Создать контактPOST /api/v1/me/contactsтелефон, имена, компания, e-mail, заметки (личные контакты владельца ключа).
Добавить заметку к звонкуPUT /api/v1/cdr/{call_id}/noteid звонка, текст, private или team.

Пустые необязательные поля в запрос не попадают. Проблема АТС (application/problem+json) показывается с detail и code, например MPBX-CONTACT-NUMBER-TAKEN.

Примеры (ИИ-сводка звонка в командную заметку)​

Каждый — одна и та же двухшаговая автоматизация, а тест проверяет, что в ней названы настоящие триггеры, модули и поля:

  • Zapier: integrations/zapier/samples/zapier-call-summary-to-note.zap.json
  • Make: integrations/make/samples/make-call-summary-to-note.scenario.json
  • n8n: integrations/n8n/samples/n8n-call-summary-to-note.workflow.json

Контрольные списки проверки (что спрашивает каждая платформа и где это выполнено)​

Публикация и проверка — работа владельца.

Zapier (проверка публичной интеграции). Аутентификация с проверкой подключения: authentication.test вызывает GET /me. Каждый триггер — REST-хук с performSubscribe, performUnsubscribe, perform и примером performList: src/triggers.js, проверено для всех 7. У каждого действия есть поля с подписями и sample: src/actions.js. Сообщения об ошибках понятны человеку: afterResponse в src/client.js. Нет дублей действий при повторе: Idempotency-Key для SMS. Триггеры убирают дубли по id. Не более одного приложения на сценарий использования, без тестовых данных в приложении, без жёстко заданного базового URL (его вводит клиент). Остаётся сделать на стороне Zapier: zapier validate, zapier push, форма проверки, публичный логотип и контакт поддержки.

Make (пользовательское приложение / проверка Make Apps). Подключение с тестовым запросом, один вебхук на событие с attach и detach, модули мгновенных триггеров, модули действий с типизированными параметрами, понятный шаблон ошибки, тела с omitEmpty: integrations/make/app.json, выполняется test/runner.js. Остаётся сделать в Make: импортировать определение в редактор пользовательских приложений (компоненты создаются из тех же блоков), добавить описания модулей и значки и отправить на проверку.

n8n (верификация community-узла). Ключевое слово пакета n8n-community-node-package, блок n8n в package.json, учётные данные с тестовым запросом, один узел-триггер с методами вебхука checkExists/create/delete и проверкой подписи, один узел-действие с четырьмя операциями, поддержка continueOnFail. Формы API узла объявлены локально (lib/types.ts), потому что n8n-workflow не под лицензией, допустимой для наших продуктов; владелец решает, собирать ли против него. Остаётся: npm run build, npm publish --provenance, запрос на верификацию, значок monopbx.svg.

Ограничения​

В этих приложениях нет OAuth (один API-ключ на подключение); OAuth 2.0 с экранами согласия Zapier/Make/n8n планируется. Действия выполняются от имени владельца API-ключа. Резервного опроса нет: платформа, которая не может принимать вебхуки, не может использовать триггеры.