{ "openapi": "3.1.2", "info": { "title": "Rootware Communication API", "version": "1.0.0", "description": "\u00d6ffentliche REST-API der Rootware Communication Platform. Authentifizierung mit dem Token eines Service Accounts als Bearer-Token." }, "servers": [ { "url": "\/api\/v1" } ], "security": [ { "oauth2": [] }, { "http": [] } ], "paths": { "\/attachments": { "post": { "operationId": "attachment.store", "description": "Legt die Datei (`multipart\/form-data`, Feld `file`) im Objektspeicher ab und liefert den Anhang (`201`). Seine\n`id` (`att_\u2026`) wird beim Senden einer Nachricht angegeben. Gr\u00f6\u00dfe und erlaubte Typen sind je Tenant begrenzt (`422`).\nJede Datei wird vor dem Ablegen auf Schadsoftware gepr\u00fcft: ein Fund wird abgewiesen (`422`), ist die Pr\u00fcfung vor\u00fcbergehend\nnicht m\u00f6glich, antwortet die API mit `503` und `Retry-After` \u2014 dann den Upload sp\u00e4ter wiederholen.", "summary": "Datei hochladen", "tags": [ "Attachment" ], "requestBody": { "required": true, "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/UploadAttachmentRequest" } } } }, "responses": { "201": { "description": "`AttachmentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AttachmentResource" } }, "required": [ "data" ] } } } }, "503": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Die Virenpr\u00fcfung ist vor\u00fcbergehend nicht verf\u00fcgbar." ] } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/attachments\/{attachment}": { "get": { "operationId": "attachment.show", "description": "Liefert die Angaben zum Anhang und in `download` einen signierten Link (`url`), der zum Zeitpunkt\n`expires_at` abl\u00e4uft. Eine geleerte oder als befallen erkannte Datei ist nicht abrufbar (`404`).", "summary": "Anhang abrufen", "tags": [ "Attachment" ], "parameters": [ { "name": "attachment", "in": "path", "required": true, "description": "The attachment ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`AttachmentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AttachmentResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/campaigns": { "get": { "operationId": "campaign.index", "description": "Filter: `status` (`draft`, `scheduled`, `running`, `paused`, `completed`, `cancelled`); Sortierung: `created_at`.", "summary": "Kampagnen auflisten", "tags": [ "Campaign" ], "parameters": [ { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `created_at`. Vorgabe: `-created_at`.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "description": "Nur diesen Status. Kommaliste: eines von.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "next_cursor", "prev_cursor" ] } }, "required": [ "data", "meta" ] } } } } } }, "post": { "operationId": "campaign.store", "description": "Legt einen Entwurf an (`201`). `template` ist der Schl\u00fcssel eines Templates mit dem Zweck `marketing`, mit ver\u00f6ffentlichter\nVersion und E-Mail-Variante. `segment` filtert die Kontakte: `countries` (ISO-L\u00e4nder), `locales` und `tags` (Kontakt tr\u00e4gt\nmindestens eines in `metadata.tags`); ohne Angabe geh\u00f6ren alle Kontakte mit g\u00fcltiger E-Mail-Adresse dazu. `variables` sind\nfeste Werte f\u00fcr das Template. Versendet wird nur an Kontakte mit g\u00fcltiger Marketing-Einwilligung; den Abmeldelink tr\u00e4gt\njede Mail. Fehler (`422`): Template nicht sendbar, ung\u00fcltiges Segment.", "summary": "Kampagne anlegen", "tags": [ "Campaign" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateCampaignRequest" } } } }, "responses": { "201": { "description": "`CampaignResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CampaignResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/campaigns\/{campaign}": { "get": { "operationId": "campaign.show", "summary": "Kampagne abrufen", "tags": [ "Campaign" ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "description": "The campaign ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`CampaignResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CampaignResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/campaigns\/{campaign}\/report": { "get": { "operationId": "campaign.report", "description": "Zielgruppe (`audience_total`), angelegte Nachrichten (`messages`), die Z\u00e4hler des Versands (`sent`, `skipped` je Grund) und\nje Ereignisart aus dem Verlauf die Zahl der Nachrichten (`events`: `sent`, `delivered`, `opened`, `clicked`, `bounced`,\n`soft_bounced`, `complained`, `unsubscribed`, `failed`, `cancelled`).", "summary": "Bericht einer Kampagne", "tags": [ "Campaign" ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "description": "The campaign ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "audience_total": { "type": [ "integer", "null" ] }, "messages": { "type": "integer", "minimum": 0 }, "sent": { "type": "integer" }, "skipped": { "type": "array", "items": {} }, "events": { "type": "string" } }, "required": [ "audience_total", "messages", "sent", "skipped", "events" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/campaigns\/{campaign}\/schedule": { "post": { "operationId": "campaign.schedule", "description": "Setzt den Start auf `scheduled_at` (in der Zukunft); die Kampagne ist dann `scheduled`. Ein Entwurf oder eine bereits\ngeplante Kampagne l\u00e4sst sich (neu) planen, sonst `409 campaign_not_schedulable`.", "summary": "Start planen", "tags": [ "Campaign" ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "description": "The campaign ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ScheduleCampaignRequest" } } } }, "responses": { "200": { "description": "`CampaignResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CampaignResource" } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Planen nicht m\u00f6glich" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/campaigns\/{campaign}\/start": { "post": { "operationId": "campaign.start", "description": "Startet einen Entwurf, eine geplante oder eine angehaltene Kampagne (`202`): die Zielgruppe wird gez\u00e4hlt, der Versand l\u00e4uft\nin gedrosselten Stapeln. Eine angehaltene Kampagne (`status_reason` nennt den Grund, etwa `daily_cost_limit`) setzt so fort.\nSonst `409 campaign_not_startable`.", "summary": "Kampagne starten", "tags": [ "Campaign" ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "description": "The campaign ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "`CampaignResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CampaignResource" } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Start nicht m\u00f6glich" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/campaigns\/{campaign}\/cancel": { "post": { "operationId": "campaign.cancel", "description": "Es l\u00e4uft kein weiterer Stapel, noch nicht versendete Nachrichten der Kampagne werden storniert. Eine abgeschlossene oder\nabgebrochene Kampagne antwortet `409 campaign_not_cancellable`.", "summary": "Kampagne abbrechen", "tags": [ "Campaign" ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "description": "The campaign ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`CampaignResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CampaignResource" } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Abbruch nicht m\u00f6glich" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/customers\/{customer}\/conversations": { "get": { "operationId": "conversation.forCustomer", "summary": "Conversations eines Kunden", "tags": [ "Conversation" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `created_at`, `updated_at`. Vorgabe: `-created_at`.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "description": "Nur diesen Status. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[channel]", "in": "query", "description": "Nur Conversations mit diesem Kanal. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[assigned]", "in": "query", "description": "Zugewiesener Benutzer (Id) oder `none` f\u00fcr unzugewiesene. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[reference]", "in": "query", "description": "Gesch\u00e4ftsreferenz als `:`, ohne Typ jede Referenz mit dieser Kennung (zum Beispiel `order:A12345`).", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "`last_message` f\u00fcgt die letzte Nachricht hinzu.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "next_cursor", "prev_cursor" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/conversations": { "get": { "operationId": "conversation.index", "description": "Filter: `status`, `channel`, `assigned` (Benutzer-Id oder `none`), `reference` (`order:A12345`); Sortierung:\n`created_at`, `updated_at`; `include=last_message` f\u00fcgt die letzte Nachricht hinzu.", "summary": "Conversations auflisten", "tags": [ "Conversation" ], "parameters": [ { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `created_at`, `updated_at`. Vorgabe: `-created_at`.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "description": "Nur diesen Status. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[channel]", "in": "query", "description": "Nur Conversations mit diesem Kanal. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[assigned]", "in": "query", "description": "Zugewiesener Benutzer (Id) oder `none` f\u00fcr unzugewiesene. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[reference]", "in": "query", "description": "Gesch\u00e4ftsreferenz als `:`, ohne Typ jede Referenz mit dieser Kennung (zum Beispiel `order:A12345`).", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "`last_message` f\u00fcgt die letzte Nachricht hinzu.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "next_cursor", "prev_cursor" ] } }, "required": [ "data", "meta" ] } } } } } } }, "\/conversations\/{conversation}": { "get": { "operationId": "conversation.show", "summary": "Conversation abrufen", "tags": [ "Conversation" ], "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "The conversation ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`ConversationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ConversationResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } }, "patch": { "operationId": "conversation.update", "description": "\u00c4ndert Status (`open`, `pending`, `snoozed`, `closed`), Zuweisung (`assigned_to`: Benutzer-Id oder `null`), Betreff und\nPriorit\u00e4t. `snoozed` braucht `snoozed_until`.", "summary": "Conversation \u00e4ndern", "tags": [ "Conversation" ], "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "The conversation ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PatchConversationRequest" } } } }, "responses": { "200": { "description": "`ConversationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ConversationResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/conversations\/{conversation}\/messages": { "get": { "operationId": "conversation.messages", "summary": "Timeline einer Conversation, die \u00e4lteste Nachricht zuerst", "tags": [ "Conversation" ], "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "The conversation ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `created_at`. Vorgabe: `created_at`.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "description": "Nur diesen Status. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[channel]", "in": "query", "description": "Nur diesen Kanal. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[direction]", "in": "query", "description": "Nur diese Richtung. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[client_reference]", "in": "query", "description": "Nur diese `client_reference` der Anfrage. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[customer_id]", "in": "query", "description": "Nur Nachrichten dieser Kunden, nach externer Kundennummer. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[created_at][gt]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: gr\u00f6\u00dfer als, ISO 8601.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[created_at][gte]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: ab (einschlie\u00dflich), ISO 8601.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[created_at][lt]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: kleiner als, ISO 8601.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[created_at][lte]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: bis (einschlie\u00dflich), ISO 8601.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } }, "post": { "operationId": "conversation.reply", "description": "Sendet eine Nachricht an den Kunden der Conversation (`202`). Ohne `channel` bleibt sie auf dem Kanal der letzten\nNachricht; Fehler wie bei `POST \/messages`.", "summary": "Antwort in einer Conversation", "tags": [ "Conversation" ], "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "The conversation ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ReplyMessageRequest" } } } }, "responses": { "202": { "description": "`MessageResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/customers": { "post": { "operationId": "customer.upsert", "description": "Legt den Kunden zur `customer_id` an (`201`) oder aktualisiert ihn (`200`). Derselbe Aufruf\nwiederholt \u00e4ndert nichts. Identities werden hinzugef\u00fcgt oder aktualisiert, nie entfernt.", "summary": "Kunden anlegen oder aktualisieren", "tags": [ "Customer" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpsertCustomerRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "get": { "operationId": "customer.index", "description": "Filter: `customer_id`, `identity`, `status`, `updated_since`; Sortierung: `created_at`, `updated_at`.", "summary": "Kunden auflisten", "tags": [ "Customer" ], "parameters": [ { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `created_at`, `updated_at`. Vorgabe: `-created_at`.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "description": "Nur diesen Status. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[customer_id]", "in": "query", "description": "Externe Kundennummer. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[identity]", "in": "query", "description": "E-Mail-Adresse oder Telefonnummer, in jeder Schreibweise. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[updated_since]", "in": "query", "description": "Nur Kunden, die seit diesem Zeitpunkt ge\u00e4ndert wurden (ISO 8601).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "next_cursor", "prev_cursor" ] } }, "required": [ "data", "meta" ] } } } } } } }, "\/customers\/{customer}": { "get": { "operationId": "customer.show", "summary": "Kunden abrufen", "tags": [ "Customer" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`CustomerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } }, "patch": { "operationId": "customer.update", "summary": "Stammdaten eines Kunden \u00e4ndern", "tags": [ "Customer" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PatchCustomerRequest" } } } }, "responses": { "200": { "description": "`CustomerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "customer.destroy", "description": "L\u00f6scht die personenbezogenen Daten des Kunden (Recht auf L\u00f6schung): Identities, Einwilligungen, externe\nKennung, Name und Metadaten sowie Inhalte, Anh\u00e4nge und Adressen seiner Nachrichten. Der Kunde bleibt mit\nStatus `erased` bestehen, Sperreintr\u00e4ge bleiben als Hash, der Verbrauch bleibt. Die L\u00f6schung l\u00e4uft\nasynchron (`202`); das Ereignis `customer.updated` mit Status `erased` meldet ihr Ende. Eine Wiederholung ist unsch\u00e4dlich.\nDie Antwort zeigt den Kunden, wie er vor der L\u00f6schung war.", "summary": "Kunden l\u00f6schen", "tags": [ "Customer" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "`CustomerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/customers\/{customer}\/identities": { "put": { "operationId": "customer.replaceIdentities", "description": "Ersetzt alle Identities durch die \u00fcbergebene Liste: Vorhandene (`type` + Wert) werden aktualisiert,\nalle anderen entfernt. Je Typ gibt es genau eine prim\u00e4re Identity. Eine ung\u00fcltige Identity bricht\nden ganzen Aufruf ab (`422`).", "summary": "Identities eines Kunden ersetzen", "tags": [ "Customer" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ReplaceIdentitiesRequest" } } } }, "responses": { "200": { "description": "`CustomerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } }, "post": { "operationId": "customer.addIdentity", "description": "Legt die Identity an (`201`) oder aktualisiert die vorhandene mit gleichem Typ und Wert (`200`).\nAls `is_primary` markiert, l\u00f6st sie die bisherige prim\u00e4re Identity des Typs ab; die erste Identity\neines Typs ist immer prim\u00e4r.", "summary": "Identity hinzuf\u00fcgen", "tags": [ "Customer" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/AddIdentityRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/customers\/{customer}\/identities\/{identity}": { "delete": { "operationId": "customer.removeIdentity", "description": "War sie die prim\u00e4re ihres Typs, wird die \u00e4lteste verbliebene Identity des Typs prim\u00e4r.", "summary": "Identity entfernen", "tags": [ "Customer" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "identity", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/customers\/{customer}\/consents": { "put": { "operationId": "customer.setConsents", "description": "H\u00e4lt jede \u00fcbergebene Einwilligung oder jeden Widerruf (`status`) je Kanal, Zweck und optional\nIdentity in der Historie fest; nicht genannte bleiben unber\u00fchrt, ein unver\u00e4nderter Stand legt nichts\nNeues an. `channel` leer gilt f\u00fcr alle Kan\u00e4le, `identity_id` leer f\u00fcr alle Identities. Die Antwort\nist der Kunde mit dem aktuellen Stand je Geltungsbereich.", "summary": "Einwilligungen setzen", "tags": [ "Customer" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SetConsentsRequest" } } } }, "responses": { "200": { "description": "`CustomerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/customers\/{customer}\/merge": { "post": { "operationId": "customer.merge", "description": "F\u00fchrt den Kunden `source` (`cus_\u2026` oder `customer_id`) in diesen Kunden \u00fcber: Identities, externe\nKennungen, Einwilligungen, Conversations und Nachrichten geh\u00f6ren danach diesem Kunden. Die Quelle\nbleibt mit Status `merged` und `merged_into` bestehen; ein Widerruf einer der beiden Seiten gilt\nweiter. L\u00f6st das Ereignis `customer.merged` aus. Beide m\u00fcssen `active` oder `unresolved` sein (`422`),\nein unbekannter oder fremder Kunde antwortet `404`. Die Antwort ist der \u00fcberlebende Kunde.", "summary": "Kunden zusammenf\u00fchren", "tags": [ "Customer" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MergeCustomerRequest" } } } }, "responses": { "200": { "description": "`CustomerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/customers\/{customer}\/export": { "get": { "operationId": "customer.export", "description": "Startet die Auskunft (Recht auf Auskunft): ein ZIP mit allen Daten des Kunden \u2014 Stammdaten, Identities,\nEinwilligungen, Conversations, Nachrichten samt Inhalt und Anh\u00e4ngen. Der Export l\u00e4uft asynchron (`202`); das\nEreignis `export.ready` meldet das fertige Paket mit einem signierten Download-Link (Vorgabe: 24 Stunden g\u00fcltig).\nEin gel\u00f6schter Kunde hat nichts mehr auszugeben (`422`).", "summary": "Daten eines Kunden exportieren", "tags": [ "Customer" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "The customer ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "`ContactExportResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ContactExportResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/customer-resolver": { "get": { "operationId": "customerResolver.show", "description": "Liefert die Konfiguration des Tenants, nie das Secret. Antwortet `404 not_found`, wenn keiner eingerichtet ist.", "summary": "Customer Resolver abrufen", "tags": [ "CustomerResolver" ], "responses": { "200": { "description": "`CustomerResolverResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResolverResource" } }, "required": [ "data" ] } } } }, "404": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Nicht gefunden" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 404 }, {} ] }, "code": { "anyOf": [ { "type": "string", "const": "not_found" }, {} ] }, "detail": { "anyOf": [ { "type": "string", "const": "F\u00fcr diesen Tenant ist kein Customer Resolver eingerichtet." }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } } } }, "put": { "operationId": "customerResolver.save", "description": "Legt die Konfiguration an (`201`) oder \u00e4ndert die vorhandene (`200`). Beim Anlegen sind `url` und `identity_types` n\u00f6tig;\n`url` muss `https:\/\/` auf Port 443 und \u00f6ffentlich erreichbar sein (keine privaten, Loopback- oder Link-Local-Adressen, keine\nZugangsdaten in der URL). `timeout_seconds` liegt zwischen 1 und dem H\u00f6chstwert der Plattform (Vorgabe 3 s, h\u00f6chstens\n10 s), `identity_types` nennt die Identity-Typen, f\u00fcr die der Resolver gefragt wird, `enabled` schaltet ihn ein oder aus.\nBeim \u00c4ndern \u00e4ndern sich nur die genannten Felder. Die Antwort auf das Anlegen enth\u00e4lt **einmalig** das `secret`\n(`whsec_\u2026`), mit dem die Signatur der Aufrufe gepr\u00fcft wird; ein neues gibt es nur durch L\u00f6schen und erneutes Anlegen.", "summary": "Customer Resolver anlegen oder \u00e4ndern", "tags": [ "CustomerResolver" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveCustomerResolverRequest" } } } }, "responses": { "201": { "description": "`CustomerResolverResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResolverResource" } }, "required": [ "data" ] } } } }, "200": { "description": "`CustomerResolverResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CustomerResolverResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "customerResolver.destroy", "description": "Entfernt die Konfiguration samt Secret (`204`); danach wird kein Resolver mehr aufgerufen. Antwortet `404 not_found`,\nwenn keiner eingerichtet ist.", "summary": "Customer Resolver l\u00f6schen", "tags": [ "CustomerResolver" ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Nicht gefunden" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 404 }, {} ] }, "code": { "anyOf": [ { "type": "string", "const": "not_found" }, {} ] }, "detail": { "anyOf": [ { "type": "string", "const": "F\u00fcr diesen Tenant ist kein Customer Resolver eingerichtet." }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } } } } }, "\/events": { "post": { "operationId": "event.store", "description": "Nimmt ein Gesch\u00e4ftsereignis des Kundensystems an (`202`); die Regeln des Mandanten entscheiden danach, ob und wie\nkommuniziert wird. `event` ist der Schl\u00fcssel eines Ereignistyps des Mandanten, `customer_id` der Kunde (`cus_\u2026` oder\ndie externe Kundennummer), `data` die Nutzlast \u2014 sie muss zum Schema des Ereignistyps passen. Mit `Idempotency-Key`\nf\u00fchrt eine Wiederholung nicht zu einem zweiten Ereignis. Fehler (`422`): `unknown_event_type`, `event_type_inactive`,\n`customer_not_found`, `invalid_event_data`.", "summary": "Ereignis melden", "tags": [ "Event" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreEventRequest" } } } }, "responses": { "202": { "description": "`BusinessEventResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BusinessEventResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/events\/{event}": { "get": { "operationId": "event.show", "description": "Zeigt das Ereignis, die Regel, nach der es l\u00e4uft (`rule`), und je Schritt der Regel einen Versuch (`attempts`): Kanal,\nAusgang (`sent`, `skipped`, `failed`, `timed_out`, `succeeded`), Grund (z. B. `no_consent`, `not_read_in_time`) und\ndie Nachricht (`message_id`). So ist nachvollziehbar, warum ein Kanal gew\u00e4hlt oder \u00fcbersprungen wurde. Ohne passende\nRegel (`no_route`) bleiben `rule` leer und `attempts` eine leere Liste. Ereignisse anderer Mandanten gibt es nicht (`404`).", "summary": "Ereignis mit Dispatch-Verlauf abrufen", "tags": [ "Event" ], "parameters": [ { "name": "event", "in": "path", "required": true, "description": "The event ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`BusinessEventResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BusinessEventResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/messages": { "post": { "operationId": "message.store", "description": "Nimmt eine direkte Nachricht an (`202`) und reiht sie zum Versand ein; der Status steht sp\u00e4ter unter\n`GET \/messages\/{id}`. `channel` ist `email`, `sms`, `whatsapp`, `rcs`, `postal` oder `auto` \u2014 dann w\u00e4hlt die\nPlattform den ersten Kanal nach der Vorgabe des Tenants, den der Kunde erreichen darf. Fehler (`422`):\n`customer_not_found`, `no_reachable_identity`, `consent_missing`, `channel_not_configured`, `attachment_not_allowed`.", "summary": "Nachricht senden", "tags": [ "Message" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SendMessageRequest" } } } }, "responses": { "202": { "description": "`MessageResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "get": { "operationId": "message.index", "description": "Filter: `status`, `channel`, `direction`, `customer_id`, `client_reference`, `created_at` (Bereich); Sortierung: `created_at`.", "summary": "Nachrichten auflisten", "tags": [ "Message" ], "parameters": [ { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `created_at`. Vorgabe: `-created_at`.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "description": "Nur diesen Status. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[channel]", "in": "query", "description": "Nur diesen Kanal. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[direction]", "in": "query", "description": "Nur diese Richtung. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[client_reference]", "in": "query", "description": "Nur diese `client_reference` der Anfrage. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[customer_id]", "in": "query", "description": "Nur Nachrichten dieser Kunden, nach externer Kundennummer. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[created_at][gt]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: gr\u00f6\u00dfer als, ISO 8601.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[created_at][gte]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: ab (einschlie\u00dflich), ISO 8601.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[created_at][lt]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: kleiner als, ISO 8601.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[created_at][lte]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: bis (einschlie\u00dflich), ISO 8601.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "\/messages\/{message}": { "get": { "operationId": "message.show", "summary": "Nachricht abrufen", "tags": [ "Message" ], "parameters": [ { "name": "message", "in": "path", "required": true, "description": "The message ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`MessageResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/messages\/{message}\/events": { "get": { "operationId": "message.events", "summary": "Statusverlauf einer Nachricht", "tags": [ "Message" ], "parameters": [ { "name": "message", "in": "path", "required": true, "description": "The message ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `occurred_at`, `created_at`. Vorgabe: `occurred_at`.", "schema": { "type": "string" } }, { "name": "filter[type]", "in": "query", "description": "Nur diesen Ereignistyp. Kommaliste: eines von.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "next_cursor", "prev_cursor" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/messages\/{message}\/cancel": { "post": { "operationId": "message.cancel", "description": "Storniert eine geplante oder wartende Nachricht. Ist sie schon beim Provider, antwortet die Plattform mit\n`409 message_not_cancellable`.", "summary": "Nachricht stornieren", "tags": [ "Message" ], "parameters": [ { "name": "message", "in": "path", "required": true, "description": "The message ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Nachricht nicht stornierbar" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string", "const": "message_not_cancellable" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "200": { "description": "`MessageResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/oauth\/token": { "post": { "operationId": "oauthToken.store", "description": "Tauscht Client-ID und Secret eines OAuth2-Clients gegen einen kurzlebigen Bearer-Token des zugeh\u00f6rigen Service Accounts\n(RFC 6749, 4.4). Der Aufruf ist ein Formular (`application\/x-www-form-urlencoded`, JSON wird ebenfalls angenommen) mit `grant_type=client_credentials`,\n`client_id` und `client_secret`; Client-ID und Secret d\u00fcrfen stattdessen per HTTP Basic im Kopf stehen. `scope` nennt die\ngew\u00fcnschten Abilities durch Leerzeichen getrennt (Vorgabe: alle Abilities des Clients; mehr als der Client darf, lehnt\n`invalid_scope` ab). Der Token gilt `expires_in` Sekunden und unterliegt wie ein API-Token der IP-Allowlist des\nService Accounts. Fehler antworten als Problem-JSON und tragen zus\u00e4tzlich den OAuth2-Fehlercode in `error`\n(`invalid_request`, `invalid_client`, `invalid_scope`, `unsupported_grant_type`, `access_denied`).", "summary": "Zugriffstoken holen (OAuth2 Client Credentials)", "tags": [ "OauthToken" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/OauthTokenRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [] } }, "\/templates": { "get": { "operationId": "template.index", "description": "Filter: `purpose` (`transactional`, `service`, `marketing`, `layout`), `key`; Sortierung: `key`, `name`,\n`created_at`. `published_version` nennt die Nummer der g\u00fcltigen Version.", "summary": "Templates auflisten", "tags": [ "Template" ], "parameters": [ { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `key`, `name`, `created_at`. Vorgabe: `key`.", "schema": { "type": "string" } }, { "name": "filter[purpose]", "in": "query", "description": "Nur diesen Zweck, `layout` listet die Layouts. Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[key]", "in": "query", "description": "Nur diesen Template-Schl\u00fcssel. Kommaliste: eines von.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "next_cursor", "prev_cursor" ] } }, "required": [ "data", "meta" ] } } } } } }, "post": { "operationId": "template.store", "description": "Legt das Template ohne Inhalt an (`201`); den Inhalt bringt `POST \/templates\/{key}\/versions`. Der `key` ist je\nTenant eindeutig (`422`). Zweck `layout` kennzeichnet ein Layout, in das E-Mails eingesetzt werden.", "summary": "Template anlegen", "tags": [ "Template" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateTemplateRequest" } } } }, "responses": { "201": { "description": "`TemplateResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TemplateResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/templates\/{template}": { "get": { "operationId": "template.show", "summary": "Template mit seinen Versionen abrufen", "tags": [ "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "The template key", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`TemplateResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/TemplateResource" }, { "type": "object", "required": [ "versions" ] } ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/templates\/{template}\/versions": { "post": { "operationId": "template.storeVersion", "description": "Legt einen Entwurf an, mit `publish: true` sofort ver\u00f6ffentlicht. Betreff und Text sind Pflicht (au\u00dfer im Layout),\nMustache-Variablen m\u00fcssen in `variables` deklariert sein; HTML maskiert jeden Wert. Mit `layout` (Schl\u00fcssel eines\nLayouts) wird dessen aktuell ver\u00f6ffentlichte Version festgeschrieben.", "summary": "Version anlegen", "tags": [ "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "The template key", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateVersionRequest" } } } }, "responses": { "201": { "description": "`TemplateVersionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TemplateVersionResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/templates\/{template}\/versions\/{version}": { "get": { "operationId": "template.showVersion", "summary": "Version abrufen", "tags": [ "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "The template key", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`TemplateVersionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TemplateVersionResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } }, "put": { "operationId": "template.updateVersion", "description": "Ersetzt den Inhalt eines Entwurfs. Eine ver\u00f6ffentlichte Version ist unver\u00e4nderlich (`409 template_version_immutable`).", "summary": "Entwurf ersetzen", "tags": [ "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "The template key", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateVersionRequest" } } } }, "responses": { "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Vorgang nicht m\u00f6glich" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "200": { "description": "`TemplateVersionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TemplateVersionResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/templates\/{template}\/versions\/{version}\/publish": { "post": { "operationId": "template.publishVersion", "description": "Macht den Entwurf zur g\u00fcltigen, unver\u00e4nderlichen Version; die bisherige wird archiviert.", "summary": "Version ver\u00f6ffentlichen", "tags": [ "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "The template key", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Vorgang nicht m\u00f6glich" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "200": { "description": "`TemplateVersionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TemplateVersionResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/templates\/{template}\/versions\/{version}\/submit": { "post": { "operationId": "template.submitVersion", "description": "Reicht die WhatsApp-Varianten einer ver\u00f6ffentlichten Version bei Meta zur Pr\u00fcfung ein (je Sprache und WABA des\nTenants; Name beim Provider `_v`). Wiederholbar: Eingereichtes wird \u00fcbersprungen. Der Status\n(`provider_templates`) kommt danach per Webhook und st\u00fcndlichem Abgleich; \u00e4ndert Meta Status oder Kategorie, geht\n`template.status_changed` an die Tenant-Webhooks. Ohne ver\u00f6ffentlichte Version `409 template_version_not_published`,\nohne verbundenes Konto `409 whatsapp_account_missing`, bei einer Ablehnung durch Meta `502 whatsapp_submission_failed`.", "summary": "Bei WhatsApp einreichen", "tags": [ "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "The template key", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Vorgang nicht m\u00f6glich" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "200": { "description": "`TemplateVersionResource`", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/TemplateVersionResource" } }, "required": [ "data" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/templates\/{template}\/preview": { "post": { "operationId": "template.preview", "description": "Rendert eine Variante (Vorgabe: E-Mail, Sprache `de`, die ver\u00f6ffentlichte Version; mit `version` auch ein\nEntwurf). Ohne `variables` gelten die Beispielwerte der Version; mit `variables` nur die angegebenen Werte \u2014\nfehlt eine Pflichtvariable, antwortet die API `422` (`errors` nennt `variables.`). Ein Brief (`channel=postal`)\nerscheint mit dem Brief-Layout der Version; mit `format=pdf` kommt statt JSON das PDF (`application\/pdf`), wie es der\nPostversand \u00fcbergibt. Ist der PDF-Dienst nicht erreichbar, antwortet die API `503 pdf_rendering_unavailable`.", "summary": "Vorschau", "tags": [ "Template" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "The template key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PreviewTemplateRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "version": { "type": "integer" }, "channel": { "type": "string" }, "locale": { "type": "string" }, "subject": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "html": { "type": "string" } }, "required": [ "version", "channel", "locale", "subject", "text", "html" ] } }, "required": [ "data" ] } }, "application\/pdf": { "schema": { "type": "string" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string", "const": "inline; filename=\"vorschau.pdf\"" } } } }, "503": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "PDF nicht verf\u00fcgbar" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 503 }, {} ] }, "code": { "anyOf": [ { "type": "string", "const": "pdf_rendering_unavailable" }, {} ] }, "detail": { "anyOf": [ { "type": "string", "const": "Der PDF-Dienst hat kein PDF geliefert; bitte sp\u00e4ter erneut versuchen." }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } }, "headers": { "Retry-After": { "schema": { "type": "string", "const": "30" } } } }, "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Vorgang nicht m\u00f6glich" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/usage": { "get": { "operationId": "usage.index", "description": "Summiert den eigenen Verbrauch in Mengen. Der Zeitraum ist ein Abrechnungsmonat (`period`, `YYYY-MM`, Vorgabe der laufende\nMonat in `Europe\/Vienna`) oder ein Datumsbereich (`from` bis `to`, beide Tage eingeschlossen). `group_by` nennt kommagetrennt\ndie Gruppierung aus `metric`, `channel` und `day` (Vorgabe `metric`); anderes antwortet `400 invalid_group_by` mit `allowed`.\nJede Zeile tr\u00e4gt die gew\u00e4hlten Gruppenspalten, die Einheit `unit` und die Menge `quantity` als Dezimal-String. Kosten und\nPreise liefert diese Schnittstelle nie. `meta.provisional` ist `true`, solange ein ber\u00fchrter Monat nicht abgeschlossen ist:\nsp\u00e4tere Buchungen k\u00f6nnen die Zahlen noch \u00e4ndern; ab dem Abschluss sind sie endg\u00fcltig.", "summary": "Verbrauch abrufen", "tags": [ "Usage" ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "group_by", "in": "query", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "period": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "provisional": { "type": "boolean" } }, "required": [ "period", "from", "to", "provisional" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/webhook-deliveries\/{delivery}\/replay": { "post": { "operationId": "webhookDelivery.replay", "description": "Setzt f\u00fcr dasselbe Ereignis einen neuen Zustellversuch an (`202`); die Antwort ist die neue Zustellung. Die `webhook-id`\nbleibt die `evt_\u2026`-ID des Ereignisses, der Empf\u00e4nger kann doppelte Zustellungen dar\u00fcber erkennen. M\u00f6glich, solange das\nEreignis aufbewahrt wird (30 Tage). Eine noch angesetzte Zustellung antwortet `409 delivery_pending`, ein nicht\naktiver Webhook `409 webhook_not_active`, ein durch L\u00f6schung (Art. 17) geleertes Ereignis `409 event_erased`.", "summary": "Zustellung wiederholen", "tags": [ "WebhookDelivery" ], "parameters": [ { "name": "delivery", "in": "path", "required": true, "description": "The delivery ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "`WebhookDeliveryResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookDeliveryResource" } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Wiederholung nicht m\u00f6glich" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/webhooks": { "get": { "operationId": "webhookEndpoint.index", "description": "Filter: `status` (`active`, `disabled`, `auto_disabled`); Sortierung: `created_at`.", "summary": "Webhook-Endpoints auflisten", "tags": [ "WebhookEndpoint" ], "parameters": [ { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `created_at`. Vorgabe: `created_at`.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "description": "Nur diesen Status. Kommaliste: eines von.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "next_cursor", "prev_cursor" ] } }, "required": [ "data", "meta" ] } } } } } }, "post": { "operationId": "webhookEndpoint.store", "description": "Legt den Endpoint an (`201`). `url` muss `https:\/\/` auf Port 443 und \u00f6ffentlich erreichbar sein (keine\nprivaten, Loopback- oder Link-Local-Adressen, keine Zugangsdaten in der URL). `event_types` nennt die\nabonnierten Ereignistypen, `*` alle. Die Antwort enth\u00e4lt **einmalig** das `secret` (`whsec_\u2026`), mit dem die\nSignatur der Zustellungen gepr\u00fcft wird.", "summary": "Webhook-Endpoint anlegen", "tags": [ "WebhookEndpoint" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "`WebhookEndpointResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpointResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/webhooks\/{webhook}": { "get": { "operationId": "webhookEndpoint.show", "summary": "Webhook-Endpoint abrufen", "tags": [ "WebhookEndpoint" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "`WebhookEndpointResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpointResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } }, "patch": { "operationId": "webhookEndpoint.update", "description": "Jedes Feld ist optional. `status` schaltet zwischen `active` und `disabled`; das erneute Aktivieren setzt auch\neinen automatisch deaktivierten Endpoint zur\u00fcck. Das Secret bleibt unver\u00e4ndert.", "summary": "Webhook-Endpoint \u00e4ndern", "tags": [ "WebhookEndpoint" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/PatchWebhookRequest" } } } }, "responses": { "200": { "description": "`WebhookEndpointResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpointResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } }, "delete": { "operationId": "webhookEndpoint.destroy", "summary": "Webhook-Endpoint l\u00f6schen", "tags": [ "WebhookEndpoint" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/webhooks\/{webhook}\/deliveries": { "get": { "operationId": "webhookEndpoint.deliveries", "description": "Jeder Zustellversuch ist ein Eintrag (Status, HTTP-Status, Antwortauszug, Dauer, Fehler), neueste zuerst. Filter:\n`status` (`pending`, `succeeded`, `failed`, `gave_up`) und `created_at`; Sortierung: `created_at`. Aufbewahrung 30 Tage.", "summary": "Delivery-Log eines Webhook-Endpoints", "tags": [ "WebhookEndpoint" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Zeilen je Seite, 1 bis 200.", "schema": { "type": "integer", "default": 50 } }, { "name": "cursor", "in": "query", "description": "`meta.next_cursor` oder `meta.prev_cursor` der vorigen Antwort; gilt nur f\u00fcr dieselbe Sortierung.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sortierung, `-` vor dem Feld sortiert absteigend. Erlaubt: `created_at`. Vorgabe: `-created_at`.", "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "description": "Nur diesen Zustellstatus (`pending`, `succeeded`, `failed`, `gave_up`). Kommaliste: eines von.", "schema": { "type": "string" } }, { "name": "filter[created_at][gt]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: gr\u00f6\u00dfer als, ISO 8601.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[created_at][gte]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: ab (einschlie\u00dflich), ISO 8601.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[created_at][lt]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: kleiner als, ISO 8601.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[created_at][lte]", "in": "query", "description": "Zeitbereich f\u00fcr `created_at`: bis (einschlie\u00dflich), ISO 8601.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "next_cursor", "prev_cursor" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/webhooks\/{webhook}\/test": { "post": { "operationId": "webhookEndpoint.test", "description": "Sendet ein Ereignis vom Typ `webhook.test` an genau diesen Webhook (`202`); die Antwort ist die angesetzte Zustellung,\nihr Ergebnis steht im Delivery-Log. Antwortet `409 webhook_not_active`, wenn der Webhook nicht aktiv ist.", "summary": "Test-Ereignis senden", "tags": [ "WebhookEndpoint" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "`WebhookDeliveryResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookDeliveryResource" } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application\/problem+json": { "schema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string" }, {} ] }, "title": { "anyOf": [ { "type": "string", "const": "Test nicht m\u00f6glich" }, {} ] }, "status": { "anyOf": [ { "type": "integer", "const": 409 }, {} ] }, "code": { "anyOf": [ { "type": "string" }, {} ] }, "detail": { "anyOf": [ { "type": "string" }, {} ] }, "request_id": { "anyOf": [ { "type": "string" }, {} ] } }, "required": [ "type", "title", "status", "code", "detail", "request_id" ], "additionalProperties": {} } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/webhooks\/{webhook}\/rotate-secret": { "post": { "operationId": "webhookEndpoint.rotateSecret", "description": "Erzeugt ein neues Secret und gibt es **einmalig** als `secret` zur\u00fcck. Das bisherige bleibt f\u00fcr `grace_hours` (Vorgabe 24,\nh\u00f6chstens 168; 0 l\u00f6st es sofort ab) g\u00fcltig: in dieser Zeit tragen die Zustellungen mehrere Signaturen im Header\n`webhook-signature`, und der Empf\u00e4nger akzeptiert, wenn eine passt. `previous_secret_expires_at` nennt das Ende der Frist.", "summary": "Secret rotieren", "tags": [ "WebhookEndpoint" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RotateWebhookSecretRequest" } } } }, "responses": { "200": { "description": "`WebhookEndpointResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpointResource" }, "previous_secret_expires_at": { "type": "null" } }, "required": [ "data", "previous_secret_expires_at" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } } }, "webhooks": { "message.created": { "post": { "operationId": "webhook_message_created", "description": "Wird an jeden aktiven Endpoint gesendet, der `message.created` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Nachricht angelegt", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MessageCreatedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "message.received": { "post": { "operationId": "webhook_message_received", "description": "Wird an jeden aktiven Endpoint gesendet, der `message.received` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Nachricht empfangen", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MessageReceivedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "message.sent": { "post": { "operationId": "webhook_message_sent", "description": "Wird an jeden aktiven Endpoint gesendet, der `message.sent` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Nachricht gesendet", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MessageSentWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "message.delivered": { "post": { "operationId": "webhook_message_delivered", "description": "Wird an jeden aktiven Endpoint gesendet, der `message.delivered` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Nachricht zugestellt", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MessageDeliveredWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "message.read": { "post": { "operationId": "webhook_message_read", "description": "Wird an jeden aktiven Endpoint gesendet, der `message.read` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Nachricht gelesen", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MessageReadWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "message.failed": { "post": { "operationId": "webhook_message_failed", "description": "Wird an jeden aktiven Endpoint gesendet, der `message.failed` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Nachricht fehlgeschlagen", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/MessageFailedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "conversation.created": { "post": { "operationId": "webhook_conversation_created", "description": "Wird an jeden aktiven Endpoint gesendet, der `conversation.created` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Conversation er\u00f6ffnet", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ConversationCreatedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "conversation.updated": { "post": { "operationId": "webhook_conversation_updated", "description": "Wird an jeden aktiven Endpoint gesendet, der `conversation.updated` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Conversation ge\u00e4ndert", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ConversationUpdatedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "customer.updated": { "post": { "operationId": "webhook_customer_updated", "description": "Wird an jeden aktiven Endpoint gesendet, der `customer.updated` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Kontakt ge\u00e4ndert", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CustomerUpdatedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "customer.merged": { "post": { "operationId": "webhook_customer_merged", "description": "Wird an jeden aktiven Endpoint gesendet, der `customer.merged` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Kontakte zusammengef\u00fchrt", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CustomerMergedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "template.status_changed": { "post": { "operationId": "webhook_template_status_changed", "description": "Wird an jeden aktiven Endpoint gesendet, der `template.status_changed` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Template-Status ge\u00e4ndert", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TemplateStatusChangedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "channel.updated": { "post": { "operationId": "webhook_channel_updated", "description": "Wird an jeden aktiven Endpoint gesendet, der `channel.updated` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Kanal ge\u00e4ndert", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ChannelUpdatedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "export.ready": { "post": { "operationId": "webhook_export_ready", "description": "Wird an jeden aktiven Endpoint gesendet, der `export.ready` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Export bereit", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ExportReadyWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "event.completed": { "post": { "operationId": "webhook_event_completed", "description": "Wird an jeden aktiven Endpoint gesendet, der `event.completed` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Gesch\u00e4ftsereignis abgeschlossen", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EventCompletedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "event.failed": { "post": { "operationId": "webhook_event_failed", "description": "Wird an jeden aktiven Endpoint gesendet, der `event.failed` (oder `*`) abonniert hat. Jeder Versuch ist ein eigener Aufruf; Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden, Weiterleitungen gelten als Fehlschlag.", "summary": "Gesch\u00e4ftsereignis fehlgeschlagen", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EventFailedWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } }, "webhook.test": { "post": { "operationId": "webhook_webhook_test", "description": "Test-Ereignis (`POST \/webhooks\/{webhook}\/test`); nicht abonnierbar, geht nur an den angeforderten Endpoint.", "summary": "Test-Ereignis", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Versuche gleich: Schl\u00fcssel zur Entdoppelung.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Zeitpunkt des Versuchs in Sekunden seit 1970 (je Versuch neu).", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Signatur nach Standard Webhooks: `v1,..\")>`; mehrere Signaturen (Secret-Rotation) sind durch Leerzeichen getrennt.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WebhookTestWebhook" } } } }, "responses": { "200": { "description": "Empfang best\u00e4tigt (jede 2xx-Antwort gilt als Erfolg)." } }, "security": [ {} ] } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "\/api\/v1\/oauth\/token", "scopes": { "customers:read": "Kontakte lesen", "customers:write": "Kontakte schreiben", "conversations:read": "Conversations lesen", "conversations:write": "Conversations schreiben", "messages:read": "Nachrichten lesen", "messages:write": "Nachrichten senden", "events:write": "Gesch\u00e4ftsereignisse melden", "templates:read": "Templates lesen", "templates:write": "Templates schreiben", "channels:read": "Kan\u00e4le lesen", "webhooks:manage": "Webhooks verwalten", "resolver:manage": "Customer Resolver verwalten", "usage:read": "Verbrauch lesen", "campaigns:read": "Kampagnen lesen", "campaigns:write": "Kampagnen anlegen und steuern" } } } }, "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "AddIdentityRequest": { "type": "object", "description": "Eine Identity hinzuf\u00fcgen (`POST \/customers\/{customer}\/identities`).", "properties": { "type": { "$ref": "#\/components\/schemas\/IdentityType" }, "value": { "type": "string", "maxLength": 255 }, "address": { "type": "array", "items": { "type": "string" } }, "is_primary": { "type": "boolean" }, "label": { "type": [ "string", "null" ], "maxLength": 32 } }, "required": [ "type" ], "title": "AddIdentityRequest" }, "AttachmentResource": { "type": "object", "properties": { "id": { "type": "string" }, "message_id": { "type": [ "string", "null" ] }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "scan_status": { "$ref": "#\/components\/schemas\/AttachmentScanStatus" }, "source": { "$ref": "#\/components\/schemas\/AttachmentSource" }, "created_at": { "type": "string" }, "download": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "url", "expires_at" ] } }, "required": [ "id", "message_id", "filename", "mime_type", "size", "sha256", "scan_status", "source", "created_at" ], "title": "AttachmentResource" }, "AttachmentScanStatus": { "type": "string", "description": "Ergebnis der Virenpr\u00fcfung eines Anhangs (Plan 5.7: `attachments.scan_status`).\n", "enum": [ "pending", "clean", "infected", "skipped" ], "title": "AttachmentScanStatus" }, "AttachmentSource": { "type": "string", "description": "Woher ein Anhang stammt (Plan 5.7: `attachments.source`).\n", "enum": [ "upload", "inbound", "generated" ], "title": "AttachmentSource" }, "BusinessEventResource": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "status": { "$ref": "#\/components\/schemas\/BusinessEventStatus" }, "customer": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ] } }, "required": [ "id", "customer_id" ] }, "client_reference": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "completed_at": { "type": [ "string", "null" ] }, "rule": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "response": { "type": [ "object", "null" ], "properties": { "expected": { "type": "boolean" }, "timeout_s": { "type": [ "integer", "null" ] }, "responded_at": { "type": [ "string", "null" ] } }, "required": [ "expected", "timeout_s", "responded_at" ] }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "integer" }, "channel": { "$ref": "#\/components\/schemas\/Channel" }, "outcome": { "$ref": "#\/components\/schemas\/DispatchOutcome" }, "reason": { "anyOf": [ { "$ref": "#\/components\/schemas\/DispatchReason" }, { "type": "null" } ] }, "detail": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "step", "channel", "outcome", "reason", "detail", "message_id", "created_at" ] } } }, "required": [ "id", "event", "status", "customer", "client_reference", "created_at" ], "title": "BusinessEventResource" }, "BusinessEventStatus": { "type": "string", "description": "Zustand eines Gesch\u00e4ftsereignisses (Plan 5.9: `business_events.status`). `received`: angenommen; die \u00fcbrigen Zust\u00e4nde setzt die Planung und Ausf\u00fchrung der Dispatches (Arbeitspaket 12.4).\n", "enum": [ "received", "planned", "running", "completed", "no_route", "failed", "cancelled" ], "title": "BusinessEventStatus" }, "BusinessReferenceType": { "type": "string", "description": "Art des Gesch\u00e4ftsvorgangs im Kundensystem (Plan 5.6: `business_references.type`).\n", "enum": [ "vehicle", "order", "invoice", "appointment", "ticket", "campaign", "custom" ], "title": "BusinessReferenceType" }, "CampaignResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "template": { "type": "string" }, "status": { "$ref": "#\/components\/schemas\/CampaignStatus" }, "status_reason": { "type": [ "string", "null" ] }, "segment": { "type": "string" }, "variables": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] }, "audience_total": { "type": [ "integer", "null" ] }, "sent": { "type": "integer" }, "skipped": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "template", "status", "status_reason", "segment", "variables", "scheduled_at", "started_at", "finished_at", "audience_total", "sent", "skipped", "created_at", "updated_at" ], "title": "CampaignResource" }, "CampaignStatus": { "type": "string", "description": "Zustand einer Kampagne (15.12, `campaigns.status`). `draft`: angelegt, nichts geplant; `scheduled`: startet zu `scheduled_at`; `running`: die Stapel laufen; `paused`: angehalten, weil der Versand nicht weitergeht (Grund in `status_reason`, etwa Kostenobergrenze oder pausierter Kanal) \u2014 erneutes Starten setzt sie fort; `completed` und `cancelled` sind Endzust\u00e4nde.\n", "enum": [ "draft", "scheduled", "running", "paused", "completed", "cancelled" ], "title": "CampaignStatus" }, "Channel": { "type": "string", "description": "Kanal, \u00fcber den die Plattform kommuniziert (Plan 5.5: `consents.channel`, `suppressions.channel`). Jeder Kanal erreicht einen Kontakt \u00fcber genau einen `IdentityType`.\n", "enum": [ "email", "sms", "whatsapp", "rcs", "postal" ], "title": "Channel" }, "ChannelUpdatedWebhook": { "type": "object", "description": "Kanal ge\u00e4ndert", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "channel.updated" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "channel": { "$ref": "#\/components\/schemas\/Channel" }, "domain": { "type": [ "string", "null" ], "description": "Absenderdomain, deren Zustand sich ge\u00e4ndert hat (E-Mail)." }, "status": { "type": "string", "description": "Neuer Zustand des Kanals bzw. der Domain." } }, "required": [ "channel", "domain", "status" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "ChannelUpdatedWebhook" }, "ConsentPurpose": { "type": "string", "description": "Zweck einer Nachricht und damit einer Einwilligung (Plan 5.5). `marketing` verlangt immer eine ausdr\u00fcckliche Einwilligung; f\u00fcr die anderen Zwecke bestimmt `communication.consent.implicit_purposes`, ob sie ohne gelten (Pr\u00fcfung: `ConsentPolicy`).\n", "enum": [ "transactional", "service", "marketing" ], "title": "ConsentPurpose" }, "ConsentResource": { "type": "object", "properties": { "purpose": { "$ref": "#\/components\/schemas\/ConsentPurpose" }, "status": { "$ref": "#\/components\/schemas\/ConsentStatus" }, "channel": { "anyOf": [ { "$ref": "#\/components\/schemas\/Channel" }, { "type": "null" } ] }, "identity_id": { "type": [ "string", "null" ] }, "source": { "$ref": "#\/components\/schemas\/ConsentSource" }, "evidence": { "type": [ "array", "null" ], "items": {} }, "granted_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] } }, "required": [ "purpose", "status", "channel", "identity_id", "source", "evidence", "granted_at", "revoked_at" ], "title": "ConsentResource" }, "ConsentSource": { "type": "string", "description": "Woher eine Einwilligung stammt (Plan 5.5: `consents.source`).\n", "enum": [ "api", "ui", "inbound_keyword", "double_opt_in", "import" ], "title": "ConsentSource" }, "ConsentStatus": { "type": "string", "description": "Stand einer Einwilligung (Plan 5.5): erteilt oder widerrufen.\n", "enum": [ "granted", "revoked" ], "title": "ConsentStatus" }, "ContactExportResource": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "$ref": "#\/components\/schemas\/ContactExportStatus" } }, "required": [ "id", "customer_id", "status" ], "title": "ContactExportResource" }, "ContactExportStatus": { "type": "string", "description": "Zustand eines Auskunftspakets (`contact_exports.status`). `pending`: angefordert, das Paket wird gebaut; `ready`: die Datei liegt im Objektspeicher und der Link wurde gemeldet; `failed`: der letzte Versuch ist gescheitert (der Job wiederholt).\n", "enum": [ "pending", "ready", "failed" ], "title": "ContactExportStatus" }, "ContactStatus": { "type": "string", "description": "Lebenszyklus eines Kontakts (Plan 5.5): `unresolved` entsteht beim Eingang von einem unbekannten Absender, `merged` verweist \u00fcber `merged_into_id` auf den Zielkontakt, `erased` ist die DSGVO-L\u00f6schung (Name entfernt, Identities gel\u00f6scht).\n", "enum": [ "active", "unresolved", "merged", "erased" ], "title": "ContactStatus" }, "ConversationCreatedWebhook": { "type": "object", "description": "Conversation er\u00f6ffnet", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "conversation.created" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "conversation": { "$ref": "#\/components\/schemas\/ConversationResource" } }, "required": [ "conversation" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "ConversationCreatedWebhook" }, "ConversationPriority": { "type": "string", "description": "Dringlichkeit einer Conversation in der Inbox (Plan 5.6: `conversations.priority`).\n", "enum": [ "low", "normal", "high" ], "title": "ConversationPriority" }, "ConversationResource": { "type": "object", "properties": { "id": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] } }, "required": [ "id", "customer_id" ] }, "status": { "$ref": "#\/components\/schemas\/ConversationStatus" }, "subject": { "type": [ "string", "null" ] }, "priority": { "$ref": "#\/components\/schemas\/ConversationPriority" }, "channels": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Channel" } }, "references": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#\/components\/schemas\/BusinessReferenceType" }, "id": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "role": { "$ref": "#\/components\/schemas\/ReferenceRole" } }, "required": [ "type", "id", "label", "url", "role" ] } }, "assigned_to": { "type": [ "object", "null" ], "properties": { "id": {}, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "last_message_at": { "type": [ "string", "null" ] }, "last_inbound_at": { "type": [ "string", "null" ] }, "last_channel": { "anyOf": [ { "$ref": "#\/components\/schemas\/Channel" }, { "type": "null" } ] }, "unread": { "type": "boolean" }, "snoozed_until": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_message": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "direction": { "$ref": "#\/components\/schemas\/MessageDirection" }, "channel": { "$ref": "#\/components\/schemas\/Channel" }, "status": { "$ref": "#\/components\/schemas\/MessageStatus" }, "preview": { "type": [ "string", "null" ] } }, "required": [ "id", "direction", "channel", "status", "preview" ] } }, "required": [ "id", "customer", "status", "subject", "priority", "channels", "references", "assigned_to", "last_message_at", "last_inbound_at", "last_channel", "unread", "snoozed_until", "closed_at", "created_at", "updated_at" ], "title": "ConversationResource" }, "ConversationStatus": { "type": "string", "description": "Lebenszyklus einer Conversation (Plan 5.6, 9.2): `open` \u2192 `pending` (wartet auf den Kontakt) \u2192 `closed`; `snoozed` blendet sie bis `snoozed_until` aus. Offen im Sinne der Zuordnung ist alles au\u00dfer `closed` ({@see self::isOpen()}).\n", "enum": [ "open", "pending", "snoozed", "closed" ], "title": "ConversationStatus" }, "ConversationUpdatedWebhook": { "type": "object", "description": "Conversation ge\u00e4ndert", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "conversation.updated" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "conversation": { "$ref": "#\/components\/schemas\/ConversationResource" } }, "required": [ "conversation" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "ConversationUpdatedWebhook" }, "CreateCampaignRequest": { "type": "object", "description": "Neue Kampagne (`POST \/campaigns`): Name, Template (Schl\u00fcssel; Zweck `marketing`), Segment und feste Template-Variablen. Was ein\nSegment ist und ob das Template sendbar ist, entscheidet allein `CampaignSegment` (`422`).", "properties": { "name": { "type": "string", "maxLength": 160 }, "template": { "type": "string", "maxLength": 255 }, "segment": { "type": "array", "items": { "type": "string" } }, "variables": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "maxItems": 50 } }, "required": [ "name", "template" ], "title": "CreateCampaignRequest" }, "CreateTemplateRequest": { "type": "object", "description": "Schl\u00fcssel, Name, Zweck und Beschreibung eines Templates (`POST \/templates`); der Schl\u00fcssel ist der Pfadparameter der API.", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$" }, "name": { "type": "string", "maxLength": 255 }, "purpose": { "anyOf": [ { "$ref": "#\/components\/schemas\/TemplatePurpose" }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "key", "name" ], "title": "CreateTemplateRequest" }, "CreateWebhookRequest": { "type": "object", "description": "Neuer Webhook-Endpoint (`POST \/webhooks`): URL, abonnierte Ereignistypen (`*` = alle) und Beschreibung. Ob die URL\nzul\u00e4ssig ist (SSRF-Schutz), entscheidet allein `CreateWebhookEndpoint`.", "properties": { "url": { "type": "string", "maxLength": 2000 }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "message.created", "message.received", "message.sent", "message.delivered", "message.read", "message.failed", "conversation.created", "conversation.updated", "customer.updated", "customer.merged", "template.status_changed", "channel.updated", "export.ready", "event.completed", "event.failed", "*" ] }, "minItems": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "url", "event_types" ], "title": "CreateWebhookRequest" }, "CustomerMergedWebhook": { "type": "object", "description": "Kontakte zusammengef\u00fchrt", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "customer.merged" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "customer": { "$ref": "#\/components\/schemas\/CustomerResource" }, "merged_customer_id": { "type": "string", "description": "\u00d6ffentliche ID (`cus_\u2026`) des Kontakts, der in `customer` aufgegangen ist." } }, "required": [ "customer", "merged_customer_id" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "CustomerMergedWebhook" }, "CustomerResolverResource": { "type": "object", "properties": { "url": { "type": "string" }, "timeout_seconds": { "type": "integer" }, "identity_types": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "secret": { "type": [ "string", "null" ] } }, "required": [ "url", "timeout_seconds", "identity_types", "enabled", "created_at", "updated_at" ], "title": "CustomerResolverResource" }, "CustomerResource": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "status": { "$ref": "#\/components\/schemas\/ContactStatus" }, "merged_into": { "type": "string", "description": "\u00d6ffentliche ID des Kunden, in den dieser aufgegangen ist; nur bei Status `merged` vorhanden (optional, damit die Form des Kunden f\u00fcr bestehende Empf\u00e4nger abw\u00e4rtskompatibel bleibt)." }, "metadata": { "type": "object", "additionalProperties": {} }, "identities": { "type": "array", "items": { "$ref": "#\/components\/schemas\/IdentityResource" } }, "reachability": { "type": "object", "properties": { "email": { "type": "boolean" }, "sms": { "type": "boolean" }, "whatsapp": { "type": [ "boolean", "string" ] }, "postal": { "type": "boolean" } }, "required": [ "email", "sms", "whatsapp", "postal" ] }, "consents": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ConsentResource" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "customer_id", "display_name", "first_name", "last_name", "company", "locale", "timezone", "country", "status", "metadata", "identities", "reachability", "consents", "created_at", "updated_at" ], "title": "CustomerResource" }, "CustomerUpdatedWebhook": { "type": "object", "description": "Kontakt ge\u00e4ndert", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "customer.updated" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "customer": { "$ref": "#\/components\/schemas\/CustomerResource" } }, "required": [ "customer" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "CustomerUpdatedWebhook" }, "DispatchOutcome": { "type": "string", "description": "Ausgang eines Versuchs (Plan 5.9: `dispatch_attempts.outcome`). `sent`: die Nachricht ist \u00fcbergeben, das Ergebnis steht noch aus; `skipped`: der Kanal wurde nicht versucht (keine Adresse, Einwilligung fehlt, gesperrt); `failed`: Versand oder Zustellung sind gescheitert; `timed_out`: die Frist ist abgelaufen; `succeeded`: eine Stopp-Bedingung der Regel ist erf\u00fcllt.\n", "enum": [ "sent", "skipped", "failed", "timed_out", "succeeded" ], "title": "DispatchOutcome" }, "DispatchReason": { "type": "string", "description": "Grund, aus dem ein Versuch endet (Plan 5.9: `dispatch_attempts.reason`) \u2014 die Antwort auf \u201ewarum wurde hier ein Brief geschickt?\u201c. {@see self::condition()} ist die **einzige Stelle**, die einen Grund auf die \u00dcbergangsbedingung der Regel abbildet (`rule_steps.advance_on`); die Gr\u00fcnde ohne Bedingung beenden den Versuch erfolgreich oder den Dispatch.\n", "x-extensible-enum": [ "no_identity", "no_consent", "suppressed", "quiet_hours", "no_provider_account", "template_unavailable", "send_rejected", "provider_error", "undeliverable", "not_delivered_in_time", "not_read_in_time", "no_response_in_time", "message_cancelled", "wait_expired", "delivered", "read", "responded", "condition_not_met" ], "title": "DispatchReason" }, "EventCompletedWebhook": { "type": "object", "description": "Gesch\u00e4ftsereignis abgeschlossen", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "event.completed" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "event": { "$ref": "#\/components\/schemas\/BusinessEventResource" } }, "required": [ "event" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "EventCompletedWebhook" }, "EventFailedWebhook": { "type": "object", "description": "Gesch\u00e4ftsereignis fehlgeschlagen", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "event.failed" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "event": { "$ref": "#\/components\/schemas\/BusinessEventResource" } }, "required": [ "event" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "EventFailedWebhook" }, "ExportReadyWebhook": { "type": "object", "description": "Export bereit", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "export.ready" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "export": { "type": "object", "description": "Das fertige Auskunftspaket (`GET \/customers\/{customer}\/export`).", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Exports (`exp_\u2026`)." }, "customer_id": { "type": "string", "description": "\u00d6ffentliche ID (`cus_\u2026`) des Kontakts, dessen Daten das Paket enth\u00e4lt." }, "url": { "type": "string", "description": "Signierter Download-Link auf das ZIP-Paket; g\u00fcltig bis `expires_at`." }, "expires_at": { "type": "string", "format": "date-time", "description": "Ende der G\u00fcltigkeit des Links (UTC)." } }, "required": [ "id", "customer_id", "url", "expires_at" ] } }, "required": [ "export" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "ExportReadyWebhook" }, "IdentityResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "$ref": "#\/components\/schemas\/IdentityType" }, "value": { "type": [ "string", "null" ] }, "address": { "type": [ "array", "null" ], "items": {} }, "label": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" }, "status": { "$ref": "#\/components\/schemas\/IdentityStatus" }, "verified_at": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "value", "label", "is_primary", "status", "verified_at" ], "title": "IdentityResource" }, "IdentityStatus": { "type": "string", "description": "Zustellbarkeit einer Identity (Plan 5.5); Bounces und Beschwerden setzen sie sp\u00e4ter.\n", "enum": [ "valid", "invalid", "bounced", "unreachable" ], "title": "IdentityStatus" }, "IdentityType": { "type": "string", "description": "Art einer Erreichbarkeit eines Kontakts (Plan 5.5). Wie der Wert normalisiert wird, entscheidet allein {@see NormalizeIdentity}.\n", "enum": [ "email", "phone", "whatsapp", "rcs", "postal_address" ], "title": "IdentityType" }, "MergeCustomerRequest": { "type": "object", "description": "Einen Kunden in einen anderen \u00fcberf\u00fchren (`POST \/customers\/{customer}\/merge`).", "properties": { "source": { "type": "string", "description": "`cus_\u2026` oder `customer_id` des Kunden, der aufgeht; aufgel\u00f6st im Controller (Cross-Tenant \u2192 404).", "maxLength": 255 } }, "required": [ "source" ], "title": "MergeCustomerRequest" }, "MessageCreatedWebhook": { "type": "object", "description": "Nachricht angelegt", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "message.created" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "message": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "message" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "MessageCreatedWebhook" }, "MessageDeliveredWebhook": { "type": "object", "description": "Nachricht zugestellt", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "message.delivered" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "message": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "message" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "MessageDeliveredWebhook" }, "MessageDirection": { "type": "string", "description": "Richtung einer Nachricht (Plan 5.7: `messages.direction`).\n", "enum": [ "outbound", "inbound" ], "title": "MessageDirection" }, "MessageFailedWebhook": { "type": "object", "description": "Nachricht fehlgeschlagen", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "message.failed" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "message": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "message" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "MessageFailedWebhook" }, "MessageReadWebhook": { "type": "object", "description": "Nachricht gelesen", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "message.read" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "message": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "message" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "MessageReadWebhook" }, "MessageReceivedWebhook": { "type": "object", "description": "Nachricht empfangen", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "message.received" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "message": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "message" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "MessageReceivedWebhook" }, "MessageResource": { "type": "object", "properties": { "id": { "type": "string" }, "conversation_id": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] } }, "required": [ "id", "customer_id" ] }, "direction": { "$ref": "#\/components\/schemas\/MessageDirection" }, "channel": { "$ref": "#\/components\/schemas\/Channel" }, "status": { "$ref": "#\/components\/schemas\/MessageStatus" }, "purpose": { "$ref": "#\/components\/schemas\/ConsentPurpose" }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "cc": { "type": "array", "items": {} }, "subject": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] }, "author": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "user" }, "name": { "type": [ "string", "null" ] } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ] } ] }, "in_reply_to": { "type": [ "string", "null" ] }, "client_reference": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} }, "attachments": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AttachmentResource" } }, "failure": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "code", "reason" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "queued_at": { "type": [ "string", "null" ] }, "sent_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "read_at": { "type": [ "string", "null" ] }, "failed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "conversation_id", "customer", "direction", "channel", "status", "purpose", "from", "to", "cc", "subject", "text", "html", "author", "in_reply_to", "client_reference", "metadata", "attachments", "scheduled_at", "created_at", "queued_at", "sent_at", "delivered_at", "read_at", "failed_at" ], "title": "MessageResource" }, "MessageSentWebhook": { "type": "object", "description": "Nachricht gesendet", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "message.sent" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "message": { "$ref": "#\/components\/schemas\/MessageResource" } }, "required": [ "message" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "MessageSentWebhook" }, "MessageStatus": { "type": "string", "description": "Status einer Nachricht (Plan 8.2) und die Statusmaschine dazu \u2014 **die einzige Stelle**, die erlaubte \u00dcberg\u00e4nge und die Rangfolge kennt. Der Status an `messages` ist abgeleiteter Zustand; ge\u00e4ndert wird er allein von {@see RecordMessageEvent}, das Model lehnt jeden anderen \u00dcbergang ab. Fortschritt hat einen Rang (`accepted` < `scheduled` < `queued` < `sending`\/`retrying` < `sent` < `delivered` < `read`); ein Status darf nur auf einen h\u00f6heren Rang wechseln, auch mehrere Stufen auf einmal (ein Provider-Webhook kann `sent` \u00fcberspringen). Zwischen `sending` und `retrying` (gleicher Rang) geht es hin und her. Die Fehlerzust\u00e4nde sind nur aus bestimmten Zust\u00e4nden erreichbar ({@see self::sources()}) und danach terminal. Einzige Ausnahme: `delivered` \u2192 `read`.\n", "enum": [ "accepted", "scheduled", "queued", "sending", "retrying", "sent", "delivered", "read", "failed", "undeliverable", "rejected", "cancelled", "expired", "received" ], "title": "MessageStatus" }, "OauthTokenRequest": { "type": "object", "description": "Anfrage an den Token-Endpunkt (`POST \/oauth\/token`, OAuth2 Client Credentials). Ein Formfehler antwortet nicht als\n`422 validation_failed`, sondern wie RFC 6749 verlangt als `400 invalid_request`. `client_id` und `client_secret` sind hier\nnicht Pflicht, weil sie stattdessen per HTTP Basic kommen d\u00fcrfen; ob eines von beiden da ist, pr\u00fcft der Controller.", "properties": { "grant_type": { "type": "string", "maxLength": 50 }, "client_id": { "type": [ "string", "null" ], "maxLength": 100 }, "client_secret": { "type": [ "string", "null" ], "maxLength": 200 }, "scope": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "grant_type" ], "title": "OauthTokenRequest" }, "PatchConversationRequest": { "type": "object", "description": "Status, Zuweisung, Betreff und Priorit\u00e4t einer Conversation (`PATCH \/conversations\/{id}`); die Regeln dazu kennt `UpdateConversation`.", "properties": { "status": { "$ref": "#\/components\/schemas\/ConversationStatus" }, "subject": { "type": [ "string", "null" ], "maxLength": 255 }, "assigned_to": { "type": [ "integer", "null" ] }, "priority": { "$ref": "#\/components\/schemas\/ConversationPriority" }, "snoozed_until": { "type": [ "string", "null" ], "format": "date-time" } }, "title": "PatchConversationRequest" }, "PatchCustomerRequest": { "type": "object", "description": "Stammdaten eines Kunden (`PATCH \/customers\/{customer}`); jedes Feld ist optional, `null` leert es.\nDie Ability pr\u00fcft die Route, Mandantentrennung das Route-Binding.", "properties": { "display_name": { "type": [ "string", "null" ], "maxLength": 255 }, "first_name": { "type": [ "string", "null" ], "maxLength": 255 }, "last_name": { "type": [ "string", "null" ], "maxLength": 255 }, "company": { "type": [ "string", "null" ], "maxLength": 255 }, "locale": { "type": [ "string", "null" ], "maxLength": 16 }, "timezone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Za-z]{2}$" }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "title": "PatchCustomerRequest" }, "PatchWebhookRequest": { "type": "object", "description": "\u00c4ndert einen Webhook-Endpoint (`PATCH \/webhooks\/{webhook}`); jedes Feld ist optional. `status` schaltet zwischen `active`\nund `disabled`; `auto_disabled` setzt allein die Plattform.", "properties": { "url": { "type": "string", "maxLength": 2000 }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "message.created", "message.received", "message.sent", "message.delivered", "message.read", "message.failed", "conversation.created", "conversation.updated", "customer.updated", "customer.merged", "template.status_changed", "channel.updated", "export.ready", "event.completed", "event.failed", "*" ] }, "minItems": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "title": "PatchWebhookRequest" }, "PostalShipping": { "type": "string", "description": "Versandart eines Briefs (Arbeitspaket 14.4). Der Katalog der Plattform, nicht der eines Providers: welche Arten ein Konto kann, meldet sein Adapter (F\u00e4higkeit `ReportsPostalCapabilities`), wie ein Provider sie nennt, steht in dessen Adapter.\n", "enum": [ "standard", "priority", "registered", "registered_return_receipt" ], "title": "PostalShipping" }, "PreviewTemplateRequest": { "type": "object", "description": "Vorschau eines Templates (`POST \/templates\/{key}\/preview`): Version, Kanal, Sprache, Variablen und Format (`json`, mit `pdf` ein Brief als PDF).", "properties": { "version": { "type": [ "integer", "null" ], "minimum": 1 }, "channel": { "$ref": "#\/components\/schemas\/Channel" }, "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" }, "variables": { "type": [ "array", "null" ], "items": { "type": "string" } }, "format": { "type": "string", "enum": [ "json", "pdf" ] } }, "title": "PreviewTemplateRequest" }, "ReferenceRole": { "type": "string", "description": "Rolle einer Business Reference an ihrem Gegenstand (Plan 5.6: `reference_links.role`): die `primary`e Referenz bestimmt die Zuordnung ausgehender Nachrichten (Plan 9.2), h\u00f6chstens eine je Gegenstand.\n", "enum": [ "primary", "related" ], "title": "ReferenceRole" }, "ReplaceIdentitiesRequest": { "type": "object", "description": "Alle Identities eines Kunden ersetzen (`PUT \/customers\/{customer}\/identities`); eine leere Liste entfernt alle.", "properties": { "identities": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#\/components\/schemas\/IdentityType" }, "value": { "type": "string", "maxLength": 255 }, "address": { "type": "array", "items": { "type": "string" } }, "is_primary": { "type": "boolean" }, "label": { "type": [ "string", "null" ], "maxLength": 32 } }, "required": [ "type" ] }, "maxItems": 50 } }, "required": [ "identities" ], "title": "ReplaceIdentitiesRequest" }, "ReplyMessageRequest": { "type": "object", "description": "Antwort in einer bestehenden Conversation (`POST \/conversations\/{id}\/messages`, Plan 8.2): Kunde und Conversation stehen\nim Pfad. Ohne `channel` bleibt die Antwort auf dem Kanal der letzten Nachricht.", "properties": { "channel": { "type": "string", "enum": [ "auto", "email", "sms", "whatsapp", "rcs", "postal" ] }, "purpose": { "$ref": "#\/components\/schemas\/ConsentPurpose" }, "text": { "type": [ "string", "null" ], "maxLength": 100000 }, "html": { "type": [ "string", "null" ], "maxLength": 1000000 }, "subject": { "type": [ "string", "null" ], "maxLength": 998 }, "from": { "type": [ "string", "null" ], "maxLength": 255 }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 }, "template": { "type": "string", "description": "Templates (Rendering, Variablen) gibt es noch nicht \u2014 ein Aufruf damit soll nicht still ohne Inhalt enden." }, "identity_id": { "type": [ "string", "null" ], "maxLength": 64 }, "attachments": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 20 }, "references": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#\/components\/schemas\/BusinessReferenceType" }, "id": { "type": "string", "maxLength": 255 }, "label": { "type": [ "string", "null" ], "maxLength": 255 }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 } }, "required": [ "type", "id" ] }, "maxItems": 10 }, "in_reply_to": { "type": [ "string", "null" ], "maxLength": 64 }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "client_reference": { "type": [ "string", "null" ], "maxLength": 255 }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" } }, "postal": { "type": "object", "properties": { "shipping": { "$ref": "#\/components\/schemas\/PostalShipping" }, "color": { "type": "boolean" }, "duplex": { "type": "boolean" } } } }, "title": "ReplyMessageRequest" }, "RotateWebhookSecretRequest": { "type": "object", "description": "Rotiert das Secret eines Webhook-Endpoints (`POST \/webhooks\/{webhook}\/rotate-secret`); `grace_hours` ist optional.", "properties": { "grace_hours": { "type": "integer", "minimum": 0, "maximum": 168 } }, "title": "RotateWebhookSecretRequest" }, "SaveCustomerResolverRequest": { "type": "object", "description": "Customer Resolver anlegen oder \u00e4ndern (`PUT \/customer-resolver`): URL, Timeout, Identity-Typen und Schalter. Ob `url` und\n`identity_types` beim Anlegen fehlen d\u00fcrfen, ob die URL zul\u00e4ssig ist (SSRF-Schutz) und wie gro\u00df der Timeout sein darf,\nentscheidet allein `SaveCustomerResolver`.", "properties": { "url": { "type": "string", "maxLength": 2000 }, "timeout_seconds": { "type": "integer" }, "identity_types": { "type": "array", "items": { "type": "string", "enum": [ "email", "phone", "whatsapp", "rcs", "postal_address" ] }, "minItems": 1 }, "enabled": { "type": "boolean" } }, "title": "SaveCustomerResolverRequest" }, "ScheduleCampaignRequest": { "type": "object", "description": "Start einer Kampagne planen (`POST \/campaigns\/{campaign}\/schedule`): `scheduled_at` muss in der Zukunft liegen (`ScheduleCampaign`).", "properties": { "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "scheduled_at" ], "title": "ScheduleCampaignRequest" }, "SendMessageRequest": { "type": "object", "description": "Direkte Nachricht (`POST \/messages`, Plan 8.3): der Kunde steht im Body (`customer_id`: `cus_\u2026` oder die externe\nKundennummer), der Kanal ist Pflicht (`auto` w\u00e4hlt die Plattform). Die Conversation bestimmt sonst\n`FindOrOpenConversation`; ausdr\u00fccklich l\u00e4sst sie sich mit `conversation_id` w\u00e4hlen oder mit `new_conversation` erzwingen.\nAufgerufen vom {@see MessageController}.", "properties": { "channel": { "type": "string", "enum": [ "auto", "email", "sms", "whatsapp", "rcs", "postal" ] }, "purpose": { "$ref": "#\/components\/schemas\/ConsentPurpose" }, "text": { "type": [ "string", "null" ], "maxLength": 100000 }, "html": { "type": [ "string", "null" ], "maxLength": 1000000 }, "subject": { "type": [ "string", "null" ], "maxLength": 998 }, "from": { "type": [ "string", "null" ], "maxLength": 255 }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 }, "template": { "type": "string", "description": "Templates (Rendering, Variablen) gibt es noch nicht \u2014 ein Aufruf damit soll nicht still ohne Inhalt enden." }, "identity_id": { "type": [ "string", "null" ], "maxLength": 64 }, "attachments": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 20 }, "references": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#\/components\/schemas\/BusinessReferenceType" }, "id": { "type": "string", "maxLength": 255 }, "label": { "type": [ "string", "null" ], "maxLength": 255 }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 } }, "required": [ "type", "id" ] }, "maxItems": 10 }, "in_reply_to": { "type": [ "string", "null" ], "maxLength": 64 }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "client_reference": { "type": [ "string", "null" ], "maxLength": 255 }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" } }, "postal": { "type": "object", "properties": { "shipping": { "$ref": "#\/components\/schemas\/PostalShipping" }, "color": { "type": "boolean" }, "duplex": { "type": "boolean" } } }, "customer_id": { "type": "string", "maxLength": 255 }, "conversation_id": { "type": [ "string", "null" ], "maxLength": 64 }, "new_conversation": { "type": "boolean" } }, "required": [ "channel", "customer_id" ], "title": "SendMessageRequest" }, "SetConsentsRequest": { "type": "object", "description": "Einwilligungen eines Kunden setzen (`PUT \/customers\/{customer}\/consents`).", "properties": { "consents": { "type": "array", "items": { "type": "object", "properties": { "purpose": { "$ref": "#\/components\/schemas\/ConsentPurpose" }, "status": { "$ref": "#\/components\/schemas\/ConsentStatus" }, "channel": { "anyOf": [ { "$ref": "#\/components\/schemas\/Channel" }, { "type": "null" } ] }, "identity_id": { "type": [ "string", "null" ], "maxLength": 64 }, "source": { "type": "string", "description": "Woher eine Einwilligung stammt (Plan 5.5: `consents.source`).\n", "enum": [ "api", "double_opt_in", "import" ] }, "evidence": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "purpose", "status" ] }, "minItems": 1, "maxItems": 50 } }, "required": [ "consents" ], "title": "SetConsentsRequest" }, "StoreEventRequest": { "type": "object", "description": "Gesch\u00e4ftsereignis (`POST \/events`, Plan 8.3): `event` ist der Schl\u00fcssel des Event Types, `customer_id` der Kunde\n(`cus_\u2026` oder die externe Kundennummer), `data` die Nutzlast. Ob Event Type, Kunde und Nutzlast passen, entscheidet\nallein {@see RecordBusinessEvent}. Aufgerufen vom {@see EventController}.", "properties": { "event": { "type": "string", "maxLength": 100 }, "customer_id": { "type": "string", "maxLength": 255 }, "data": { "type": "array", "items": { "type": "string" } }, "references": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#\/components\/schemas\/BusinessReferenceType" }, "id": { "type": "string", "maxLength": 255 }, "label": { "type": [ "string", "null" ], "maxLength": 255 }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 } }, "required": [ "type", "id" ] }, "maxItems": 10 }, "client_reference": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "event", "customer_id" ], "title": "StoreEventRequest" }, "TemplatePurpose": { "type": "string", "description": "Zweck eines Templates (Plan 5.8: `templates.purpose`). `layout` ist die H\u00fclle f\u00fcr E-Mails (Kopf, Fu\u00df, Gestaltung); sie wird nie selbst versendet.\n", "enum": [ "transactional", "service", "marketing", "layout" ], "title": "TemplatePurpose" }, "TemplateResource": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "purpose": { "$ref": "#\/components\/schemas\/TemplatePurpose" }, "description": { "type": [ "string", "null" ] }, "published_version": {}, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "$ref": "#\/components\/schemas\/TemplateVersionStatus" }, "published_at": { "type": [ "string", "null" ] } }, "required": [ "version", "status", "published_at" ] } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "key", "name", "purpose", "description", "published_version", "created_at", "updated_at" ], "title": "TemplateResource" }, "TemplateStatusChangedWebhook": { "type": "object", "description": "Template-Status ge\u00e4ndert", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "template.status_changed" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "template": { "$ref": "#\/components\/schemas\/TemplateResource" }, "provider_template": { "type": "object", "description": "Freigabe der WhatsApp-Variante bei Meta, wenn das Ereignis von dort kommt; fehlt bei der Ver\u00f6ffentlichung einer Version.", "properties": { "version": { "type": "integer", "description": "Nummer der Version, deren WhatsApp-Variante sich ge\u00e4ndert hat." }, "locale": { "type": "string", "description": "Sprache der Variante (`de`, `de-AT`)." }, "name": { "type": "string", "description": "Name beim Provider (`_v`)." }, "language": { "type": "string", "description": "Sprachcode beim Provider (`de_AT`)." }, "status": { "type": "string", "description": "Freigabestatus bei Meta.", "enum": [ "pending", "approved", "rejected", "paused", "disabled" ] }, "category": { "type": "string", "description": "Kategorie, die Meta zuordnet und nach der es abrechnet.", "enum": [ "utility", "marketing", "authentication" ] }, "submitted_category": { "type": "string", "description": "Eingereichte Kategorie.", "enum": [ "utility", "marketing", "authentication" ] }, "reclassified": { "type": "boolean", "description": "Meta hat die Kategorie ge\u00e4ndert (`category` \u2260 `submitted_category`) \u2014 das \u00e4ndert die Kosten." }, "rejection_reason": { "type": [ "string", "null" ], "description": "Ablehnungsgrund von Meta." }, "quality_score": { "type": [ "string", "null" ], "description": "Qualit\u00e4tsbewertung (`green`, `yellow`, `red`, `unknown`)." }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "version", "locale", "name", "language", "status", "category", "submitted_category", "reclassified", "rejection_reason", "quality_score", "synced_at" ] } }, "required": [ "template" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "TemplateStatusChangedWebhook" }, "TemplateVersionRequest": { "type": "object", "description": "Inhalt einer Template-Version (`POST \/templates\/{key}\/versions`, `PUT \u2026\/versions\/{n}`): Variablen, Layout und\nVarianten. Form und L\u00e4ngen pr\u00fcft diese Klasse; was ein Template enthalten darf, `SaveTemplateVersion`.", "properties": { "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "type": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "required": { "type": "boolean" }, "example": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "name" ] }, "maxItems": 50 }, "layout": { "type": [ "string", "null" ], "maxLength": 63 }, "postal_layout": { "type": [ "string", "null" ], "maxLength": 63 }, "variants": { "type": "array", "items": { "type": "object", "properties": { "channel": { "$ref": "#\/components\/schemas\/Channel" }, "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" }, "subject": { "type": [ "string", "null" ], "maxLength": 998 }, "body_text": { "type": [ "string", "null" ], "maxLength": 200000 }, "body_html": { "type": [ "string", "null" ], "maxLength": 500000 }, "whatsapp_category": { "anyOf": [ { "$ref": "#\/components\/schemas\/WhatsAppTemplateCategory" }, { "type": "null" } ] }, "whatsapp_components": { "type": [ "array", "null" ], "items": { "type": "array", "items": { "type": "string" } }, "maxItems": 4 } }, "required": [ "channel", "locale" ] }, "minItems": 1, "maxItems": 20 }, "publish": { "type": "boolean" } }, "required": [ "variants" ], "title": "TemplateVersionRequest" }, "TemplateVersionResource": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "$ref": "#\/components\/schemas\/TemplateVersionStatus" }, "variables": { "type": "array", "items": {} }, "layout": { "type": [ "object", "null" ], "properties": { "key": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "key", "version" ] }, "postal_layout": { "type": [ "object", "null" ], "properties": { "key": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "key", "version" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "channel": { "$ref": "#\/components\/schemas\/Channel" }, "locale": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "body_text": { "type": [ "string", "null" ] }, "body_html": { "type": [ "string", "null" ] }, "whatsapp_category": { "anyOf": [ { "$ref": "#\/components\/schemas\/WhatsAppTemplateCategory" }, { "type": "null" } ] }, "whatsapp_components": { "type": [ "array", "null" ], "items": {} }, "provider_templates": { "type": "array", "items": {} } }, "required": [ "channel", "locale", "subject", "body_text", "body_html", "whatsapp_category", "whatsapp_components", "provider_templates" ] } }, "published_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "version", "status", "variables", "layout", "postal_layout", "variants", "published_at", "created_at" ], "title": "TemplateVersionResource" }, "TemplateVersionStatus": { "type": "string", "description": "Zustand einer Template-Version (Plan 5.8: `template_versions.status`). `draft`: noch \u00e4nderbar; `published`: unver\u00e4nderlich und f\u00fcr den Versand freigegeben; `archived`: abgel\u00f6st, bleibt f\u00fcr versendete Nachrichten erhalten.\n", "enum": [ "draft", "published", "archived" ], "title": "TemplateVersionStatus" }, "UploadAttachmentRequest": { "type": "object", "description": "Eine Datei hochladen (`POST \/attachments`, multipart). Gr\u00f6\u00dfe und erlaubte Typen kommen aus {@see AttachmentLimits}.", "properties": { "file": { "type": "string", "format": "binary", "contentMediaType": "application\/octet-stream", "description": "Maximum file size: 16384 kilobytes." } }, "required": [ "file" ], "title": "UploadAttachmentRequest" }, "UpsertCustomerRequest": { "type": "object", "description": "Anlegen oder Aktualisieren \u00fcber `customer_id` (`POST \/customers`): die Stammdaten des\nPatch-Requests plus Kundennummer und Identities und Einwilligungen. Ob der Wert einer Identity g\u00fcltig ist, entscheidet\nallein `NormalizeIdentity` (Action `UpsertContact`).", "properties": { "display_name": { "type": [ "string", "null" ], "maxLength": 255 }, "first_name": { "type": [ "string", "null" ], "maxLength": 255 }, "last_name": { "type": [ "string", "null" ], "maxLength": 255 }, "company": { "type": [ "string", "null" ], "maxLength": 255 }, "locale": { "type": [ "string", "null" ], "maxLength": 16 }, "timezone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Za-z]{2}$" }, "metadata": { "type": [ "array", "null" ], "items": { "type": "string" } }, "customer_id": { "type": "string", "description": "Beginnt sie wie eine \u00f6ffentliche ID, w\u00e4re `{customer}` im Pfad nicht mehr eindeutig (E-06).", "maxLength": 255 }, "identities": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#\/components\/schemas\/IdentityType" }, "value": { "type": "string", "maxLength": 255 }, "address": { "type": "array", "items": { "type": "string" } }, "is_primary": { "type": "boolean" }, "label": { "type": [ "string", "null" ], "maxLength": 32 } }, "required": [ "type" ] }, "maxItems": 50 }, "consents": { "type": "array", "items": { "type": "object", "properties": { "purpose": { "$ref": "#\/components\/schemas\/ConsentPurpose" }, "status": { "$ref": "#\/components\/schemas\/ConsentStatus" }, "channel": { "anyOf": [ { "$ref": "#\/components\/schemas\/Channel" }, { "type": "null" } ] }, "identity_id": { "type": [ "string", "null" ], "maxLength": 64 }, "source": { "type": "string", "description": "Woher eine Einwilligung stammt (Plan 5.5: `consents.source`).\n", "enum": [ "api", "double_opt_in", "import" ] }, "evidence": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "purpose", "status" ] }, "maxItems": 50 } }, "required": [ "customer_id" ], "title": "UpsertCustomerRequest" }, "WebhookDeliveryResource": { "type": "object", "properties": { "id": { "type": "string" }, "webhook_id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "$ref": "#\/components\/schemas\/WebhookEventType" }, "attempt": { "type": "integer" }, "status": { "$ref": "#\/components\/schemas\/WebhookDeliveryStatus" }, "response_status": { "type": [ "integer", "null" ] }, "response_body": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "webhook_id", "event_id", "event_type", "attempt", "status", "response_status", "response_body", "duration_ms", "error", "next_attempt_at", "created_at" ], "title": "WebhookDeliveryResource" }, "WebhookDeliveryStatus": { "type": "string", "description": "Stand eines Zustellversuchs an einen Webhook-Endpoint (Plan 5.10): `pending` ist angesetzt, `succeeded` mit 2xx beantwortet, `failed` gescheitert (ein weiterer Versuch ist angesetzt), `gave_up` endg\u00fcltig aufgegeben.\n", "enum": [ "pending", "succeeded", "failed", "gave_up" ], "title": "WebhookDeliveryStatus" }, "WebhookEndpointResource": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": {} }, "api_version": { "type": "string" }, "status": { "$ref": "#\/components\/schemas\/WebhookEndpointStatus" }, "disabled_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "secret": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "description", "event_types", "api_version", "status", "disabled_reason", "created_at", "updated_at" ], "title": "WebhookEndpointResource" }, "WebhookEndpointStatus": { "type": "string", "description": "Zustand eines Webhook-Endpoints (Plan 5.10). Nur `active` erh\u00e4lt Zustellungen. `disabled` setzt der Tenant selbst, `auto_disabled` die Plattform nach dauerhaften Fehlschl\u00e4gen (Plan 8.4); wieder aktiviert wird beides durch den Tenant.\n", "enum": [ "active", "disabled", "auto_disabled" ], "title": "WebhookEndpointStatus" }, "WebhookEventType": { "type": "string", "description": "Katalog der Ereignistypen, die ein Webhook-Endpoint abonnieren kann (Plan 4.4, 5.10). `*` abonniert alle, auch k\u00fcnftige ({@see self::WILDCARD}); es steht nicht im Katalog. Wer ein Ereignis einf\u00fchrt, das Mandanten per Webhook erreicht, erg\u00e4nzt es hier.\n", "x-extensible-enum": [ "message.created", "message.received", "message.sent", "message.delivered", "message.read", "message.failed", "conversation.created", "conversation.updated", "customer.updated", "customer.merged", "template.status_changed", "channel.updated", "export.ready", "event.completed", "event.failed", "webhook.test" ], "title": "WebhookEventType" }, "WebhookTestWebhook": { "type": "object", "description": "Test-Ereignis", "properties": { "id": { "type": "string", "description": "\u00d6ffentliche ID des Ereignisses (`evt_\u2026`), \u00fcber alle Zustellversuche gleich; entspricht dem Header `webhook-id`." }, "type": { "type": "string", "const": "webhook.test" }, "api_version": { "type": "string", "description": "Version des Payload-Formats, bei Anlage des Endpoints festgeschrieben." }, "created_at": { "type": "string", "format": "date-time", "description": "Zeitpunkt des Ereignisses (UTC); ein Empf\u00e4nger verwirft \u00e4ltere St\u00e4nde anhand dessen." }, "data": { "type": "object", "description": "Vollst\u00e4ndiger aktueller Zustand des Objekts, nicht das Delta.", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "message": { "type": "string" } }, "required": [ "webhook", "message" ] } }, "required": [ "id", "type", "api_version", "created_at", "data" ], "title": "WebhookTestWebhook" }, "WhatsAppTemplateCategory": { "type": "string", "description": "Kategorie eines WhatsApp-Templates (Plan 5.8: `template_variants.whatsapp_category`). Meta rechnet nach ihr ab und kann sie nach der Pr\u00fcfung \u00e4ndern ({@see ProviderTemplateStatus}, `provider_templates.category`).\n", "enum": [ "utility", "marketing", "authentication" ], "title": "WhatsAppTemplateCategory" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }