Integration handbook for partners

Dieses Handbuch richtet sich an Produkt- und Entwicklerteams, die ihr Werkzeug mit Set2Sell verbinden wollen — etwa Funnel- und Formular-Tools, Werbe- und Tracking-Plattformen, Telefonie, Buchhaltung oder KI-Assistenten. Es beschreibt ausschließlich Schnittstellen, die heute live sind. Jede Angabe wurde gegen den aktuellen Programmcode und per Live-Aufruf gegen die Produktionsumgebung geprüft.

---

1. Auf einen Blick

Set2Sell ist ein CRM für Vertriebsteams: Leads laufen als Deals durch Pipelines mit Phasen, dazu kommen Termine, Anrufe, Aufgaben, Funnels und Automationen. Für die Anbindung von außen gibt es fünf Wege:

Welcher Weg passt?

• Du baust eine eigene Integration in deinem Produkt: REST-API v1 für das Schreiben und Lesen, Webhook-Abos für das Reagieren auf Ereignisse. Beides zusammen deckt den Normalfall vollständig ab.
• Du willst nur Leads abliefern und hast ein No-Code-Tool ohne eigene Auth-Logik: Lead-Import-Webhook. Für neue, professionelle Integrationen empfehlen wir trotzdem POST /api/v1/deals, weil dort Rate-Limit, Fehlerformat und Berechtigungen sauberer sind.
• Deine Kunden nutzen Zapier: Zapier-App verlinken, fertig. Make und n8n arbeiten über deren HTTP-Module direkt mit REST-API und Webhook-Abos.
• Du baust einen KI-Agenten: MCP-Server.

---

2. Grundlagen

2.1 Datenmodell in acht Begriffen

2.2 Domains und Serverstandort

Die Anwendung läuft in Frankfurt am Main (Vercel-Region fra1), die Datenbank liegt bei Supabase in der Region eu-central-1 (ebenfalls Frankfurt). Ausgehende Webhook-Aufrufe kommen aus dieser Umgebung; eine feste Absender-IP-Liste gibt es nicht. Empfänger sollten deshalb die Signatur prüfen (Abschnitt 4.4), nicht die IP.

Es gibt keine separate Sandbox-Umgebung. Für Tests legt Set2Sell auf Anfrage einen eigenen Test-Workspace an (Abschnitt 9).

2.3 Sicherheitsmodell

• Nur HTTPS. Webhook-Ziele müssen https:// sein; lokale und private Adressen werden abgelehnt.
• API-Keys werden nur als SHA-256-Hash gespeichert und genau einmal im Klartext angezeigt. Sie können jederzeit vom Workspace-Admin widerrufen werden. Nur Workspace-Admins können Keys anlegen. Jeder Key trägt eine Stufe (nur lesen, lesen & schreiben, voll; Abschnitt 3.2) und handelt als sein Ersteller: Verliert der Ersteller die Admin-Rolle oder verlässt den Workspace, antwortet die API mit 403 bzw. der Key wird automatisch widerrufen.
• Webhook-Signaturen sind HMAC-SHA256 mit einem Secret pro Abo, das ebenfalls nur einmal angezeigt wird.
• Rate-Limits gelten pro Key (bzw. pro Person bei OAuth), pro Workspace und für teure Routen separat; sie werden über Antwort-Header sichtbar gemacht (3.2).
• Mandantentrennung ist serverseitig erzwungen: Jede Abfrage der REST-API wird auf den Workspace des Keys gefiltert. Eine fremde pipeline_id oder deal_id liefert 404, nie fremde Daten.

2.4 Was welcher Weg auslöst

Im Cockpit reagieren zwei getrennte Systeme auf Änderungen: Webhook-Abos (nach außen, Abschnitt 4) und die Automationen des Kunden (im Produkt: E-Mail-Strecken, Aufgaben, Phasenwechsel). Nicht jeder Entstehungsweg eines Deals stößt beide an. Diese Matrix zeigt den heutigen Stand; plane deine Integration danach.

Wenn ein Deal entsteht:

Wenn ein Deal die Phase wechselt:

Ein Phasenwechsel über den MCP-Server wirkt wie einer im Deal-Drawer: neben den Webhook-Abos laufen die Zuweisungsregel der Zielphase, die Team-Benachrichtigung, phasengesteuerte Sequenzen und die Automationen „Deal: Stage gewechselt" / „Deal: Status geändert".

Praktische Folge: Wenn dein Produkt Deals anlegt oder verschiebt und der Kunde erwartet, dass seine Automationen darauf reagieren, ist das heute beim Anlegen nur über den Lead-Import-Webhook gegeben, beim Verschieben nur über den MCP-Server. Über REST-API und Lead-Import-Update starten beim Verschieben keine Automationen — sprich uns an, wenn du diesen Fall hast; die Lücke ist bekannt und auf der Liste. Für deine eigenen Reaktionen auf Ereignisse sind die Webhook-Abos unabhängig davon vollständig.

---

3. REST-API v1

3.1 API-Key anlegen (Kundenseite)

Der Kunde erzeugt den Key selbst:

1. Im Cockpit Einstellungen → Workspace → Tab „API" öffnen (nur als Workspace-Admin sichtbar).
2. Neuen Key anlegen, einen Namen vergeben (z. B. den Namen deines Produkts) und eine Stufe wählen: „Nur lesen", „Lesen & schreiben" (Standard) oder „Voll" (3.2).
3. Der Key s2s_live_… wird genau einmal angezeigt. Der Kunde kopiert ihn in deine Integration.

In der Übersicht sieht der Kunde später nur die ersten Zeichen (s2s_live_ab12cd…), das Anlegedatum und die letzte Nutzung, und kann den Key widerrufen. Ein widerrufener Key verhält sich nach außen wie ein unbekannter Key (401).

Deals, die über einen Key angelegt werden, gehören dem Nutzer, der den Key erstellt hat.

3.2 Authentifizierung, Rate-Limit, Fehlerformat

Header bei jeder Anfrage:

Authorization: Bearer s2s_live_…
Content-Type: application/json

Vollständige Referenz: GET https://cockpit.set2sell.io/api/v1/openapi.json (OpenAPI 3.1, stets aktuell, mit Schemas, Stufen und Fehlercodes je Operation) und GET /api/v1/llms.txt (kompakte Übersicht). Dieses Handbuch erklärt die Zusammenhänge; die Tabelle in 3.3 nennt die Endpunkte, 3.3a die Gruppen, die dort nur kurz stehen.

Der Key handelt als sein Ersteller. Bei jeder Anfrage wird geprüft, dass der Ersteller noch aktives Mitglied und Workspace-Admin ist (sonst 403 forbidden_role); gesperrte Konten oder Workspaces antworten 403 account_locked. Verlässt der Ersteller den Workspace, wird der Key automatisch widerrufen und seine Zapier-Webhook-Abos werden pausiert (paused_reason: creator_left).

Stufen (Scopes) pro Key. Der Kunde wählt beim Anlegen eine von drei Stufen (Standard für neue Keys: „Lesen & schreiben"); vor Einführung der Stufen angelegte Keys haben vollen Zugriff.

Fehlt die Stufe, antwortet die API mit 403 forbidden_scope, bevor etwas geändert wird. Ausnahmen von der Faustregel (GET = read, POST/PATCH = write, DELETE = delete): POST /deals/merge und alle DELETE-Operationen auf Feldern, Listen, Ansichten, Aufgaben und Kontakten brauchen delete; POST /deals/{id}/restore und DELETE /deals/{id}/tags brauchen nur write; alle /hooks-Operationen brauchen nur write, damit sich Zapier mit „Lesen & schreiben" wieder abmelden kann. Die Stufe jeder Operation steht in der OpenAPI. Zapier braucht mindestens „Lesen & schreiben".

OAuth statt API-Key. Neben s2s_live_…-Keys akzeptiert die API ein Clerk-OAuth- Access-Token: Authorization: Bearer <token> plus der Pflicht-Header X-Workspace-Id: <Workspace-UUID> (ohne ihn 422). Es gilt dieselbe Prüfung (die Person hinter dem Token muss Admin des Workspace sein), die Stufen sind voll. Partner-Apps für OAuth registriert Set2Sell — melde dich über den Kontakt in Abschnitt 9; eine selbstverwaltete Registrierung gibt es nicht. (Der MCP-Server in Abschnitt 7 nutzt denselben Autorisierungsserver, aber einen eigenen Endpunkt.) Schickt ein Key-Aufruf einen X-Workspace-Id, der nicht zum Workspace des Keys passt, kommt 422.

Rate-Limits. Drei Eimer, der engste gewinnt:

Jede Antwort — auch 4xx und 5xx — trägt diese Header; eine 429 trägt die Zahlen des Eimers, der angeschlagen hat:

Der Zähler ist über alle Server-Instanzen geteilt, das Limit gilt also global. Zusätzlich werden fehlgeschlagene Authentifizierungen pro IP gezählt (20 pro Minute). Wer ungültige Keys durchprobiert, bekommt 429 statt weiterer 401.

Fehlerformat (einheitlich für alle v1-Routen; details nur bei Zusatzkontext):

{ "error": { "code": "validation_error", "message": "pipeline_id: Invalid UUID" } }

Zwei Regeln, die viele Integratoren überraschen:

• Unbekannte Felder und Query-Parameter werden mit 422 abgelehnt, nicht still ignoriert. Ein ?page=2 oder ein "status": "gewonnen" im Body ist ein Fehler.
• Kein 400. Ungültiges JSON landet ebenfalls als 422 validation_error.

Konventionen für Listen und POST:

• fields= auf jedem GET: Feldauswahl (fields=id,contact.email); ein unbekannter Pfad → 422.
• sort= dort, wo der Endpunkt es anbietet (-feld = absteigend). Dann ist next_cursor undurchsichtig: unverändert als cursor zurückgeben, nicht deuten.
• include_counts=true dort, wo angeboten: liefert total (bei /deals auch total_value). Gezählt wird pro Anfrage — mit der ersten Seite mitschicken.
• Idempotenz: Jedes POST akzeptiert Idempotency-Key (1–255 Zeichen; ein leerer Header gilt als fehlend). Gleicher Key + gleiche Anfrage innerhalb von 24 Stunden → die gespeicherte Antwort, mit Header Idempotent-Replayed: true. Gleicher Key mit anderer Anfrage → 422 idempotency_mismatch; läuft das Original noch → 409 conflict. 5xx, 429 und 402 werden nicht gespeichert, ein Retry ist also gefahrlos. Nicht unterstützt (422, wenn der Header kommt): POST /hooks (die Antwort enthält das Einmal-Secret) sowie POST /contacts/search und POST /deals/search (reine Lesevorgänge, einfach wiederholbar).

3.3 Endpunkt-Referenz

Alle Pfade relativ zu https://cockpit.set2sell.io/api/v1.

3.3a Weitere Endpunktgruppen

Diese Gruppen sind in der Tabelle oben nicht einzeln aufgeführt; Parameter, Schemas und Stufen stehen in der openapi.json.

Sequenzen im Sinne von Close bildet Set2Sell mit Automationen ab; einen eigenen /sequences-Endpunkt gibt es nicht.

Alle Operationen dieser Gruppen (Pipelines, Sperrlisten, Mitglieder, Einladungen, Vorlagen, Automationen) setzen einen Workspace-Admin als Key-Ersteller voraus (siehe 3.2) und brauchen die Stufe aus der Tabelle in 3.2: GET = read, POST/PATCH/PUT = write, DELETE = delete — Ausnahme: POST /email-templates/{templateId}/render liest nur (read).

Versand (E-Mail, SMS, WhatsApp)

POST /emails, POST /sms und POST /whatsapp-messages laufen über denselben Weg wie der Versand aus dem Cockpit (Absender, Signatur, Kontingent, Zeitleiste) und zusätzlich durch dieselben Leitplanken. Alle drei liegen im teuren Rate-Limit-Eimer (60/Minute, 3.2) und brauchen die Stufe write.

mode:

Leitplanken, in dieser Reihenfolge — alle vor dem Versand, bei einem Treffer wird nichts gesendet oder gezählt:

1. Kontaktverbot. Steht der Empfänger auf der Sperrliste „Nicht kontaktieren“ des Workspace → 422 blocked, details.reason: contact_block. Bei SMS und WhatsApp wird die Nummer in allen Schreibweisen verglichen (079…, +4179…, 0049…). Das ist strenger als die App, die dort heute nicht prüft.
2. Sperrliste (E-Mail). Adresse auf der Unterdrückungsliste (Bounces, Beschwerden) → 422 blocked, reason: suppressed.
3. Absender. E-Mail braucht ein Absenderkonto des Workspace mit verifizierter Domain; SMS/WhatsApp einen aktiven Kanal → 422 validation_error.
4. Abo und Kontingent. Ohne aktives Abo oder bei erschöpftem Kontingent → 402 payment_required. (Das E-Mail-Kontingent wird beim tatsächlichen Versand geprüft, bei schedule also zu scheduled_at; die Mail steht dann auf failed.)
5. WhatsApp-Vorlage und 24-Stunden-Fenster. Freitext (body) ist nur innerhalb von 24 Stunden nach der letzten Nachricht des Kontakts erlaubt; eine Erstnachricht braucht immer eine freigegebene Vorlage (template_id + template_variables, alle Platzhalter gefüllt) → sonst 422 blocked, reason: whatsapp_window_closed (fehlende oder unvollständige Vorlage: 422).

Empfängernummer. SMS und WhatsApp normalisieren die Nummer wie die App zu E.164 (nationale Schreibweisen werden mit der Landesvorwahl der Absendernummer des Kanals gelesen, sonst +49). Ist sie nicht wählbar → 422 validation_error mit Feld to. Geprüft und gesendet wird an genau dieselbe Nummer.

Anbieter-Ablehnung. Lehnt Twilio dauerhaft ab (ungültige Nummer, Empfänger hat mit STOP abgemeldet, 4xx außer 401/403/429) → 422 blocked, reason: provider_rejected, details.provider_code. Dieselbe Anfrage scheitert wieder, deshalb wird die Antwort gespeichert. Bei 401/403/429, 5xx oder wenn der Anbieter nicht antwortet → 502 provider_error (nicht gespeichert).

Idempotenz. Sende bei jedem Versand einen Idempotency-Key: eine Wiederholung mit demselben Key liefert die gespeicherte Antwort und sendet nicht erneut — auch dann, wenn der Anbieter angenommen, das Speichern aber gescheitert ist (SMS/WhatsApp: message ist dann null). 402 und 5xx werden nicht gespeichert. Der einzige Fall, in dem eine Wiederholung erneut senden kann: ein 502, bei dem der Anbieter nicht geantwortet hat — er kann die Nachricht trotzdem zugestellt haben.

Termine buchen

POST /appointments bucht wie das Cockpit (Deal-Drawer, Kalender): Bestätigungsmail und Erinnerungen der Terminart (an den Kontakt des Deals, sonst booked_by_email/ booked_by_phone), Mail an den Gastgeber (falls nicht du selbst), die Webhooks appointment.* (4.2), Automationen „Termin gebucht“, Ort und Videoraum der Terminart und der Kalender-Push zum verbundenen Kalender des Gastgebers. Gebucht wird mit booking_source internal. Ein aktives Abo ist nötig (402).

• Gastgeber: host_id, sonst der Gastgeber der Terminart (Round Robin unter ihren Mitgliedern), sonst der Ersteller des Keys.
• Überschneidung: belegt der Gastgeber die Zeit schon → 409 conflict.
• Außerhalb der Arbeitszeiten, an einem freien Tag oder über dem Tageslimit wird der Termin trotzdem gebucht; die Antwort trägt ein warning. Belegte Zeiten in externen Kalendern werden nur bei der Wahl des Round-Robin-Mitglieds geprüft — rufe vorher GET /event-types/{id}/slots ab.
• Round Robin: ist zur gewünschten Zeit kein Mitglied frei → 409; hat die Terminart keine aktiven Mitglieder → 422.
• Idempotenz: sende einen Idempotency-Key. Ohne ihn bucht ein Wiederholungsversuch erneut (bei Round Robin womöglich bei einem anderen Mitglied).
• Absagen: POST /appointments/{id}/cancel setzt den Status auf abgesagt (der Termin bleibt als Nachweis), stoppt Erinnerungen, benachrichtigt den Gebuchten, entfernt den Kalendereintrag und feuert appointment.cancelled. Ein bereits abgesagter Termin kommt unverändert zurück, ohne zweite Benachrichtigung — Wiederholen ist gefahrlos. DELETE /appointments/{id} löscht dagegen endgültig und sendet keinen Webhook.
• Verschieben: PATCH mit neuer start_time/end_time aktualisiert den Kalender, benachrichtigt den Gebuchten und feuert appointment.rescheduled; eine belegte Zeit → 409.

Änderung am Vertrag (29.10.2026): next_cursor von GET /appointments. Der Cursor ist jetzt eine undurchsichtige Zeichenkette statt der Termin-ID. Gib next_cursor unverändert als cursor zurück und werte ihn nicht aus. Ein alter Cursor in Form einer Termin-UUID wird weiter angenommen. Der Cursor gilt nur für dieselbe Sortierung (order): ein Cursor aus asc mit order=desc (oder umgekehrt) → 422.

GET/me

curl https://cockpit.set2sell.io/api/v1/me \
  -H "Authorization: Bearer s2s_live_…"

{
  "data": {
    "team": { "id": "3f2c…", "name": "Beispiel GmbH", "currency": "EUR" },
    "scopes": ["read", "write"],
    "user": { "id": "user_3JB…", "role": "admin" }
  }
}

scopes sind die Stufen des Aufrufers (["read"], ["read","write"] oder ["read","write","delete"]), user die handelnde Person: der Ersteller des Keys bzw. der angemeldete OAuth-Nutzer.

currency ist der ISO-4217-Code der Workspace-Währung; alle value-Beträge von Deals sind in dieser Währung.

GET/members

Aktive Mitglieder des Workspace. id ist die Nutzer-ID (user_…), unter der Deals owner_id, setter_id und closer_id führen und Phasenwechsel changed_by. Die Zuordnung zu Personen in deinem System läuft am besten über email.

curl https://cockpit.set2sell.io/api/v1/members \
  -H "Authorization: Bearer s2s_live_…"

{
  "data": [
    { "id": "user_3JB…", "name": "Anna Beispiel", "email": "anna@example.com",
      "role": "admin", "joined_at": "2026-01-15T09:30:00.000Z" }
  ]
}

role ist owner | admin | member | viewer. Ausgeschiedene Mitglieder erscheinen nicht mehr — wer den Zugang in deinem System an die Mitgliedschaft koppelt, gleicht regelmäßig gegen diese Liste ab. IDs, die in älteren Deals oder im Phasenverlauf stehen, aber hier fehlen, gehören ehemaligen Mitgliedern.

GET/pipelines

Liefert alle aktiven (nicht gelöschten, nicht archivierten) Pipelines, sortiert nach Position, jeweils mit ihren Phasen.

{
  "data": [
    {
      "id": "8a1e…", "name": "Vertrieb", "is_default": true,
      "stages": [
        { "id": "c0d1…", "name": "Neu",        "position": 0, "mapped_status": "offen" },
        { "id": "c0d2…", "name": "Termin",     "position": 1, "mapped_status": "termin" },
        { "id": "c0d3…", "name": "Gewonnen",   "position": 2, "mapped_status": "gewonnen" },
        { "id": "c0d4…", "name": "Verloren",   "position": 3, "mapped_status": "verloren" }
      ]
    }
  ]
}

Die mapped_status-Werte brauchst du, um zu wissen, welche Phase einen Deal auf „gewonnen" oder „verloren" setzt.

PATCH/pipelines/{pipelineId}/stages/{stageId}

Status-Zuordnung (mapped_status) oder name einer Phase ändern. Damit gleicht ein Partner ab, welche Phase als offen, gewonnen oder verloren zählt.

curl -X PATCH https://cockpit.set2sell.io/api/v1/pipelines/8a1e…/stages/c0d3… \
  -H "Authorization: Bearer s2s_live_…" -H "Content-Type: application/json" \
  -d '{ "mapped_status": "gewonnen" }'

Antwort: { "data": { "id", "pipeline_id", "name", "position", "mapped_status" } }. mapped_status nimmt die sechs Status-Werte aus 11.1. Deals, die bereits in der Phase stehen, behalten ihren Status, bis sie das nächste Mal verschoben werden — wie beim Umbau im Pipeline-Editor. 404, wenn Pipeline oder Phase nicht zum Workspace gehören.

GET/deals

Query-Parameter (alle optional; unbekannte Parameter → 422):

{ "data": [ …Deal… ], "next_cursor": "9b7f…" }

Blättern: Solange next_cursor nicht null ist, die Anfrage mit ?cursor=<wert> wiederholen. Die Reihenfolge ist stabil, aber nicht chronologisch (sortiert nach id). Für „alles seit Zeitpunkt X" deshalb updated_since verwenden, nicht die Cursor-Reihenfolge.

Löschungen erkennen: Ein gelöschter Deal verschwindet aus allen Antworten, auch aus updated_since-Abfragen. Wer Löschungen nachvollziehen will, pollt zusätzlich GET /deals?deleted_since=<letzter Lauf> — die Antwort trägt dann deleted_at. Das ergänzt das Ereignis deal.deleted, falls eine Zustellung verloren ging. Löschungen sind 30 Tage nachvollziehbar; ein wiederhergestellter Deal taucht danach wieder normal auf.

POST/deals

curl -X POST https://cockpit.set2sell.io/api/v1/deals \
  -H "Authorization: Bearer s2s_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "8a1e…",
    "first_name": "Maria",
    "last_name": "Beispiel",
    "email": "maria@example.com",
    "phone": "+49 170 1234567",
    "company": "Beispiel GmbH",
    "value": 2500,
    "source": "dein-produkt",
    "tags": ["webinar-2026-09"],
    "notes": "Hat sich über das Herbst-Webinar angemeldet."
  }'

Body-Felder:

Antwort: 201 mit { "data": Deal } (Deal-Objekt siehe 3.4). Beim Anlegen wird eine Notiz „Deal über die öffentliche API erstellt" in die Zeitleiste des Deals geschrieben und das Webhook-Ereignis deal.created ausgelöst. Automationen des Kunden mit dem Auslöser „Deal: Neu erstellt" starten für API-Deals derzeit nicht (Matrix in 2.4).

Idempotenz: Mit dem Header Idempotency-Key (siehe 3.2) legt ein wiederholter POST (etwa durch einen Netzwerk-Retry) keinen zweiten Deal an — du bekommst die gespeicherte Antwort zurück. Ohne den Header gibt es keine serverseitige Dublettenprüfung: Prüfe vor dem Anlegen per GET /deals?search=<email> oder dedupliziere selbst. (Der Lead-Import-Webhook in Abschnitt 5 hat zusätzlich eine inhaltliche Dublettenerkennung — das ist der funktionale Unterschied zwischen den Wegen.)

GET/deals/{id}

200 mit { "data": Deal }; 404, wenn der Deal nicht zum Workspace gehört oder gelöscht ist; 422, wenn id keine UUID ist.

PATCH/deals/{id}

Akzeptiert dieselben Felder wie POST (pipeline_id nur zusammen mit stage_id, siehe unten), zusätzlich probability (ganze Zahl 0–100) sowie expected_close_date, setter_id und closer_id mit null zum Leeren. Nur gesendete Felder werden geändert.

curl -X PATCH https://cockpit.set2sell.io/api/v1/deals/9b7f… \
  -H "Authorization: Bearer s2s_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "c0d3…" }'

Ein stage_id-Wechsel setzt Status, Gewinn-/Abschlussdatum und Wahrscheinlichkeit automatisch — und leert sie wieder: Ein Deal, der aus „gewonnen" nach „verloren" oder in eine offene Phase zurückgeht, verliert sein won_date (bei offenen Phasen auch closed_at). Lies Umsatz deshalb über status, won_date ist nur bei status = gewonnen gesetzt. Ausgelöste Webhook-Ereignisse: immer deal.updated; bei Phasenwechsel zusätzlich deal.stage_changed; beim Kippen des Status zusätzlich deal.won oder deal.lost. Automationen des Kunden („Deal: Stage gewechselt", „Deal: Status geändert", „Deal: Tag hinzugefügt") reagieren auf API-Änderungen derzeit nicht (Matrix in 2.4).

Pipeline wechseln: pipeline_id zusammen mit stage_id verschiebt den Deal in eine andere Pipeline; die Phase muss zur Ziel-Pipeline gehören. Wie in der App entsteht ein Zeitleisten-Eintrag (im Phasenverlauf als Wechsel mit unterschiedlichen from_pipeline_id/to_pipeline_id). Archivierte oder gelöschte Ziel-Pipelines → 404, pipeline_id ohne stage_id → 422.

Was PATCH bewusst nicht kann:

• status, won_date, closed_at setzen. Diese Felder sind abgeleitet.
• probability gegen eine Gewonnen-/Verloren-Phase durchsetzen: Wird beides in einer Anfrage geschickt, gewinnt die Ableitung (100 bzw. 0).

Eigene Felder schreiben: custom_fields ist ein Objekt mit dem Feldnamen als Schlüssel (GET /custom-fields liefert Namen und Typen der Pipeline). Gültige Werte werden gespeichert und mit 200 bestätigt. Nur ein unbekannter Name oder ein falscher Typ antwortet 422, die Meldung nennt dann die vorhandenen Felder. Mitgeschickte Felder werden gesetzt, alle anderen bleiben unverändert.

curl -X PATCH https://cockpit.set2sell.io/api/v1/deals/9b7f… \
  -H "Authorization: Bearer s2s_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "custom_fields": { "Wunsch-Coaching": "Einzel", "Budget": 2500 } }'

DELETE/deals/{id}

204 ohne Rumpf. Der Deal verschwindet sofort aus Oberfläche und API, bleibt aber 30 Tage wiederherstellbar (Soft-Delete). Laufende E-Mail-Sequenzen des Deals werden beendet, und deal.deleted wird ausgelöst. 404, wenn der Deal nicht zum Workspace gehört oder bereits gelöscht ist.

GET/deals/{id}/stage-history

Alle Phasenwechsel eines Deals, älteste zuerst — auch für bereits gelöschte Deals. Quelle ist die Zeitleiste des Deals; jeder Schreibweg (Board, API, Automation, MCP, Import, Buchung, Funnel) hinterlässt dort einen Eintrag, deshalb ist der Verlauf vollständig und reicht zeitlich vor die Einrichtung deines Webhook-Abos zurück.

{
  "data": [
    {
      "id": "7c1a…", "deal_id": "9b7f…",
      "from_stage_id": "c0d1…", "to_stage_id": "c0d2…",
      "from_pipeline_id": "8a1e…", "to_pipeline_id": "8a1e…",
      "from_status": "offen", "to_status": "termin",
      "changed_at": "2026-09-12T14:03:11.412Z",
      "changed_by": "user_3JB…", "actor_kind": "user"
    }
  ]
}

changed_by ist die Nutzer-ID des Handelnden (GET /members); bei Automationen der Deal-Besitzer, erkennbar an actor_kind: "automation". actor_kind ist null bei Einträgen vor September 2026. Ein Pipeline-Wechsel erscheint als Wechsel mit unterschiedlichen from_pipeline_id/to_pipeline_id.

POST/deals/{id}/notes

Notiz an die Zeitleiste des Deals — erscheint in der Oberfläche wie eine von Hand geschriebene Notiz und löst note.created aus.

curl -X POST https://cockpit.set2sell.io/api/v1/deals/9b7f…/notes \
  -H "Authorization: Bearer s2s_live_…" -H "Content-Type: application/json" \
  -d '{ "text": "Rückruf für Donnerstag vereinbart." }'

text: 1 bis 10.000 Zeichen. Antwort 201 mit dem Eintrag im Format von GET /activities (type: "note", user_id = Ersteller des API-Keys). 404 für fremde oder gelöschte Deals.

POST/deals/merge

Dubletten in einen Hauptdeal zusammenführen — dieselbe Funktion wie „Zusammenführen" in der Oberfläche.

curl -X POST https://cockpit.set2sell.io/api/v1/deals/merge \
  -H "Authorization: Bearer s2s_live_…" -H "Content-Type: application/json" \
  -d '{ "primary_deal_id": "9b7f…", "duplicate_deal_ids": ["1c2d…", "3e4f…"] }'

Was passiert: Leere Felder des Hauptdeals werden aus den Dubletten gefüllt (Kontakt, Firma, Vor-/Nachname; beim Wert gewinnt der höhere), Tags werden vereinigt, Notizen angehängt; Aktivitäten, Termine, Aufgaben, Anrufe und eigene Felder wandern zum Hauptdeal; die Dubletten werden gelöscht (Soft-Delete). Ausgelöste Ereignisse: deal.deleted je Dublette, dann deal.updated für den Hauptdeal.

{
  "data": {
    "deal": { …Hauptdeal… },
    "merged_deal_ids": ["1c2d…", "3e4f…"],
    "merged_count": 2,
    "fields_updated": { "company": "Beispiel GmbH" }
  }
}

Bis zu 20 Dubletten je Aufruf. 404, wenn einer der Deals nicht (mehr) zum Workspace gehört — dann wird nichts zusammengeführt.

GET/stage-changes

Dieselben Einträge für den ganzen Workspace, chronologisch (changed_at, dann id). Damit liest du den Verlauf einmal komplett und danach inkrementell.

{ "data": [ …Eintrag wie oben… ], "next_cursor": "7c1a…" }

Inkrementell: since auf den changed_at-Wert des letzten verarbeiteten Eintrags setzen und über die Eintrags-id deduplizieren (der erste Treffer ist der bereits bekannte). Innerhalb einer Antwort blätterst du mit cursor, bis next_cursor null ist. Ein unbekannter cursor (fremder Workspace) antwortet 422.

GET/activities

Zeitleisten-Einträge des ganzen Workspace, chronologisch (created_at, dann id): Anrufe, Notizen, E-Mails, Termine, Aufgaben, SMS, WhatsApp, Phasenwechsel. Das ist der vollständige Kontaktverlauf je Interessent und die Aktivität je Teammitglied.

{
  "data": [
    {
      "id": "5e6f…", "deal_id": "9b7f…", "type": "call",
      "description": "Anruf: erreicht, Termin vereinbart",
      "user_id": "user_3JB…", "direction": "outbound", "duration_seconds": 312,
      "created_at": "2026-09-12T14:03:11.412Z"
    }
  ],
  "next_cursor": null
}

direction (inbound | outbound) und duration_seconds sind bei Anrufen, SMS, WhatsApp und E-Mails gesetzt, sonst null. user_id ist null bei Einträgen, die das System geschrieben hat. Inkrementell wie bei /stage-changes: since auf den letzten created_at setzen und über id deduplizieren.

GET/appointments

Termine des Workspace, sortiert nach Beginn (start_time, dann id).

{
  "data": [
    {
      "id": "7a8b…", "title": "Erstgespräch mit Maria Beispiel", "status": "erschienen",
      "start_time": "2026-09-18T09:00:00.000Z", "end_time": "2026-09-18T09:30:00.000Z",
      "deal_id": "9b7f…", "host_id": "user_3JB…", "created_by": "user_3JB…",
      "event_type_id": "e1f2…", "event_type_name": "Erstgespräch 30 min",
      "location": "https://meet.example/…", "description": null,
      "booking_source": "booking_page", "timezone": "Europe/Berlin",
      "created_at": "…", "updated_at": "…"
    }
  ],
  "next_cursor": null
}

host_id ist der Gastgeber (Kalenderinhaber, meist der Closer), created_by wer den Termin angelegt hat (bei Setter-Buchungen der Setter; bei Buchungen über Buchungsseite oder Funnel ebenfalls der Gastgeber). Status-Bedeutung: erschienen = stattgefunden, nicht_erschienen = No-Show, abgesagt = abgesagt, verschoben = neu terminiert.

GET/custom-fields

Optionaler Filter ?pipeline_id=<uuid> (404, wenn die Pipeline nicht zum Workspace gehört). Ohne Filter: Felder aller aktiven Pipelines.

{
  "data": [
    {
      "id": "f1a2…", "pipeline_id": "8a1e…",
      "name": "Wunsch-Coaching", "type": "select",
      "required": false,
      "options": { "options": ["Einzel", "Gruppe"] },
      "description": null
    }
  ]
}

name ist zugleich der Schlüssel, unter dem der Wert im Deal-Objekt (custom_fields) und im Lead-Import-Payload steht — exakte Schreibweise inklusive Groß-/Kleinschreibung und Leerzeichen. type ist eines von text | number | select | multiselect | boolean | date | email | phone | url.

🚨 options hat zwei Formen — bitte beide behandeln. Das Feld wird so ausgeliefert, wie es gespeichert ist. Der Normalfall ist das Objekt { "options": ["Einzel", "Gruppe"] }; aus Altbeständen kann dieselbe Angabe als flache Liste ["Einzel", "Gruppe"] kommen. Bei Feldern ohne Auswahl steht null oder {}. Robust auslesen:

const werte = Array.isArray(f.options) ? f.options : (f.options?.options ?? [])

Achtung, Asymmetrie: Beim Anlegen und Ändern schicken Sie options als flache Liste (siehe POST/PATCH unten) — zurück kommt sie als Objekt. Falls wir die Ausgabe künftig vereinheitlichen, kündigen wir das vorher an; mit dem Schnipsel oben sind Sie in beiden Fällen auf der sicheren Seite.

POST/custom-fields

Eigenes Feld an einer Pipeline anlegen — etwa beim Verbinden, statt das Team darum zu bitten. Gleicher Schreibpfad wie das MCP-Werkzeug create_custom_field.

curl -X POST https://cockpit.set2sell.io/api/v1/custom-fields \
  -H "Authorization: Bearer s2s_live_…" -H "Content-Type: application/json" \
  -d '{ "pipeline_id": "8a1e…", "name": "Partner-Code", "type": "text" }'

Antwort 201 im Format von GET /custom-fields. 409 conflict, wenn der Name in der Pipeline schon vergeben ist; 404, wenn die Pipeline nicht zum Workspace gehört.

PATCH/custom-fields/{id}·DELETE/custom-fields/{id}

Ein bestehendes Feld nachziehen — etwa wenn sich die Beschreibung in Ihrer Oberfläche ändert. Die id stammt aus GET /custom-fields oder aus der Antwort von POST.

curl -X PATCH https://cockpit.set2sell.io/api/v1/custom-fields/f1a2… \
  -H "Authorization: Bearer s2s_live_…" -H "Content-Type: application/json" \
  -d '{ "description": "Modul 3 · Stand September" }'

Mindestens ein Feld ist Pflicht. Antwort 200 im Format von GET /custom-fields. name und type sind nicht änderbar (422). Der Name ist der Schlüssel, unter dem die Werte am Deal stehen (custom_fields), und auch der Funnel-Weg ordnet eingehende Antworten über den Namen zu — ein umbenanntes Feld würde er beim nächsten Eingang als neues Feld anlegen, statt den Wert dem bestehenden zuzuordnen. Wer einen anderen Namen braucht, legt ein neues Feld an.

DELETE entfernt die Felddefinition und antwortet mit { "ok": true }. Dabei gehen die gespeicherten Werte dieses Feldes an allen Deals verloren — das lässt sich nicht rückgängig machen. Beide Aufrufe antworten mit 404, wenn das Feld nicht existiert oder nicht zum Workspace des Schlüssels gehört.

POST/hooks·PATCH/hooks/{id}·DELETE/hooks/{id}

Damit legt eine Integration ein Webhook-Abo programmatisch an, ohne dass der Kunde die Oberfläche bedienen muss (so arbeitet unsere Zapier-App).

curl -X POST https://cockpit.set2sell.io/api/v1/hooks \
  -H "Authorization: Bearer s2s_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dein Produkt",
    "url": "https://hooks.dein-produkt.de/set2sell/abc123",
    "events": ["deal.created", "deal.stage_changed", "appointment.created"]
  }'

201 mit { "data": { "id": "…", "secret": "…" } }. Das Secret wird nur in dieser Antwort ausgegeben — sofort speichern, du brauchst es für die Signaturprüfung. 422, wenn die URL kein HTTPS ist oder auf eine private Adresse zeigt. name ist optional (Standard „Zapier"). Erlaubte events siehe Abschnitt 4.2.

Per API angelegte Abos erscheinen dem Kunden in der Oberfläche als schreibgeschützt („von Zapier verwaltet"): Er sieht sie samt Zustellprotokoll, kann sie aber nicht bearbeiten. Anlegen und Entfernen liegt bei deiner Integration.

DELETE /hooks/{id} → 200 { "ok": true }. 404, wenn die ID unbekannt ist oder das Abo vom Kunden in der Oberfläche angelegt wurde — solche Abos sind über die API unantastbar.

Abo ändern: PATCH /hooks/{id} mit url, events, name und/oder active (alle optional, nur gesendete Felder ändern sich). Das Secret bleibt bestehen — Löschen und Neuanlage sind bei einer neuen Adresse nicht mehr nötig. active: true hebt eine Auto-Pause auf und setzt den Fehlerzähler zurück. Wie DELETE wirkt PATCH nur auf per API angelegte Abos; in der Oberfläche angelegte antworten 404.

GET/webhook-subscriptions

Alle Abos des Workspace, egal ob per Oberfläche oder API angelegt — ohne Secret.

{
  "data": [
    {
      "id": "…", "name": "Dein Produkt", "url": "https://…",
      "events": ["deal.stage_changed"], "active": true,
      "paused_at": null, "paused_reason": null,
      "failure_count": 0, "created_at": "2026-09-01T10:00:00.000Z"
    }
  ]
}

failure_count zählt endgültig gescheiterte Zustellungen in Folge; jede erfolgreiche Zustellung setzt ihn auf 0. Ab 20 wird das Abo automatisch pausiert (active: false, paused_at und paused_reason gesetzt). Damit kann deine Integration selbst erkennen, dass sie nichts mehr bekommt, statt auf den Kunden zu warten.

GET/webhook-subscriptions/{id}/deliveries

Zustellprotokoll eines Abos, neueste zuerst. Query: limit (1–100, Standard 50), status (pending | delivering | succeeded | failed | dead), since (ISO-8601, created_at >= since).

{
  "data": [
    {
      "id": "…", "event": "deal.stage_changed", "status": "succeeded",
      "attempt": 1, "last_response_status": 200, "last_response_body": "ok",
      "last_error": null, "duration_ms": 184,
      "created_at": "…", "delivered_at": "…", "next_attempt_at": null,
      "payload": { "id": "evt_…", "type": "deal.stage_changed", "data": { "…": "…" } }
    }
  ]
}

payload ist der gesendete Umschlag (Form in 4.3) — damit lässt sich eine fehlgeschlagene Zustellung ohne Nachstellen prüfen.

Bewusst ohne Cursor: Zustellungen eines Ereignis-Stapels teilen exakt denselben created_at-Stempel. Inkrementell pollst du mit since (leicht überlappend) und dedupliziert über die Delivery-id.

3.4 Das Deal-Objekt

So sieht ein Deal in allen v1-Antworten aus:

{
  "id": "9b7f…",
  "title": "Maria Beispiel",
  "status": "offen",
  "pipeline_id": "8a1e…",
  "stage_id": "c0d1…",
  "value": 2500,
  "contact": {
    "name": "Maria Beispiel",
    "first_name": "Maria",
    "last_name": "Beispiel",
    "email": "maria@example.com",
    "phone": "+49 170 1234567",
    "company": "Beispiel GmbH"
  },
  "tags": ["webinar-2026-09"],
  "custom_fields": { "Wunsch-Coaching": "Einzel" },
  "priority": "medium",
  "probability": 50,
  "source": "dein-produkt",
  "notes": "Hat sich über das Herbst-Webinar angemeldet.",
  "expected_close_date": null,
  "won_date": null,
  "closed_at": null,
  "owner_id": "user_3JB…",
  "setter_id": "user_3JB…",
  "closer_id": null,
  "stage_entered_at": "2026-09-12T14:03:11.412Z",
  "last_touch_at": "2026-09-14T09:20:00.000Z",
  "created_at": "2026-09-11T08:00:00.000Z",
  "updated_at": "2026-09-11T08:00:00.000Z",
  "deleted_at": null
}

Personen und Uhren:

custom_fields ist nach Feldname geschlüsselt und zeigt dieselben Werte wie die Oberfläche. Fehlende Werte sind null, nicht weggelassen.

Achtung, zwei Formen: Die REST-API liefert Kontaktdaten verschachtelt (contact.email). Webhook-Payloads liefern dagegen die flache Datenbankzeile (contact_email). Eine Integration, die beides verarbeitet, muss beide Formen kennen. Die Zuordnung steht in Abschnitt 4.3.

3.5 Verhaltensregeln auf einen Blick

• Status folgt der Phase. Nie status senden; stage_id verschieben.
• contact_name vs. Vor-/Nachname. Sende bevorzugt first_name und last_name. Ein alleiniger contact_name wird am letzten Leerzeichen geteilt („Anna Maria Müller" → Vorname „Anna Maria", Nachname „Müller"). Werden alle drei gesendet, gewinnen Vor- und Nachname.
• Idempotenz per Idempotency-Key bei jedem POST (3.2) — für Retries immer mitsenden. Der Lead-Import-Webhook dedupliziert zusätzlich inhaltlich.
• Cursor ist nicht chronologisch. Für Deltas updated_since.
• Löschen ist ein Soft-Delete. 30 Tage wiederherstellbar (durch den Kunden oder per POST /deals/{id}/restore); nachvollziehbar über GET /deals?deleted_since=….
• won_date gilt nur bei status = gewonnen. Wandert der Deal weiter, wird es geleert. Umsatz immer über status lesen.
• Personen sind Nutzer-IDs. owner_id, setter_id, closer_id, changed_by über GET /members auflösen; die Zuordnung zu deinem System läuft über email.
• source gehört dir. Setze deinen Produktnamen; der Kunde sieht ihn als Lead-Quelle und kann danach filtern.

3.6 Beispiel-Ablauf: Anbindung in vier Aufrufen

KEY="s2s_live_…"; BASE="https://cockpit.set2sell.io/api/v1"

# 1. Verbindung prüfen
curl -s "$BASE/me" -H "Authorization: Bearer $KEY"

# 2. Pipelines und Phasen holen, Ziel-Pipeline merken
curl -s "$BASE/pipelines" -H "Authorization: Bearer $KEY"

# 3. Deal anlegen
curl -s -X POST "$BASE/deals" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"pipeline_id":"8a1e…","first_name":"Maria","last_name":"Beispiel","email":"maria@example.com","source":"dein-produkt"}'

# 4. Später: Deal in die Phase „Termin" verschieben und den Setter eintragen
curl -s -X PATCH "$BASE/deals/9b7f…" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage_id":"c0d2…","setter_id":"user_3JB…"}'

# 5. Für Auswertungen: Mitglieder und Phasenverlauf lesen
curl -s "$BASE/members" -H "Authorization: Bearer $KEY"
curl -s "$BASE/stage-changes?since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $KEY"

---

4. Ausgehende Webhooks (Ereignis-Abos)

Set2Sell schickt Ereignisse per HTTP POST an eine URL deiner Wahl, sobald sie passieren. Die Zustellung ist signiert, wird bei Fehlern wiederholt und ist für den Kunden und für dich (per API) nachvollziehbar.

4.1 Abo einrichten

Über die Oberfläche (durch den Kunden): Einstellungen → Workspace → Tab „Webhooks" → Neuer Webhook: Name, HTTPS-URL, Ereignisse auswählen, optional eigene Header (z. B. ein eigener Auth-Token) mitgeben. Nach dem Speichern wird das Signing-Secret einmalig angezeigt.

Per API (durch deine Integration): POST /api/v1/hooks, siehe Abschnitt 3.3.

Über die Oberfläche kann der Kunde außerdem jederzeit ein Testereignis (webhook.test) auslösen, fehlgeschlagene Zustellungen erneut anstoßen und ein pausiertes Abo reaktivieren.

4.2 Ereignisse

Hinweise:

• deal.created deckt nicht jeden Entstehungsweg ab (Matrix in 2.4). Es feuert, wenn ein Nutzer einen Deal in der Oberfläche anlegt oder deine Integration POST /api/v1/deals aufruft. Deals aus Funnel, Buchungsseite, Lead-Import-Webhook oder MCP lösen es nicht aus. Für diese Wege abonniere die Quell-Ereignisse: funnel.submission_completed (trägt deal_id) und appointment.created (trägt deal_id in der Termin-Zeile). Wenn dein Produkt selbst Leads einspielt und gleichzeitig auf neue Deals hören will, lege sie über POST /api/v1/deals an.
• lead.imported feuert nur bei Datei- und Pipeline-Importen in der Oberfläche, nicht für Deals aus REST-API oder Lead-Import-Webhook.
• deal_id bei funnel.submission_completed ist null, solange die Einreichung noch keinem Deal zugeordnet ist; quiz_score ist null außerhalb von Quiz-Funnels.
• Mehrseitige Funnels: funnel.lead_captured kommt nach der Seite, die den Deal entstehen lässt, funnel.submission_completed erst nach der letzten Formularseite — beide mit derselben deal_id. Wer nur vollständige Datensätze will, abonniert ausschließlich submission_completed.
• appointment.created trägt attribution (Werbe-Klick-IDs, UTM-Parameter, Landing-URL), wenn die Buchung über eine Buchungsseite oder einen Funnel kam.

4.3 Zustellformat

Jede Zustellung ist ein POST mit Content-Type: application/json und diesen Headern:

X-Set2Sell-Event: deal.stage_changed
X-Set2Sell-Delivery-Id: 6d0c1c1e-…            ← eindeutig pro Zustellung
X-Set2Sell-Timestamp: 1757577600               ← Unix-Sekunden
X-Set2Sell-Signature: sha256=3f9a…             ← siehe 4.4

Dazu kommen die vom Kunden konfigurierten eigenen Header. Der Body ist ein Umschlag:

{
  "id": "evt_6d0c1c1e-…",
  "event": "deal.stage_changed",
  "created_at": "2026-09-11T08:00:00.000Z",
  "team_id": "3f2c…",
  "data": {
    "deal": {
      "id": "9b7f…",
      "title": "Maria Beispiel",
      "status": "termin",
      "pipeline_id": "8a1e…",
      "stage_id": "c0d2…",
      "value": 2500,
      "contact_name": "Maria Beispiel",
      "first_name": "Maria",
      "last_name": "Beispiel",
      "contact_email": "maria@example.com",
      "contact_phone": "+49 170 1234567",
      "company": "Beispiel GmbH",
      "tags": ["webinar-2026-09"],
      "custom_fields": { "Wunsch-Coaching": "Einzel" },
      "source": "dein-produkt",
      "user_id": "user_…",
      "created_at": "…",
      "updated_at": "…"
    },
    "previous_stage_id": "c0d1…",
    "new_stage_id": "c0d2…"
  }
}

id im Umschlag ist evt_ + Delivery-ID. Bei einem erneuten Zustellversuch bleiben id, Body und Delivery-ID gleich; nur X-Set2Sell-Timestamp und die Signatur werden neu berechnet.

Deal-Zeile (flach) ↔ REST-Deal (verschachtelt):

Die Deal-Zeile ist die vollständige Datenbankzeile. Neue Spalten können jederzeit dazukommen; verlasse dich nur auf die hier genannten Felder und ignoriere unbekannte.

4.4 Signatur prüfen

Signatur = sha256= + Hex(HMAC-SHA256(Secret, <timestamp>.<raw-body>)).

• Raw Body heißt: die Bytes, wie sie ankommen — vor dem JSON-Parsen und ohne Neuformatierung.
• Vergleiche timing-sicher.
• Weise Zustellungen ab, deren Timestamp mehr als 5 Minuten von deiner Uhr abweicht (Replay-Schutz).

Node.js

const crypto = require('crypto')

function verify(secret, headers, rawBody) {
  const ts = headers['x-set2sell-timestamp']
  const sig = headers['x-set2sell-signature'] || ''
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`).digest('hex')
  return expected.length === sig.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))
}

Python

import hmac, hashlib, time

def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    ts = headers.get('X-Set2Sell-Timestamp', '')
    sig = headers.get('X-Set2Sell-Signature', '')
    if abs(time.time() - int(ts or 0)) > 300:
        return False
    expected = 'sha256=' + hmac.new(
        secret.encode(), f'{ts}.'.encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

PHP

function verify(string $secret): bool {
    $ts  = $_SERVER['HTTP_X_SET2SELL_TIMESTAMP'] ?? '';
    $sig = $_SERVER['HTTP_X_SET2SELL_SIGNATURE'] ?? '';
    $body = file_get_contents('php://input');
    if (abs(time() - intval($ts)) > 300) return false;
    $expected = 'sha256=' . hash_hmac('sha256', "{$ts}.{$body}", $secret);
    return hash_equals($expected, $sig);
}

4.5 Zustellung, Wiederholung, Auto-Pause

Gespeichert werden pro Zustellung Antwortstatus, die ersten 4.096 Zeichen des Antwortkörpers, Antwort-Header, Fehlermeldung und Dauer — abrufbar für den Kunden in der Oberfläche und für dich über GET /webhook-subscriptions/{id}/deliveries.

4.6 Empfehlungen für Empfänger

1. Sofort 2xx antworten, dann verarbeiten. Alles, was länger als 10 Sekunden dauert, gilt als Fehlschlag und wird wiederholt.
2. Idempotent verarbeiten. Dedupliziere über X-Set2Sell-Delivery-Id (oder id im Umschlag); Wiederholungen tragen dieselbe ID.
3. Signatur und Timestamp prüfen, nicht die Absender-IP.
4. Unbekannte Felder ignorieren. Payloads wachsen additiv.
5. Pausen überwachen: Poll GET /webhook-subscriptions gelegentlich oder bitte den Kunden, die Pause-Mail zu beachten.

4.7 Zielsystem-Format „Trakyo"

Neben dem Standard-Umschlag gibt es ein festes Sonderformat für die YouTube-Attributions-Plattform Trakyo: flacher Body (trakyo_id, email, name, phone, event_name) nur für appointment.created aus Buchungsseiten und Funnels, ohne Umschlag und ohne Signatur. Das wählt der Kunde beim Anlegen des Abos als „Zielsystem". Andere Partner-spezifische Formate sind auf Anfrage möglich; Standard ist der Umschlag aus 4.3.

---

5. Eingehender Lead-Import-Webhook

Der Lead-Import-Webhook ist der ältere, auf No-Code-Tools zugeschnittene Weg, Leads einzuspielen. Sein Mehrwert gegenüber POST /api/v1/deals: Dublettenerkennung mit Anreicherung, Pipeline und Phase per Name statt UUID, Schreiben von eigenen Feldern und ein Batch-Modus.

Dafür ist die Authentifizierung schwächer (Nutzer-ID statt Secret), das Fehlerformat ein anderes, und aus per Webhook angelegten Deals feuert kein deal.created-Abo. Für neue, produktive Partner-Integrationen empfehlen wir deshalb die REST-API v1; dieser Abschnitt gilt vor allem für Zapier-Catch-Hooks, Make, n8n und Formular-Tools.

5.1 Endpunkt und Header

POST https://cockpit.set2sell.io/api/webhooks/lead-import
Content-Type: application/json
x-user-id: user_…

• x-user-id ist die Nutzer-ID eines Mitglieds des Ziel-Workspace (beginnt mit user_). Der Kunde findet sie unter Einstellungen → Webhooks zusammen mit einem Konfigurations-Generator, der die fertige Zapier-/Make-Konfiguration erzeugt. Fehlt der Header: 401; falsches Format: 403.
• x-webhook-signature (HMAC-SHA256 über den Rohbody, Hex, optional mit Präfix sha256=) ist vorgesehen, aber für Partner nicht erforderlich.
• Rate-Limit: 50 Anfragen pro Minute und Nutzer-ID (ohne Header: pro IP). Bei Überschreitung 429 mit retryAfter in Sekunden.

Ein GET auf denselben Pfad liefert eine maschinenlesbare Selbstbeschreibung (Felder, Formate); mit ?options=true und x-user-id zusätzlich die Pipelines und Phasen des Nutzers samt IDs.

5.2 Einzel-Lead

{
  "title": "Maria Beispiel",
  "pipeline": "Vertrieb",
  "stage": "Neu",
  "first_name": "Maria",
  "last_name": "Beispiel",
  "contact_email": "maria@example.com",
  "contact_phone": "+49 170 1234567",
  "company": "Beispiel GmbH",
  "value": 2500,
  "notes": "Webinar-Anmeldung",
  "source": "dein-produkt",
  "source_id": "lead_48213",
  "tags": ["webinar-2026-09"],
  "custom_fields": { "Wunsch-Coaching": "Einzel" },
  "mode": "enrich"
}

* Fehlen pipeline_id und pipeline, wird die Standard-Pipeline des Nutzers verwendet. Gibt es keine, schlägt der Aufruf mit einer Fehlermeldung fehl.

5.3 Batch (bis 100 Leads)

{
  "default_pipeline_name": "Vertrieb",
  "default_stage_name": "Neu",
  "leads": [
    { "title": "Lead 1", "contact_email": "a@example.com" },
    { "title": "Lead 2", "contact_email": "b@example.com", "stage": "Termin" }
  ]
}

Statt der Namen gehen auch default_pipeline_id / default_stage_id. Jeder Lead darf die Vorgaben mit eigenen pipeline/stage-Angaben überschreiben. Jeder Lead wird einzeln verarbeitet; ein fehlerhafter Lead bricht den Stapel nicht ab.

5.4 Dublettenerkennung und Anreicherung

Vor dem Anlegen wird innerhalb des Workspace nach einem bestehenden Deal gesucht, in dieser Reihenfolge:

1. gleiche E-Mail (normalisiert),
2. sonst gleiche Telefonnummer (normalisiert),
3. sonst gleiche Firma + Kontaktname.

Wird ein Treffer gefunden, wird kein neuer Deal angelegt, sondern der bestehende bearbeitet:

Die Antwort sagt dir, was passiert ist:

{
  "success": true,
  "action": "enriched",
  "deal_id": "9b7f…",
  "message": "Existing deal enriched with 2 new field(s): contact_phone, company",
  "fields_updated": ["contact_phone", "company"]
}

5.5 Antworten

5.6 Was der Lead-Import auslöst und was nicht

• Angelegte Deals starten Automationen des Kunden mit Auslöser „Deal: Neu erstellt" — der einzige Integrationsweg, der das heute tut (Matrix in 2.4).
• Angelegte Deals lösen kein Webhook-Abo deal.created und kein lead.imported aus.
• Im update-Modus lösen Phasenwechsel die Webhook-Abos deal.stage_changed sowie deal.won/deal.lost aus, aber keine Automation „Deal: Stage gewechselt".
• Jeder Aufruf wird serverseitig protokolliert (Status, Dauer, Fehler; Signaturen und Auth-Header geschwärzt). Bei Support-Anfragen hilft deshalb der Zeitstempel des Aufrufs.

---

6. Zapier, Make und n8n

6.1 Zapier-App „Set2Sell Cockpit"

Es gibt eine fertige Zapier-App. Sie ist als private App veröffentlicht, das heißt Kunden erreichen sie über einen Einladungslink, nicht über die Zapier-Suche:

https://zapier.com/developer/public-invite/244466/98564210ea8523c8d3d4a36cb30a2a4a/

Der Kunde findet denselben Link mit einer Schritt-für-Schritt-Anleitung im Cockpit unter Einstellungen → Workspace → Tab „API".

Verbindung: API-Key (s2s_live_…). Die App ruft GET /me als Verbindungstest auf und zeigt den Workspace-Namen als Verbindungsbezeichnung.

Trigger (alle instant, per Webhook-Abo):

Jeder Zap-Datensatz trägt zusätzlich id (Delivery-ID) und event. Die eigenen Felder des Kunden erscheinen bei den Deal-Triggern als custom_fields__<Feldname> (bei „Deal-Phase geändert" als deal__custom_fields__<Feldname>) — im Zap-Editor beschriftet mit dem Feldnamen, auch wenn der Beispiel-Deal keinen Wert trägt.

Aktionen:

Suche:

Die Abos, die Zapier anlegt, erscheinen dem Kunden im Webhook-Tab als „von Zapier verwaltet" und werden beim Ausschalten des Zaps automatisch wieder entfernt.

Beide Aktionen laufen über die REST-API. Damit gilt auch hier: Ein per Zap angelegter oder verschobener Deal startet derzeit keine Automation des Kunden (Matrix in 2.4). Wer das braucht, nutzt für das Anlegen „Webhooks by Zapier → POST" auf den Lead-Import-Webhook (Abschnitt 5).

Lücke, die du kennen solltest: Es gibt in der Zapier-App keinen Trigger für deal.created. Wer auf jeden neuen Deal reagieren will, legt im Cockpit ein Webhook-Abo auf deal.created an und nutzt in Zapier „Webhooks by Zapier → Catch Hook".

6.2 Make (ehemals Integromat) und n8n

Für beide gibt es keine eigene App. Sie arbeiten über ihre generischen Module:

• Leads anlegen / Deals lesen: HTTP-Modul gegen https://cockpit.set2sell.io/api/v1/… mit Header Authorization: Bearer s2s_live_… (Abschnitt 3).
• Auf Ereignisse reagieren: „Custom Webhook" (Make) bzw. „Webhook"-Node (n8n) als Ziel-URL eines Webhook-Abos eintragen (Abschnitt 4). Die Signaturprüfung ist dort optional; das Secret kann aber als zweiter Faktor über einen eigenen Header mitgegeben werden (Kunde trägt beim Abo einen eigenen Header ein, das Szenario prüft ihn).
• Alternativ ohne API-Key: Lead-Import-Webhook (Abschnitt 5) mit x-user-id.

---

7. KI-Anbindung per MCP

Set2Sell stellt einen MCP-Server (Model Context Protocol) bereit. Damit kann ein KI-Assistent des Kunden — etwa Claude im Web, als Desktop-App oder in Claude Code, aber auch jeder andere MCP-Client mit OAuth-Unterstützung — das CRM des Nutzers direkt bedienen: Deals suchen und anlegen, Termine buchen, Terminarten pflegen, Funnels bauen und veröffentlichen, Leads importieren.

7.1 Verbindung

Ein Aufruf ohne Token liefert 401 mit WWW-Authenticate: Bearer … resource_metadata="…/.well-known/oauth-protected-resource/mcp" — MCP-Clients starten daraus automatisch den Anmeldefluss. Der Kunde findet die Anleitung im Cockpit unter Profil → Tab „KI-Anbindung (MCP)".

7.2 Werkzeuge (77)

Jedes Werkzeug nimmt eine workspace_id entgegen; bei Mehrdeutigkeit ruft der Client zuerst list_workspaces auf. Schreibende Werkzeuge protokollieren in der Zeitleiste des Deals. Phasenwechsel über move_deal (oder update_deal mit stage_id) lösen deal.stage_changed sowie deal.won / deal.lost aus — und wie ein Phasenwechsel im Deal-Drawer die Zuweisungsregel der Zielphase, die Team-Benachrichtigung, phasengesteuerte Sequenzen und Automationen (siehe 2.4); create_deal über MCP löst derzeit kein deal.created aus (siehe Hinweise in 4.2).

7.3 Abgrenzung zur REST-API

Wenn dein Produkt selbst ein KI-Agent ist, der im Namen eines Nutzers arbeitet, ist MCP der richtige Weg. Für Server-zu-Server-Integrationen bleibt es die REST-API.

---

8. Einbettungen

Diese Punkte betreffen weniger Partner-Backends als Website-Baukästen und Agenturen, die Cockpit-Elemente in Kundenseiten einbauen.

8.1 Buchungsseite

Jede Buchung erzeugt einen Termin und, sofern noch keiner existiert, einen Deal, und löst appointment.created aus.

8.2 Formulare

<script src="https://cockpit.set2sell.io/embed.js" data-form="<slug>" defer></script>

Das Script rendert das Formular an Ort und Stelle in einem iframe, passt die Höhe automatisch an und löst nach dem Absenden auf der Elternseite ein DOM-Ereignis aus:

document.addEventListener('set2sell-form:complete', (e) => {
  console.log(e.detail.submission_id)
})

Optionale Attribute am Script-Tag: data-min-height="<px>" (Starthöhe, Standard 400) und data-host="<url>", falls das Formular unter einer eigenen Domain läuft. Mehrere Formulare auf einer Seite sind möglich.

Alternativ direkt als iframe: https://cockpit.set2sell.io/form/<slug>/embed.

8.3 Funnels

Veröffentlichte Funnels laufen unter https://cockpit.set2sell.io/f/<slug> oder der eigenen Domain des Kunden. Formular-Abschlüsse lösen funnel.submission_completed, Buchungen appointment.created aus. Beide tragen Attribution (UTM, fbclid, gclid, Landing-URL), soweit vom Besucher mitgebracht.

---

9. Partner-Onboarding

9.1 So läuft eine Partnerschaft typischerweise

1. Kontakt an info@set2sell.io mit kurzer Beschreibung: Was macht euer Produkt, welche Richtung (Daten rein, Daten raus, beides), welche Ereignisse braucht ihr.
2. Test-Workspace. Wir legen einen Workspace für euch an, in dem ihr Admin seid: API-Keys, Webhook-Abos, Pipelines, Testdaten — alles selbst steuerbar.
3. Bauen gegen die Produktionsumgebung mit dem Test-Workspace.
4. Abnahme: Wir prüfen gemeinsam Signaturprüfung, Idempotenz, Fehlerbehandlung und Rate-Limit-Verhalten.
5. Listung. Auf Wunsch nehmen wir euch in die Integrationsübersicht im Cockpit auf und stellen eine Kundenanleitung bereit.

9.2 Checkliste vor dem Go-live

REST-API

• Key wird verschlüsselt gespeichert und nie geloggt.
• 401 führt zu einer klaren Meldung an den Kunden („Key widerrufen? Neuen Key eintragen").
• 429 wird mit Retry-After respektiert, nicht sofort wiederholt.
• 422-Meldungen (error.message) werden dem Kunden oder eurem Support sichtbar gemacht.
• source ist auf euren Produktnamen gesetzt.
• Keine Duplikate durch Retries (eigene Deduplizierung oder GET /deals?search=).
• status wird nie gesendet; Phasenwechsel über stage_id.

Webhooks

• Signatur und Timestamp werden geprüft.
• Antwort 2xx innerhalb weniger Sekunden, Verarbeitung asynchron.
• Dedup über Delivery-ID.
• Unbekannte Felder werden ignoriert.
• Umgang mit pausierten Abos (Poll oder Kundenhinweis).

Lead-Import-Webhook (falls genutzt)

• Nutzer-ID wird als Konfigurationswert vom Kunden abgefragt, nicht erraten.
• action: "enriched" wird korrekt als „Dublette, vorhandener Deal" behandelt.
• Batch-results werden je Lead ausgewertet.

9.3 Support

• Technische Fragen und Test-Workspace: info@set2sell.io
• Fehlerberichte bitte mit Zeitstempel (UTC), Workspace-ID (aus GET /me), Delivery-ID (bei Webhooks) oder Request-Body (bei API-Fehlern, ohne Key).

---

10. Änderungspolitik

• Additive Änderungen ohne Ankündigung: neue Felder in Antworten und Payloads, neue Ereignisse, neue Endpunkte, neue MCP-Werkzeuge. Integrationen müssen unbekannte Felder ignorieren.
• Nicht ohne neue Version: Entfernen oder Umbenennen von Feldern, Ändern von Typen oder Semantik bestehender Endpunkte, Ändern des Signaturverfahrens. Solche Änderungen erscheinen als v2 neben v1; v1 bleibt mindestens 12 Monate nach Ankündigung erreichbar.
• Strenge Eingabeprüfung: Weil unbekannte Felder mit 422 abgelehnt werden, ändert sich das Verhalten bestehender Anfragen nicht, wenn wir neue Felder einführen — sie werden erst gültig, wenn ihr sie bewusst sendet.
• Vertragsänderung 29.10.2026: GET /appointments liefert next_cursor als undurchsichtige Zeichenkette statt als Termin-ID (Details unter „Termine buchen“ in 3.3a). Alte ID-Cursor werden weiter angenommen; wer next_cursor als ID ausgewertet hat, muss es unverändert zurückgeben.
• Ankündigungen gehen per E-Mail an die bei uns hinterlegte technische Kontaktadresse des Partners.

---

11. Anhang

11.1 Status-Werte

Der Status ist immer aus dem mapped_status der aktuellen Phase abgeleitet.

11.2 Feld-Limits der REST-API

11.3 Typen eigener Felder

text, number, select, multiselect, boolean, date, email, phone, url

11.4 Alle Webhook-Ereignisse

deal.created, deal.updated, deal.stage_changed, deal.won, deal.lost, deal.deleted, appointment.created, appointment.cancelled, appointment.rescheduled, task.created, task.completed, call.completed, lead.imported, note.created, funnel.submission_completed, webhook.test

11.5 Glossar Deutsch ↔ API