claritos
deenru

LeadConnector

Drei Wege, claritos mit LeadConnector zu verbinden — und die Marketplace-App, die Aktionen und Auslöser direkt in den LeadConnector-Workflow-Builder bringt.

Drei Wege

Weg A: LeadConnector-Workflow-Aktion „Webhook“ ruft die HTTP-API (Authorization: Bearer capi_…), und claritos-Webhooks stoßen LeadConnector-Workflows über den „Inbound Webhook“-Auslöser an. Weg B: der claritos-MCP als externer MCP-Server in LeadConnector-KI-Agenten. Weg C: die Marketplace-App — Aktionen und Auslöser mit Formularfeldern statt JSON. Dieser Leitfaden beschreibt Weg C; A und B brauchen nur die Leitfäden „Webhooks“ und „MCP“.

Installation

Aus den Organisations-Einstellungen (Tab „Integrationen“ → „Mit LeadConnector verbinden“): LeadConnector fragt nach der Location, claritos speichert die Installation (Token verschlüsselt) und verknüpft sie mit der Organisation, in der der Knopf gedrückt wurde. Alternativ aus dem LeadConnector-Marketplace installieren — dann verknüpft die External Authentication (nächster Abschnitt) die Location mit der Organisation.

External Authentication (API-Schlüssel)

Beim Verbinden der App in LeadConnector trägt der Nutzer einen claritos-API-Schlüssel ein. LeadConnector prüft ihn gegen die Verify-URL; claritos antwortet mit der Organisation und merkt sich die Verknüpfung Location ↔ Organisation. Danach schickt LeadConnector den Schlüssel bei jeder Aktion als Authorization-Header mit — Scopes, Ratenlimits, Aufruf-Protokoll und Klientendaten-Gate gelten wie bei jedem API-Aufruf.

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" }

Aktionen (Custom Workflow Actions)

Jede Aktion ist eine Feld-Abbildung auf genau einen API-Endpunkt und liefert dessen Antwort zurück (Felder in LeadConnector per Response-Mapping nutzbar). Verfügbar: contact-create (Kontakt anlegen), task-create (Aufgabe), sms-send (SMS über Twilio), quote-create (Angebots-Entwurf), invoice-create (Rechnungs-Entwurf), form-response (Formular-Antwort → Lead). Fehler kommen als Problem-Details (RFC 9457) mit dem HTTP-Status des Endpunkts; LeadConnector zeigt sie im Ausführungsprotokoll. Neu: invoice-issue (Rechnung festschreiben; die Antwort ergänzt `documents` mit PDF-Status und -Adresse, ob das ZUGFeRD-XML bereit ist, wo es liegt, sonst `pending: xml-not-ready`). Braucht `invoices:write`. Dazu set-custom-field: setzt ein eigenes Feld am Kontakt (Feld-Schlüssel und Wert, leerer Wert löscht). Den Kontakt findet die Aktion über die claritos-Kontakt-ID oder die E-Mail; sie legt keinen an. Teilen sich mehrere Kontakte die E-Mail, antwortet sie mit 409 und dem Grund contact-ambiguous, gibt es keinen, mit 404 und contact-not-found. Der Schlüssel braucht 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", … }

Auslöser (Custom Workflow Triggers)

Legt ein Nutzer einen claritos-Auslöser im Workflow-Builder an, ruft LeadConnector die Subscribe-URL mit Ziel-URL auf; claritos legt dafür intern einen Webhook-Endpunkt an (mit Backoff, Zustellprotokoll und Alarmen wie jeder Endpunkt) und liefert die Ereignisse in der Standard-Nutzlast. Verfügbar: lead_created, contact_created, invoice_paid, invoice_issued, quote_accepted, esign_completed, form_submitted, task_done. Löscht der Nutzer den Auslöser, wird der Endpunkt entfernt; gleiches beim Trennen der Location oder bei Deinstallation. Dazu Zahlungen: checkout_pending (Zahlung eingeleitet, bei SEPA noch kein Geld), checkout_completed (Zahlung eingegangen, hier freischalten) und checkout_failed (gescheitert, zurückgebucht oder Rate ausgefallen, hier sperren). Nutzlast `checkout` mit Betrag in Cent, Währung, E-Mail und Name des Kunden (customerEmail, customerName), Link-Kennung und Titel (checkoutLinkId, checkoutLinkName), bei Rechnungen Kennung und Nummer, Auftrag (orderId, orderNumber), bei checkout_failed der Grund failureReason (direct_debit_failed, chargeback, no_mandate, payment_failed). Rechnung, Angebot und Aufgabe tragen contactEmail, damit ein Workflow den Kontakt mit „Find Contact“ findet. Ist die App per OAuth installiert, trägt jede Zustellung zusätzlich das Zugangstoken der Installation (Authorization: Bearer, Version-Kopfzeile); die Signatur der Standard-Nutzlast bleibt.

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, … } }

Weg A ohne App

Ohne Marketplace-App genügt die HTTP-API: In LeadConnector die Workflow-Aktion „Webhook“ (Methode/URL/Header/Body wie in der Referenz) — und in claritos ein Webhook-Endpunkt auf die URL des LeadConnector-„Inbound Webhook“-Auslösers (Leitfaden „Webhooks“, Abschnitt „Plattformen“). Vorteil: alle 140+ Endpunkte und alle Ereignisse; Nachteil: JSON statt Formularfelder.

Weg B: MCP in LeadConnector-KI-Agenten

LeadConnector-Konversations-KI und Voice-Agenten können externe MCP-Server einbinden. URL https://www.claritos.io/api/mcp/v1 mit Authorization-Header (API-Schlüssel) eintragen — der Agent bekommt genau die Werkzeuge, die der Schlüssel darf (Leitfaden „MCP“).

Menüpunkt in LeadConnector (SSO)

claritos kann als Menüpunkt in LeadConnector erscheinen (Custom Menu Link auf {BASE}/embed/leadconnector, „Open in iframe“). Die Seite fragt den Kontext beim Eltern-Fenster an; LeadConnector antwortet verschlüsselt, wir entschlüsseln mit dem SSO-Schlüssel der App und zeigen den Zustand der Verbindung: verknüpfte Organisation, aktive Auslöser, verfügbare Aktionen. Bewusste Grenze: der Kontext belegt die Location, nicht eine claritos-Identität — er erzeugt keine Anmeldung und die Seite zeigt keine Geschäftsdaten.

Für Betreiber: Marketplace-Einrichtung

Die App wird einmal je Umgebung im LeadConnector-Developer-Portal angelegt (Redirect-URL, Webhook-URL für App-Ereignisse, External Authentication mit Feld apiKey und Verify-URL, Custom Actions mit ihren Feldern, Custom Triggers mit Subscribe-URL, Scopes). Client-ID und -Secret kommen als Umgebungsvariablen in die App; die Signatur der App-Ereignisse (Ed25519) prüft claritos mit dem öffentlichen Schlüssel aus der Doku. Feldnamen und Nutzlasten der LeadConnector-Aufrufe sind im Code tolerant ausgelegt (data/flach, triggerData/meta) — beim ersten Lauf gegen die aktuelle Marketplace-Doku prüfen. Adressen im Formular (ohne Marke im Pfad): Redirect {BASE}/api/integrations/leadconnector/callback, Webhook für App-Ereignisse {BASE}/api/integrations/leadconnector/uninstall, Verify-URL {BASE}/api/integrations/leadconnector/external-auth, Aktionen {BASE}/api/integrations/leadconnector/actions/<key>, Subscribe-URL {BASE}/api/integrations/leadconnector/triggers, Menüpunkt {BASE}/embed/leadconnector. Ältere Adressen bleiben als Alias erreichbar. Scope: nur workflows.readonly, weil die App die API der Plattform nicht aufruft.