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

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

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

## 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

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

## Dati personali

Questo endpoint contiene dati personali: record di consenso. [Dati personali nelle API di KeenAuth](/docs/policies/personal-data) 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.