# 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](/docs/api/management/users/create-consent-record).

`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.

```json
{
  "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

```bash
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](/docs/policies/personal-data) 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.