> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Einwilligungsmanagement und Nachweise > Erfassen, abrufen und prüfen kanalbezogene Messaging-Einwilligungen in Orbit — einschließlich DSGVO-Zuordnung der Rechtsgrundlage und von Indiens DPDP-Consent-Manager signierter Nachweise. # Einwilligungsmanagement und Nachweise Bevor Sie einem Kontakt auf einem regulierten Kanal eine Nachricht senden, benötigen Sie in der Regel eine Rechtsgrundlage — meist eine **Einwilligung**. Die Einwilligungs-API von Orbit ist das führende System dafür, wer auf welchem Kanal wann und auf welcher Rechtsgrundlage ein- oder ausgestiegen ist. Jeder Schreibvorgang wird auf die Speicher verteilt, gegen die Ihre Sendevorgänge geprüft werden — das Erfassen einer Einwilligung hier gibt also die Nachricht tatsächlich frei (oder blockiert sie). Sie können zudem [den gesamten Verlauf exportieren](#den-einwilligungsnachweis-exportieren) als auditfähige CSV- oder JSON-Datei. Alle folgenden Endpunkte sind unter `https://api.orbit.devotel.io/api/v1/compliance` beheimatet. Das Erfassen einer Einwilligung in Orbit schafft einen auditfähigen Verlauf, macht einen Versand jedoch nicht allein dadurch rechtmäßig. Sie bleiben für das Einholen einer wirksamen Einwilligung und für die von Ihnen versendeten Inhalte verantwortlich. Diese Seite ist keine Rechtsberatung. *** ## Kanäle und Zustände Die Einwilligung wird **pro Kanal** erfasst. Das unterstützte Kanalset umfasst: `email`, `fax`, `instagram`, `line`, `messenger`, `push`, `rcs`, `sms`, `viber`, `voice`, `whatsapp`. Ein Paar `(contact, channel)` nimmt einen von drei Zuständen an: | Zustand | Bedeutung | | ----------- | -------------------------------------------------------------------------------------------------- | | `opted_in` | Einwilligung erteilt und nicht widerrufen. | | `opted_out` | Einwilligung widerrufen oder ein expliziter Opt-out erfasst. | | `unknown` | Für das Paar liegt kein Einwilligungsdatensatz vor — Ihr Sende-Gate entscheidet über den Standard. | *** ## Einwilligungen erfassen `POST /compliance/consent` erfasst einen Opt-in oder Opt-out über einen oder mehrere Kanäle in einem einzigen Aufruf. Identifizieren Sie den Kontakt über `contact_id` **oder** über `identifier` (eine E-Mail, eine E.164-Telefonnummer oder eine WhatsApp-ID — Orbit erkennt den Typ automatisch). ```bash theme={null} curl -X POST https://api.orbit.devotel.io/api/v1/compliance/consent \ -H "Authorization: Bearer $ORBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "identifier": "jordan@example.com", "channels": ["email", "sms"], "opt_in": true, "source": "web_form", "consent_type": "marketing", "lawful_basis": "consent", "purpose": "Weekly product newsletter and order updates", "consent_text_version": "tos-2026-04", "consent_proof_url": "https://example.com/proofs/abc123.png" }' ``` Rückgabe `201 Created`: ```json theme={null} { "contact_id": "cnt_9f…", "consent_record_ids": ["cr_a1…", "cr_b2…"], "channels": ["email", "sms"], "state": "opted_in", "valid_until": null } ``` | Feld | Typ | Hinweise | | --------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `contact_id` / `identifier` | string | Geben Sie eines der beiden an. | | `channels` | string\[] | Einer oder mehrere aus dem Kanalset; dedupliziert und sortiert. | | `opt_in` | boolean | **Erforderlich.** `true` = Opt-in, `false` = Opt-out. | | `source` | string | Wie die Einwilligung erfasst wurde (z. B. `web_form`, `import`, `double_opt_in`). Standard `consent_api`. | | `consent_type` | string | Zweckkategorie, z. B. `marketing`, `transactional`. Standard `messaging`. | | `lawful_basis` | enum | Rechtsgrundlage nach Art. 6 DSGVO: `consent`, `contract`, `legal_obligation`, `vital_interests`, `public_task`, `legitimate_interests`. | | `purpose` | string | Freitext zur Beschreibung der Verwendung (≤ 500). | | `consent_text_version` | string | Version des Hinweistextes, dem die betroffene Person zugestimmt hat. | | `consent_proof_url` | string (url) | Link zu einem Screenshot oder signierten Dokument. | | `valid_until` | string (ISO-8601 UTC) | Absoluter Zeitpunkt, zu dem die Einwilligung abläuft. Nur bei Opt-in — wird bei Opt-out ignoriert. Schließt `expires_in_days` aus. | | `expires_in_days` | integer | Relatives Gültigkeitsfenster (1–3650 Tage ab jetzt). Nur bei Opt-in. Schließt `valid_until` aus. | | `metadata` | object | Beliebige benutzerdefinierte Schlüssel/Werte. | Die Angabe **beider** Werte `valid_until` und `expires_in_days` ist mehrdeutig und wird mit `422 VALIDATION_ERROR` abgelehnt. Wenn Sie ein Zeitfenster setzen, gibt die `201`-Antwort das aufgelöste `valid_until` (den absoluten Ablaufzeitpunkt) zurück; bei einer nicht ablaufenden Einwilligung oder einem Opt-out ist es `null`. Das erneute Erfassen eines Opt-ins mit einem neuen Zeitfenster **verlängert** die Gültigkeit — der ursprüngliche `granted_at`-Wert bleibt erhalten, der Ablaufzeitpunkt wird jedoch aktualisiert. **Was ein Schreibvorgang bewirkt.** Jeder erfasste Kanal aktualisiert vier synchronisierte Speicher: die Audit-Tabelle `consent_records`, den Spiegel `channel_preferences` des Kontakts (den schnellen Lese-Pfad, den Ihre Sendevorgänge prüfen), die `suppression_list` (bei Opt-out) sowie einen kurzlebigen Redis-STOP-Blocker, damit laufende Kampagnen-Batches die Änderung innerhalb von ca. 10 Minuten berücksichtigen. Schreibvorgänge sind **teilsicher**: Schlägt ein Kanal fehl, gelten die anderen weiterhin. Vergleichen Sie `consent_record_ids.length` mit der Anzahl der angeforderten Kanäle, um einen Teilschreibvorgang zu erkennen. Das erneute Erfassen eines Opt-ins für einen bereits aktiven Kanal aktualisiert die Metadaten/den Nachweis, **behält aber den ursprünglichen `granted_at` bei**. *** ## Einwilligungen abrufen `GET /compliance/consent/lookup` gibt den aktuellen Zustand für ein `(contact, channel)`-Paar zurück — verwenden Sie ihn als Prüfung vor dem Versand. ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/compliance/consent/lookup?identifier=jordan@example.com&channel=sms" \ -H "Authorization: Bearer $ORBIT_API_KEY" ``` ```json theme={null} { "contact_id": "cnt_9f…", "channel": "sms", "state": "opted_in", "source": "web_form", "granted_at": "2026-04-02T10:11:00.000Z", "revoked_at": null, "lawful_basis": "consent", "purpose": "Weekly product newsletter and order updates", "consent_text_version": "tos-2026-04", "consent_proof_url": "https://example.com/proofs/abc123.png", "valid_until": null, "expired": false, "requires_reconfirmation": false } ``` Ein `state` von `unknown` bedeutet, dass für das Paar kein Datensatz existiert — Ihre Anwendung entscheidet, ob dies eine Einwilligung impliziert (einige Transaktionsabläufe) oder den Versand blockiert (die meisten Marketingabläufe). Die letzten drei Felder melden zeitlich begrenzte Einwilligungen und sind **immer vorhanden**: | Feld | Typ | Hinweise | | ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `valid_until` | string \| null | Der Ablaufzeitpunkt der Einwilligung oder `null`, wenn die Einwilligung nie abläuft (oder das Paar abgemeldet ist). | | `expired` | boolean | `true`, wenn die Einwilligung aktiv ist, ihr `valid_until` jedoch in der Vergangenheit liegt. Behandeln Sie eine abgelaufene Einwilligung an Ihrem Sende-Gate als nicht mehr eingewilligt. | | `requires_reconfirmation` | boolean | Spiegelt `expired` — ein Hinweis, einen Re-Permission-Prozess auszulösen. Setzen Sie den Wert zurück, indem Sie einen neuen Opt-in erfassen (optional mit einem neuen Zeitfenster). | *** ## Ablaufende Einwilligungen finden `GET /compliance/consent/expiring` durchsucht den Mandanten nach Opt-ins, deren Gültigkeitsfenster abgelaufen ist oder bald abläuft — die Grundlage für eine Re-Permission-Kampagne (erneute Bestätigung). Es werden nur Einwilligungen mit einem `valid_until` zurückgegeben; nicht ablaufende Einwilligungen erscheinen nie. ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/compliance/consent/expiring?within_days=30&status=all" \ -H "Authorization: Bearer $ORBIT_API_KEY" ``` Abfrageparameter: | Parameter | Typ | Hinweise | | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `within_days` | integer | Vorausschau-Horizont (0–3650, Standard 30). Gibt Einwilligungen zurück, deren `valid_until` bei oder vor jetzt + `within_days` liegt; bereits abgelaufene Einwilligungen sind immer enthalten. | | `channel` | enum | Optional — auf einen einzelnen Kanal einschränken. | | `status` | enum | `all` (Standard), `expired` (bereits nach `valid_until`) oder `expiring` (noch gültig, aber innerhalb des Horizonts). | | `limit` | integer | Seitengröße (1–100, Standard 50). | | `cursor` | string | Opaker Paginierungs-Cursor — unverändert zurücksenden. | ```json theme={null} { "within_days": 30, "channel": null, "status": "all", "as_of": "2026-05-01T09:00:00.000Z", "items": [ { "id": "cr_b2…", "contact_id": "cnt_9f…", "channel": "sms", "consent_type": "marketing", "source": "web_form", "lawful_basis": "consent", "granted_at": "2025-05-02T10:11:00.000Z", "valid_until": "2026-04-20T00:00:00.000Z", "expired": true, "status": "expired", "requires_reconfirmation": true } ], "next_cursor": null } ``` Die Einträge sind so sortiert, dass die am frühesten ablaufenden zuerst kommen. Jeder trägt einen `status` (`expired` oder `expiring`), sodass Sie zwischen „jetzt erneut bestätigen" und „vor Ablauf des Fensters warnen" unterscheiden können. Die erneute Bestätigung ist ein gewöhnlicher Opt-in per `POST /compliance/consent` — optional mit einem neuen `valid_until` oder `expires_in_days`. Behandeln Sie `next_cursor` als opak und senden Sie ihn unverändert zurück; ein `null`-Wert bedeutet die letzte Seite. Ein ungültiger oder veralteter Cursor wird als neue erste Seite behandelt und löst keinen Fehler aus. *** ## Bestätigte Einwilligungen (Double-Opt-in-Handshakes) Ein einfaches `POST /compliance/consent` dokumentiert die Einwilligung — es ist das führende System, sobald Ihre eigene Oberfläche die Einwilligung eingeholt hat. Wenn die Beweisstufe eine erfasste **Antwort des Empfängers** erfordert (ausdrückliche schriftliche Einwilligung nach TCPA, bestätigter Opt-in in der EU, 10DLC-Kampagnenprüfung), verwenden Sie stattdessen den verwalteten **Double-Opt-in-Handshake**: 1. `POST /compliance/consent/double-opt-in` — **Start**: erfasst eine Zeile im Status *pending* (noch keine Einwilligung) und gibt den Bestätigungstext für das Paar zurück. 2. Der Empfänger antwortet; leiten Sie den Text an `POST /compliance/consent/double-opt-in/confirm` weiter — **Bestätigung**: Ein zustimmendes Schlüsselwort zur ausstehenden Aufforderung wandelt das Paar in eine bestätigte `opted_in`- Einwilligung um. 3. `GET /compliance/consent/double-opt-in/status` — **Lesen**: der aktuelle Zustand (`opted_in` | `opted_out` | `pending` | `none`) sowie die Flags `confirmed` / `awaiting_reply`, ohne Nebenwirkungen. Bestätigte Handshakes landen im selben Einwilligungsregister, das diese Seite dokumentiert — `/lookup`, `/history` und der Export lesen sie identisch. Bis zur Bestätigung ist ein ausstehender Handshake keine Einwilligung. Mandanteneigen: Nichts startet einen Handshake im Namen der Plattform. Die vollständigen Mechanismen finden Sie unter [Bestätigte Einwilligungen (Double-Opt-in-Handshakes)](/compliance/double-opt-in). *** ## Einwilligungsverlauf `GET /compliance/consent/history` gibt den vollständigen, paginierten Prüfpfad für einen Kontakt zurück — jede Erteilung und jeder Widerruf, die neuesten zuerst. Abfrageparameter: `contact_id` oder `identifier` (eines erforderlich), ein optionaler `channel`-Filter, `limit` (≤ 100, Standard 50) und ein opaker `cursor`. ```json theme={null} { "contact_id": "cnt_9f…", "channel": null, "items": [ { "id": "cr_b2…", "channel": "sms", "consent_state": "opted_in", "granted": true, "source": "web_form", "granted_at": "2026-04-02T10:11:00.000Z", "revoked_at": null, "lawful_basis": "consent", "created_at": "2026-04-02T10:11:00.000Z" } ], "next_cursor": "eyJ0…" } ``` Behandeln Sie `next_cursor` als opak — senden Sie ihn unverändert zurück, um die nächste Seite abzurufen. Ein ungültiger oder veralteter Cursor wird als neue erste Seite behandelt und löst keinen Fehler aus. *** ## Den Einwilligungsnachweis exportieren `GET /compliance/consent/export` lädt den mandantenweiten Einwilligungsverlauf als einzelne Datei herunter — die Antwort auf ein TCPA-Audit, die Beweislast nach Art. 7 Abs. 1 DSGVO oder eine Offenlegungsanfrage („zeigen Sie, wer wann auf welchem Kanal und aus welcher Quelle ein- oder ausgestiegen ist"). Er ist das Massen-Gegenstück zu `/lookup` und `/history`. ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/compliance/consent/export?format=csv&state=opted_out" \ -H "Authorization: Bearer $ORBIT_API_KEY" \ -o consent-proof-of-record.csv ``` Abfrageparameter: | Parameter | Typ | Hinweise | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `format` | enum | `csv` (Standard — RFC-4180, kann in einer Tabellenkalkulation geöffnet werden) oder `json`. | | `channel` | enum | Auf einen Kanal einschränken. | | `state` | enum | `all` (Standard), `opted_in`, `opted_out` oder `unknown`. | | `contact_id` | string | Schränkt den Export auf einen einzelnen Kontakt ein — die Form einer Offenlegungsanfrage. | | `from` / `to` | string | Datumsbereich über `created_at` des Datensatzes. Akzeptiert ein reines Datum im Format `YYYY-MM-DD` oder einen RFC-3339-Zeitstempel. | | `limit` | integer | Anzahl der Zeilen (1–50.000, Standard 50.000). | Jede Zeile enthält ein Einwilligungsereignis, verknüpft mit den Identifikatoren des Kontakts — `record_id`, `contact_id`, `email`, `phone`, `whatsapp_id`, `channel`, `consent_state`, `granted`, `consent_type`, `source` — sowie die Spalten zur Beweislast nach DSGVO `lawful_basis`, `purpose`, `policy_template`, `consent_text_version`, `consent_proof_url`, `ip_address`, `valid_until` und die Zeitstempel für Erteilung/Widerruf/Aktualisierung. CSV-Downloads erhalten einen datierten Dateinamen (`consent-proof-of-record-YYYY-MM-DD.csv`) und werden nie über einen Lesecache ausgeliefert (`Cache-Control: no-store`). Bei `format=json` liefert die Antwort stattdessen eine Hülle mit `columns` / `items` / `count` — dieselben Daten für programmatische Verbraucher. Der Zugriff ist auf **Owner**- und **Admin**-Schlüssel beschränkt — die Nutzdaten legen mandantenweit rohe Empfänger-Identifikatoren offen, dieselbe Vertrauensstufe wie beim Suppression-Import. Jeder Exportlauf wird selbst mit seinen Filtern und der Zeilenzahl in das Audit-Log geschrieben. Überschreitet Ihr Register 50.000 Zeilen, wird der Export an der Obergrenze abgeschnitten: CSV-Antworten tragen den Header `X-Export-Truncated: true`, und die JSON-Hülle setzt `truncated: true`. Grenzen Sie nach Kanal oder Status ein oder paginieren Sie, indem Sie aufeinanderfolgende Datumsfenster mit `from`/`to` exportieren. *** Indiens **Digital Personal Data Protection Act (DPDP)** führt das Konzept eines **Consent Managers** ein — eines rechenschaftspflichtigen, registrierten Vermittlers, der im Namen einer betroffenen Person kryptografisch **signierte Einwilligungsnachweise** ausstellt. Orbit kann die Manager registrieren, die Ihre Nutzer verwenden, und die von ihnen ausgestellten Nachweise prüfen. ### Einen Consent Manager registrieren `POST /compliance/consent/managers` (Admin/Owner) registriert einen Manager und speichert dessen öffentlichen Schlüssel (einen ECDSA-P-256-SPKI-PEM), mit dem jeder von ihm signierte Nachweis geprüft wird. ```bash theme={null} curl -X POST https://api.orbit.devotel.io/api/v1/compliance/consent/managers \ -H "Authorization: Bearer $ORBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Consent Manager", "manager_id": "acme-cm-001", "manager_url": "https://cm.acme.example", "public_key": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----", "country_code": "IN" }' ``` * `GET /compliance/consent/managers` listet registrierte Manager (aktive zuerst). * `PUT /compliance/consent/managers/{id}` aktualisiert oder deaktiviert einen (Teilaktualisierung; alle Felder optional). ### Einen signierten Nachweis speichern `POST /compliance/consent/receipts` prüft einen von einem Manager signierten Nachweis und speichert ihn als Einwilligung. Die Signatur (ECDSA P-256 / SHA-256, IEEE-P1363, base64url) wird anhand des öffentlichen Schlüssels des registrierten Managers über eine an JCS angelehnte JSON-Kanonisierung der Nutzdaten mit sortierten Schlüsseln geprüft, **bevor** etwas gespeichert wird. Diese Kanonisierung sortiert Objektschlüssel aufsteigend nach UTF-16-Codeeinheit und entfernt unwesentlichen Leerraum, ist jedoch keine vollständige RFC-8785-Implementierung — insbesondere wendet sie die von JCS vorgeschriebenen Regeln zur Zahlenserialisierung nicht an. Signieren Sie Nachweise mit derselben Form sortierter Schlüssel, die Orbit verwendet, statt davon auszugehen, dass ein spezifikationsvollständiger RFC-8785-Prüfer einen übereinstimmenden Hash erzeugt. ```bash theme={null} curl -X POST https://api.orbit.devotel.io/api/v1/compliance/consent/receipts \ -H "Authorization: Bearer $ORBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact_id": "cnt_9f…", "consent_manager_id": "acme-cm-001", "channel": "sms", "consent_type": "marketing", "receipt": { "receipt_id": "rcpt_77…", "issued_at": "2026-05-01T09:00:00.000Z", "purpose": "Promotional SMS", "fiduciary_id": "fid_acme", "signature": "MEUCIQ…", "payload": { "…": "…" } } }' ``` Rückgabe `201` mit `{ "id": …, "receipt_id": …, "verified": true }`. Eine ungültige Signatur oder ein nicht registrierter/inaktiver Manager liefert `422 CONSENT_RECEIPT_INVALID` — das Detail weist darauf hin, dass die Nutzdaten manipuliert worden sein können oder der Manager die Schlüssel rotiert hat. ### Einen gespeicherten Nachweis erneut prüfen `POST /compliance/consent/receipts/{id}/verify` prüft einen zuvor gespeicherten Nachweis erneut anhand des **aktuellen** Schlüssels des Managers — verwenden Sie dies während eines Audits, um zu bestätigen, dass ein Nachweis weiterhin gültig ist und ob sein Manager aktiv bleibt. `{id}` akzeptiert entweder die ID des Einwilligungsdatensatzes oder die `receipt_id`. Einwilligungsnachweise setzen die Mandantenmigration `consent_managers` voraus. Bei Mandanten ohne diese Migration degradieren die Lesepfade kontrolliert: Die Managerliste gibt eine leere Liste zurück, und der Re-Verify-Endpunkt liefert `404`. Das Ausstellen eines Nachweises ist fail-closed, daher liefert `POST /compliance/consent/receipts` bei Mandanten ohne Migration `422 CONSENT_RECEIPT_INVALID`, statt zu degradieren — führen Sie die Migration aus, bevor Sie Nachweise ausstellen. *** ## Weiterführende Referenzen * [Ein DSGVO-Posture von Anfang bis Ende aufbauen](/compliance/gdpr-posture-guide) — die Abfolge, die diese Einwilligungsebene speist. * [Bestätigte Einwilligungen (Double-Opt-In-Handshakes)](/compliance/double-opt-in) — der Beginn/Bestätigen/Status-Ablauf oberhalb eines einfachen Einwilligungsdatensatzes. * [Einwilligungs-Posture: Die Richtlinien für unbekannte Einwilligung](/compliance/consent-default-policy) — die organisationsweiten Regler, die bestimmen, was Kontakte ohne Register-Eintrag empfangen dürfen (Marketing-Versand vs. CDP-Fanout). * [Opt-Out & Suppressionslisten](/compliance/opt-out-suppression) — Massenimport von Opt-outs und wie die Suppressionsliste Sendevorgänge steuert. * [DSAR](/compliance/dsar) — Bearbeitung von Auskunfts-/Löschanträgen über den Einwilligungsdatensatz. * [DLT-India-Onboarding](/compliance/dlt-india) — die Registrierungsebene, die DPDP-Einwilligungen bei indischen SMS ergänzt. * [API-Referenz → Compliance](/api-reference/endpoints/compliance) — vollständige Anfrage-/Antwortschemas (aus der Live-API neu generiert).