# Importar registros de consentimiento

`POST /v1/jobs/consent-imports` · permiso `consent-records:write`

Importa las aceptaciones de sus documentos legales que se registraron en otro sistema, por ejemplo cuando traslada usuarios a KeenAuth. La solicitud es síncrona: de 1 a 500 registros se escriben en una sola transacción, de modo que se escriben todos o ninguno. Cada registro importado tiene `method = import`, y `occurred_at` conserva la hora del sistema de origen. La versión, el hash del contenido y el idioma se toman del documento; usted no puede proporcionarlos. Los registros importados son de solo adición, como cualquier otro registro de consentimiento. Para registrar una única aceptación obtenida ahora, use [Registrar un consentimiento](/docs/api/management/users/create-consent-record).

`Idempotency-Key` es obligatorio. Un reintento con la misma clave y la misma solicitud devuelve la misma respuesta (con `Idempotent-Replayed: true`) y no escribe nada una segunda vez.

## Solicitud

Cuerpo JSON (los campos desconocidos se rechazan con `400 unknown_field`):

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `records` | object[] | sí | De 1 a 500 registros, escritos en este orden. |
| `records[].user_id` | string | sí | ID del usuario (`usr_…`). |
| `records[].subject_type` | string | sí | Solo `document`. |
| `records[].subject_id` | string | sí | ID del documento legal (`ldoc_…`). |
| `records[].state` | string | sí | `presented`, `accepted` o `declined`. |
| `records[].application_id` | string \| null | no | Aplicación (`app_…`); si se omite y el documento es específico de una aplicación, se registra la aplicación del documento. |
| `records[].occurred_at` | string (date-time) | sí | Cuándo ocurrió en el sistema de origen; no puede ser futura. |

## Respuesta

`201 Created` con los registros escritos (`records`), en el orden de entrada.

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

## Errores

| HTTP | código | Cuándo |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Falta el encabezado `Idempotency-Key` o está mal formado, el cuerpo no es JSON válido o tiene un campo desconocido. |
| 401 | `unauthenticated` | Falta la credencial, no es válida o fue revocada. |
| 403 | `insufficient_permissions` | La credencial no tiene el permiso requerido. |
| 413 | `payload_too_large` | El cuerpo supera 1 MiB. |
| 415 | `unsupported_media_type` | El tipo de contenido no es `application/json`. |
| 422 | `validation_failed` | Un registro no es válido; `errors[].pointer` es `/records/<index>/<field>`. Un usuario desconocido da `unknown_user`, una aplicación desconocida `unknown_application` y un documento desconocido `unknown_subject`; menos de 1 o más de 500 registros da `out_of_range` en `/records`. No se escribe nada. |
| 422 | `idempotency_key_reuse` | La `Idempotency-Key` se usó con una solicitud diferente. |
| 429 | `rate_limited` | Se superó el límite de frecuencia; reintente después del período `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente después del período `Retry-After`. |

## Ejemplo

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

## Datos personales

Este endpoint contiene datos personales: registros de consentimiento. [Datos personales en las API de KeenAuth](/docs/policies/personal-data) describe qué se almacena, durante cuánto tiempo se conserva y cómo se elimina. No envíe categorías especiales de datos personales (salud, datos biométricos, religión, opiniones políticas, orientación sexual) en ningún campo.