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.

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.

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

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