Zustimmungsdatensätze importieren

POST /v1/jobs/consent-imports · Berechtigung consent-records:write

Importiert Zustimmungen zu Ihren rechtlichen Dokumenten, die in einem anderen System erfasst wurden, zum Beispiel wenn Sie Nutzer zu KeenAuth migrieren. Die Anfrage ist synchron: 1–500 Datensätze werden in einer Transaktion geschrieben, sodass entweder alle oder keiner geschrieben wird. Jeder importierte Datensatz hat method = import, und occurred_at bewahrt die Zeit aus dem Quellsystem. Version, Inhalts-Hash und Locale werden aus dem Dokument übernommen; Sie können sie nicht angeben. Importierte Datensätze sind wie alle anderen Zustimmungsdatensätze nur anfügbar. Um eine einzelne, jetzt eingeholte Zustimmung zu erfassen, verwenden Sie Zustimmung erfassen.

Idempotency-Key ist erforderlich. Ein erneuter Versuch mit demselben Schlüssel und derselben Anfrage liefert dieselbe Antwort (mit Idempotent-Replayed: true) und schreibt kein zweites Mal etwas.

Anfrage

JSON-Body (unbekannte Felder werden mit 400 unknown_field abgelehnt):

Feld Typ Pflicht Beschreibung
records object[] ja 1–500 Datensätze, in dieser Reihenfolge geschrieben.
records[].user_id string ja Nutzer-ID (usr_…).
records[].subject_type string ja Nur document.
records[].subject_id string ja ID des rechtlichen Dokuments (ldoc_…).
records[].state string ja presented, accepted oder declined.
records[].application_id string | null nein Anwendung (app_…); wenn es weggelassen wird und das Dokument anwendungsspezifisch ist, wird die Anwendung des Dokuments erfasst.
records[].occurred_at string (date-time) ja Zeitpunkt im Quellsystem; nicht in der Zukunft.

Antwort

201 Created mit den geschriebenen Datensätzen (records), in Eingabereihenfolge.

{
  "imported_count": 1,
  "records": [
    {
      "id": "crec_01j9xk3m7q8r2s4t6v8w0y2z4b",
      "user_id": "usr_01j9xk3m7q8r2s4t6v8w0y2z4c",
      "subject_type": "document",
      "subject_id": "ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "subject_version": "2026-10",
      "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "locale": "en",
      "state": "accepted",
      "method": "import",
      "application_id": null,
      "occurred_at": "2025-03-14T08:00:00Z"
    }
  ]
}

Fehler

HTTP Code Wann
400 malformed_request, unknown_field Der Header Idempotency-Key fehlt oder ist fehlerhaft, der Body ist kein gültiges JSON oder enthält ein unbekanntes Feld.
401 unauthenticated Die Anmeldedaten fehlen, sind ungültig oder widerrufen.
403 insufficient_permissions Den Anmeldedaten fehlt die erforderliche Berechtigung.
413 payload_too_large Der Body ist größer als 1 MiB.
415 unsupported_media_type Der Inhaltstyp ist nicht application/json.
422 validation_failed Ein Datensatz ist ungültig; errors[].pointer ist /records/<index>/<field>. Ein unbekannter Nutzer ist unknown_user, eine unbekannte Anwendung unknown_application, ein unbekanntes Dokument unknown_subject; weniger als 1 oder mehr als 500 Datensätze sind out_of_range bei /records. Es wird nichts geschrieben.
422 idempotency_key_reuse Der Idempotency-Key wurde mit einer anderen Anfrage verwendet.
429 rate_limited Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach dem Zeitraum Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach dem Zeitraum Retry-After.

Beispiel

curl -X POST https://api.eu.keenauth.com/v1/jobs/consent-imports \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"records":[{"user_id":"usr_01j9xk3m7q8r2s4t6v8w0y2z4c","subject_type":"document","subject_id":"ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a","state":"accepted","occurred_at":"2025-03-14T08:00:00Z"}]}'

CLI: keenauth jobs consent-imports create --data records.json

Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Zustimmungsdatensätze. Personenbezogene Daten in den KeenAuth-APIs beschreibt, was gespeichert wird, wie lange es aufbewahrt wird und wie es gelöscht wird. Senden Sie keine besonderen Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung) in irgendeinem Feld.