LeadConnector

Три способа связать claritos с LeadConnector — и приложение Marketplace, которое приносит действия и триггеры прямо в конструктор workflow LeadConnector.

Три пути

Путь A: действие workflow LeadConnector «Webhook» вызывает HTTP API (Authorization: Bearer capi_…), а вебхуки claritos запускают workflow LeadConnector через триггер «Inbound Webhook». Путь B: MCP claritos как внешний MCP-сервер в ИИ-агентах LeadConnector. Путь C: приложение Marketplace — действия и триггеры с полями формы вместо JSON. Это руководство описывает путь C; для A и B достаточно руководств «Вебхуки» и «MCP».

Установка

Из настроек организации (вкладка «Интеграции» → «Подключить LeadConnector»): LeadConnector запрашивает локацию, claritos сохраняет установку (токены зашифрованы) и связывает её с организацией, в которой нажата кнопка. Либо установите из LeadConnector Marketplace — тогда External Authentication (следующий раздел) свяжет локацию с организацией.

External Authentication (API-ключ)

При подключении приложения в LeadConnector пользователь вводит API-ключ claritos. LeadConnector проверяет его по verify-URL; claritos отвечает организацией и запоминает связь локация ↔ организация. Далее LeadConnector передаёт ключ заголовком Authorization при каждом действии — scopes, лимиты, протокол вызовов и гейт клиентских данных действуют как при любом вызове API.

http

POST https://www.claritos.io/api/integrations/leadconnector/external-auth
Content-Type: application/json

{ "apiKey": "capi_…", "locationId": "ve9EPM428h8vShlRW1KT" }

200 { "organizationId": "org_…", "organizationName": "Muster GmbH", "locationId": "ve9EPM428h8vShlRW1KT" }

Действия (custom workflow actions)

Каждое действие — отображение полей на ровно одну конечную точку API с возвратом её ответа (поля доступны в LeadConnector через response mapping). Доступны: contact-create, task-create, sms-send (SMS через Twilio), quote-create (черновик предложения), invoice-create (черновик счёта), form-response (ответ формы → лид). Ошибки приходят как Problem Details (RFC 9457) с HTTP-статусом конечной точки; LeadConnector показывает их в журнале выполнения. Новое: invoice-issue (провести счёт; ответ дополняется `documents` со статусом и адресом PDF, готовностью и адресом XML ZUGFeRD, иначе `pending: xml-not-ready`). Нужно `invoices:write`. Также set-custom-field: задаёт собственное поле контакта (ключ поля и значение, пустое значение удаляет его). Контакт действие находит по идентификатору контакта claritos или по e-mail; новый не создаёт. Если e-mail есть у нескольких контактов, ответ 409 с причиной contact-ambiguous, если нет ни одного, 404 с contact-not-found. Ключу нужно право contacts:write.

http

POST https://www.claritos.io/api/integrations/leadconnector/actions/contact-create
Authorization: Bearer capi_…
Content-Type: application/json

{ "data": { "firstName": "{{contact.first_name}}", "lastName": "{{contact.last_name}}", "email": "{{contact.email}}" } }

201 { "id": "ct_…", "type": "PERSON", "displayName": "Anna Muster", … }

Триггеры (custom workflow triggers)

Когда пользователь добавляет триггер claritos в конструкторе workflow, LeadConnector вызывает subscribe-URL с целевым URL; claritos создаёт для него внутренний webhook-адрес (с backoff, журналом доставки и оповещениями, как у любого адреса) и доставляет события в стандартной нагрузке. Доступны: lead_created, contact_created, invoice_paid, invoice_issued, quote_accepted, esign_completed, form_submitted, task_done. Удаление триггера удаляет адрес; то же при отключении локации или удалении приложения. Также платежи: checkout_pending (платёж начат; при SEPA денег ещё нет), checkout_completed (платёж получен, здесь открывать доступ) и checkout_failed (не прошёл, возвращён или пропущен взнос, здесь закрывать). Нагрузка `checkout` содержит сумму в центах, валюту, e-mail и имя клиента (customerEmail, customerName), идентификатор и название ссылки (checkoutLinkId, checkoutLinkName), для счетов их идентификатор и номер, заказ (orderId, orderNumber), а для checkout_failed причину failureReason (direct_debit_failed, chargeback, no_mandate, payment_failed). Счёт, предложение и задача содержат contactEmail, чтобы workflow мог найти контакт через «Find Contact». Если приложение установлено через OAuth, каждая доставка дополнительно несёт токен доступа установки (Authorization: Bearer, заголовок Version); подпись стандартной нагрузки сохраняется.

json

// LeadConnector → Subscribe-URL (beim Anlegen des Triggers im Workflow)
{ "triggerData": { "id": "trg_…", "key": "invoice_paid", "targetUrl": "https://services.leadconnectorhq.com/hooks/…" },
  "meta": { "locationId": "ve9EPM428h8vShlRW1KT" }, "extras": { "type": "create" } }

// claritos → targetUrl (Standard-Webhook-Nutzlast)
{ "id": "evt_…", "type": "invoices.invoice.paid", "createdAt": "…", "data": { "id": "inv_…", "number": "RE-2026-0042", "totalCents": 119000, … } }

Путь A без приложения

Без приложения Marketplace достаточно HTTP API: в LeadConnector действие workflow «Webhook» (метод/URL/заголовки/тело как в справочнике) — и в claritos webhook-адрес на URL триггера LeadConnector «Inbound Webhook» (руководство «Вебхуки», раздел «Платформы»). Плюс: все 140+ конечных точек и все события; минус: JSON вместо полей формы.

Путь B: MCP в ИИ-агентах LeadConnector

Разговорный ИИ и голосовые агенты LeadConnector могут подключать внешние MCP-серверы. Укажите URL https://www.claritos.io/api/mcp/v1 с заголовком Authorization (API-ключ) — агент получит ровно те инструменты, которые разрешает ключ (руководство «MCP»).

Пункт меню в LeadConnector (SSO)

claritos может отображаться как пункт меню в LeadConnector (custom menu link на {BASE}/embed/leadconnector, «Open in iframe»). Страница запрашивает контекст у родительского окна; LeadConnector отвечает в зашифрованном виде, мы расшифровываем ключом SSO приложения и показываем состояние связи: связанная организация, активные триггеры, доступные действия. Сознательная граница: контекст подтверждает локацию, а не личность в claritos — он не создаёт вход, и страница не показывает бизнес-данные.

Для операторов: настройка Marketplace

Приложение создаётся один раз на среду в портале разработчика LeadConnector (redirect-URL, webhook-URL для событий приложения, External Authentication с полем apiKey и verify-URL, custom actions с их полями, custom triggers с subscribe-URL, scopes). Client ID и secret задаются переменными окружения; подпись событий приложения (Ed25519) claritos проверяет публичным ключом из документации. Имена полей и нагрузки вызовов LeadConnector обрабатываются в коде терпимо (data/плоско, triggerData/meta) — при первом запуске сверьте с актуальной документацией Marketplace. Адреса в форме (без марки в пути): redirect {BASE}/api/integrations/leadconnector/callback, webhook для событий приложения {BASE}/api/integrations/leadconnector/uninstall, verify-URL {BASE}/api/integrations/leadconnector/external-auth, действия {BASE}/api/integrations/leadconnector/actions/<key>, subscribe-URL {BASE}/api/integrations/leadconnector/triggers, пункт меню {BASE}/embed/leadconnector. Прежние адреса остаются доступными как псевдонимы. Scope: только workflows.readonly, потому что приложение не вызывает API платформы.