Importa consentimientos previos

Importa consentimientos previos

Si capturabas consentimientos antes de integrarte con Soyio, migra ese histórico con la API de importación de consentimientos previos.

Cada registro importado genera un consentimiento en Soyio, anclado a su fecha real de captura. También conserva evidencia auditable de tu sistema de origen y queda claramente distinguido de los consentimientos capturados en vivo.

Antes de importar

Antes de preparar el lote, crea y habilita la plantilla de consentimiento que vas a importar. Cada registro necesita consent_template_id y consent_template_version.

Usa la taxonomía para definir categorías y usos de datos, y la guía de plantillas de consentimiento para configurar la plantilla.

La importación es asíncrona: creas un lote, Soyio responde de inmediato con un identificador (cimp_*) y procesa los registros en segundo plano. Consultas el progreso, los contadores y el detalle por registro con un endpoint de estado.

Cómo funciona

1. Crea el lote con POST /consent_imports (JSON inline o archivo CSV/NDJSON). Soyio valida el envelope y responde 202 Accepted con el estado pending.
2. Soyio procesa los registros de forma asíncrona: valida, deduplica y crea cada consentimiento histórico.
3. Consulta el estado con GET /consent_imports/{id} hasta que status sea completed (o failed). La respuesta incluye contadores y el detalle por registro.

Qué pasa después de enviar el lote

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Prepara cada registro

Describe cada consentimiento previo con esta estructura. Usa los mismos campos para JSON, CSV y NDJSON.

Campo	Requerido	Descripción
user_reference o entity_id	Sí (uno)	Identificador del titular. user_reference es tu identificador; entity_id es un token ent_* existente. La entidad se resuelve o se crea automáticamente.
consent_template_id	Sí	Token de la plantilla (constpl_*). Debe existir y estar habilitada.
consent_template_version	Sí	Versión exacta de la plantilla a la que se otorgó el consentimiento (auditable).
origin_event	Sí	Registro o evento fuente del otorgamiento histórico: { system, event_id, occurred_at }. Ver más abajo.
channel	Sí	Canal original: digital, phone_call o in_person.
selected_scopes	No	Subconjunto de scopes de la plantilla. Por defecto, todos los scopes de la plantilla.
scope_selection_behavior	No	replace (por defecto) o additive.
origin	No	Flujo o contexto de producto donde se capturó el consentimiento.
metadata	No	Objeto libre con metadatos de captura o auditoría.

Origen y contexto

Usa estos campos para separar la evidencia de origen del contexto de captura:

Campo	Qué representa
origin_event	Registro o evento del sistema de origen que representa el otorgamiento histórico. Soyio lo usa para deduplicar y para fijar la fecha real de captura.
channel	Canal donde se capturó el consentimiento: digital, phone_call o in_person.
origin	Flujo o contexto de producto donde ocurrió la captura, por ejemplo web_signup, branch_onboarding o call_center.
metadata	Detalles libres de auditoría o captura, como campaña, id del checkbox, operador o fila del archivo fuente.

Registro con contexto de captura

{
  "user_reference": "user-123",
  "consent_template_id": "constpl_1B2M2Y8AsgTpgAmY7PhCfg",
  "consent_template_version": 1,
  "origin_event": {
    "system": "legacy_crm",
    "event_id": "row-00042",
    "occurred_at": "2022-03-15T12:00:00Z"
  },
  "channel": "digital",
  "origin": "web_signup",
  "metadata": {
    "campaign": "newsletter-2022",
    "checkbox_id": "marketing-opt-in"
  }
}

origin_event e idempotencia

origin_event identifica el evento o registro del sistema de origen que representa el otorgamiento histórico. No describe el lote de importación. Ancla la fidelidad histórica y la idempotencia del registro:

Campo	Descripción
system	Sistema de origen del registro (por ejemplo, legacy_crm).
event_id	Identificador del registro original en tu sistema.
occurred_at	Fecha real de captura del consentimiento, en ISO-8601. No puede ser futura.

La clave de idempotencia es system:event_id. Si reintentas un lote (o vuelves a enviar un registro ya importado), Soyio lo omite (skipped_duplicate) en lugar de duplicarlo. Así puedes reintentar la importación sin crear consentimientos duplicados.

occurred_at cumple el rol de "fecha de otorgamiento": Soyio ancla a esa fecha el created_at y la expiración (expires_at = occurred_at + duración de la plantilla) del consentimiento, su agreement y su evidencia. Así, el histórico queda fiel: el orden, la expiración y los filtros por fecha son correctos.

Crea una importación

JSON inline

curl -X POST https://api.soyio.id/v1/consent_imports \
  -H "Authorization: Bearer $SOYIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_system": "legacy_crm",
    "consents": [
      {
        "user_reference": "user-123",
        "consent_template_id": "constpl_1B2M2Y8AsgTpgAmY7PhCfg",
        "consent_template_version": 1,
        "origin_event": {
          "system": "legacy_crm",
          "event_id": "row-00042",
          "occurred_at": "2022-03-15T12:00:00Z"
        },
        "channel": "digital",
        "origin": "web_signup",
        "metadata": { "campaign": "newsletter-2022", "checkbox_id": "marketing-opt-in" }
      }
    ]
  }'

source_system en el envelope es el valor por defecto para los registros que no especifican origin_event.system. Por defecto, la importación no activa webhooks ni workflows basados en eventos. Si necesitas reproducir los eventos hacia consumidores externos, envía broadcast_events: true.

Archivo CSV

Envía un archivo multipart/form-data con una fila por registro. Los campos de origin_event se aplanan como origin_event_system, origin_event_id y origin_event_occurred_at.

consents.csv

user_reference,consent_template_id,consent_template_version,origin_event_system,origin_event_id,origin_event_occurred_at,channel
user-123,constpl_1B2M2Y8AsgTpgAmY7PhCfg,1,legacy_crm,row-00042,2022-03-15T12:00:00Z,digital

curl -X POST https://api.soyio.id/v1/consent_imports \
  -H "Authorization: Bearer $SOYIO_API_KEY" \
  -F "file=@consents.csv" \
  -F "input_format=csv" \
  -F "source_system=legacy_crm" \
  -F "broadcast_events=false"

Archivo NDJSON

Una línea JSON por registro (mismo esquema que el JSON inline):

consents.ndjson

{"user_reference":"user-123","consent_template_id":"constpl_1B2M2Y8AsgTpgAmY7PhCfg","consent_template_version":1,"origin_event":{"system":"legacy_crm","event_id":"row-00042","occurred_at":"2022-03-15T12:00:00Z"},"channel":"digital"}

curl -X POST https://api.soyio.id/v1/consent_imports \
  -H "Authorization: Bearer $SOYIO_API_KEY" \
  -F "file=@consents.ndjson" \
  -F "input_format=ndjson"

Recibes una respuesta 202 Accepted:

{
  "consent_import": {
    "id": "cimp_1B2M2Y8AsgTpgAmY7PhCfg",
    "status": "pending",
    "input_format": "json",
    "source_system": "legacy_crm",
    "records_count": null,
    "accepted_count": 0,
    "rejected_count": 0,
    "skipped_count": 0
  }
}

Consulta el estado

curl https://api.soyio.id/v1/consent_imports/cimp_1B2M2Y8AsgTpgAmY7PhCfg \
  -H "Authorization: Bearer $SOYIO_API_KEY"

{
  "consent_import": {
    "id": "cimp_1B2M2Y8AsgTpgAmY7PhCfg",
    "status": "completed",
    "records_count": 3,
    "accepted_count": 2,
    "rejected_count": 1,
    "skipped_count": 0,
    "record_results": [
      { "index": 0, "identifier": "legacy_crm:row-00042", "status": "accepted", "consent_commit_token": "ccom_..." },
      { "index": 1, "identifier": "legacy_crm:row-00043", "status": "imported_expired", "warnings": ["consent was already expired at import time"] },
      { "index": 2, "identifier": "legacy_crm:row-00044", "status": "rejected", "errors": ["consent_template constpl_x version 2 was not found"] }
    ]
  }
}

Interpreta los estados por registro

status	Significado
accepted	Importado y aplicado al estado de consentimiento del titular.
imported_expired	Importado, pero su expiración cae en el pasado (consentimiento histórico ya vencido). Se reporta con warnings.
imported_superseded	Registrado como evidencia histórica, pero no aplicado al estado activo porque un evento posterior (por ejemplo, una revocación más reciente) ya removió el permiso.
skipped_duplicate	El origin_event ya había sido importado. No se duplica.
rejected	No superó la validación. Revisa errors.

Lotes grandes

Para lotes muy grandes, el detalle completo por registro se entrega en un archivo descargable vía error_report_url, y record_results incluye sólo una muestra de los registros con problemas.

Qué valida Soyio

Cada registro se valida de forma independiente; un registro inválido no afecta al resto del lote. Los mensajes de error son accionables:

• origin_event.system, origin_event.event_id y origin_event.occurred_at son obligatorios; occurred_at debe ser una fecha válida y no futura.
• user_reference o entity_id debe estar presente.
• La plantilla (consent_template_id + consent_template_version) debe existir y estar habilitada.
• selected_scopes debe ser un subconjunto de los scopes de la plantilla.
• channel debe ser digital, phone_call o in_person.

Cómo identificar consentimientos importados

Los consentimientos importados se marcan con imported: true y source_system, y exponen la fecha original de captura en su evidencia. En el dashboard se muestran con una etiqueta Importado y los campos de origen, para que un auditor pueda distinguirlos de los capturados en vivo vía widget.

Referencia de la API

• POST /consent_imports — crea una importación.
• GET /consent_imports/{id} — consulta el estado de una importación.
• GET /consent_imports — lista las importaciones.

Consulta la Referencia de la API para el detalle completo de cada endpoint.