Importa i record di consenso

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

Importa le accettazioni dei tuoi documenti legali registrate in un altro sistema, per esempio quando sposti gli utenti su KeenAuth. La richiesta è sincrona: da 1 a 500 record vengono scritti in una sola transazione, quindi o vengono scritti tutti o nessuno. Ogni record importato ha method = import, e occurred_at conserva il momento dal sistema di origine. La versione, l'hash del contenuto e la lingua sono ricavati dal documento; non puoi fornirli. I record importati sono solo in aggiunta, come ogni altro record di consenso. Per registrare una singola accettazione ottenuta ora, usa Registra un consenso.

Idempotency-Key è obbligatorio. Un nuovo tentativo con la stessa chiave e la stessa richiesta restituisce la stessa risposta (con Idempotent-Replayed: true) e non scrive nulla una seconda volta.

Richiesta

Corpo JSON (i campi sconosciuti vengono rifiutati con 400 unknown_field):

Campo Tipo Obbligatorio Descrizione
records object[] sì Da 1 a 500 record, scritti in questo ordine.
records[].user_id string sì ID utente (usr_…).
records[].subject_type string sì Solo document.
records[].subject_id string sì ID del documento legale (ldoc_…).
records[].state string sì presented, accepted oppure declined.
records[].application_id string | null no Applicazione (app_…); se omesso e il documento è specifico per applicazione, viene registrata l'applicazione del documento.
records[].occurred_at string (date-time) sì Quando è avvenuto nel sistema di origine; non può essere nel futuro.

Risposta

201 Created con i record scritti (records), nell'ordine di input.

{
  "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"
    }
  ]
}

Errori

HTTP codice Quando
400 malformed_request, unknown_field L'intestazione Idempotency-Key è mancante o malformata, il corpo non è JSON valido oppure contiene un campo sconosciuto.
401 unauthenticated La credenziale è mancante, non valida o revocata.
403 insufficient_permissions La credenziale non ha l'autorizzazione richiesta.
413 payload_too_large Il corpo supera 1 MiB.
415 unsupported_media_type Il tipo di contenuto non è application/json.
422 validation_failed Un record non è valido; errors[].pointer è /records/<index>/<field>. Un utente sconosciuto è unknown_user, un'applicazione sconosciuta unknown_application, un documento sconosciuto unknown_subject; meno di 1 o più di 500 record è out_of_range a /records. Non viene scritto nulla.
422 idempotency_key_reuse La Idempotency-Key è stata usata con una richiesta diversa.
429 rate_limited È stato superato il limite di richieste; riprova dopo il periodo Retry-After.
503 service_unavailable Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo Retry-After.

Esempio

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

Dati personali

Questo endpoint contiene dati personali: record di consenso. Dati personali nelle API di KeenAuth descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene cancellato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.