Exportaciones de datos

Cuando necesitas extraer miles de registros, por ejemplo para alimentar tu data warehouse o auditar consentimientos, recorrer los endpoints de listado página por página es lento y costoso. La API de exportaciones lo resuelve con una sola solicitud: creas una exportación, Soyio genera el archivo en segundo plano y te avisa por webhook cuando está listo para descargar.

Cómo funciona

Crea la exportación con POST /api/v1/exports, indicando el recurso y los filtros.
Soyio procesa en segundo plano y genera un archivo CSV o JSON, opcionalmente empaquetado como ZIP.
Recibes el evento export.completed en tu webhook, o consultas el estado con GET /api/v1/exports/{id}.
Descargas el archivo desde download_url.

Por defecto, download_url siempre conserva el formato solicitado en output_format. Si prefieres dividir el resultado en archivos de hasta 50.000 registros, envía "packaging": "zip"; Soyio entregará un .zip con partes numeradas y un manifest.json.

Recursos disponibles

Recurso	Contenido	Permisos requeridos
`consent_actions`	Acciones de consentimiento individuales	`exports.api.write` y `consent.api.read`
`consent_commits`	Commits de consentimiento con sus acciones	`exports.api.write` y `consent.api.read`
`consent_form_entries`	Respuestas y consentimientos enviados mediante formularios	`exports.api.write` y `consent_form_entries.api.read`
`validation_attempts`	Reportes de conversión, fallas o reintentos de validación	`exports.api.write` y `validation_attempts.api.read`
`disclosure_requests`	Solicitudes de divulgación con la misma estructura de la API	`exports.api.write` y `disclosure_requests.api.read`
`agreements`	Acuerdos, incluyendo todas sus versiones	`exports.api.write` y `agreements.api.read`
`evidences`	Evidencias asociadas a los acuerdos	`exports.api.write` y `agreements.api.read`

Los permisos aplican tanto para crear como para consultar: una credencial sin el permiso de lectura del recurso no verá esas exportaciones al listarlas ni al consultar su estado.

Una exportación de agreements incluye todas las versiones de cada acuerdo. Si solo necesitas las versiones vigentes, filtra con {"latest":{"=":true}}. Revisa Acuerdos y permisos para entender el versionado.

Para validation_attempts, envía también report_kind con conversion, failures o retries. Cada exportación contiene un solo tipo de recurso, por lo que los intentos de validación relacionados con disclosure requests se solicitan en una exportación independiente.

Crea una exportación

curl -X POST \
  https://app.soyio.id/api/v1/exports \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "agreements",
    "output_format": "json",
    "where": "{\"latest\":{\"=\":true}}"
  }'

La API responde 202 Accepted con la exportación en estado pending:

{
  "export": {
    "id": "exp_1B2M2Y8AsgTpgAmY7PhCfg",
    "resource_kind": "agreements",
    "report_kind": null,
    "output_format": "json",
    "status": "pending",
    "records_count": null,
    "error_message": null,
    "file_name": null,
    "download_url": null,
    "created_at": "2026-06-11T15:30:00Z",
    "completed_at": null
  }
}

Los parámetros where y order_by aceptan el mismo formato que los endpoints de listado. Revisa Paginación y filtros para conocer los operadores disponibles.

Este endpoint acepta resource, report_kind, output_format, packaging, where y order_by. Ignora silenciosamente cualquier otro campo.

resource es el único campo obligatorio. Si lo omites, la API responde 400. Si envías un valor no válido en un campo con opciones fijas, como resource u output_format, responde 422.

Revisa la referencia del API para Crear una exportación.

Exporta disclosure requests

Usa los mismos filtros disponibles en el listado de disclosure requests. El archivo conserva la estructura pública del recurso:

curl -X POST \
  https://app.soyio.id/api/v1/exports \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "disclosure_requests",
    "output_format": "json",
    "where": "{\"created_at\":{\">\":\"2026-07-01T00:00:00Z\"}}",
    "order_by": "created_at DESC"
  }'

Si también necesitas sus intentos de validación, crea otra exportación. requestable_type limita el reporte a intentos originados por disclosure requests:

curl -X POST \
  https://app.soyio.id/api/v1/exports \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "validation_attempts",
    "report_kind": "conversion",
    "output_format": "csv",
    "where": "{\"requestable_type\":{\"=\":\"DisclosureRequest\"}}"
  }'

Recibe la notificación

Cuando el archivo está listo, Soyio envía el evento export.completed a tus webhooks suscritos. El payload incluye el recurso completo con su download_url:

{
  "id": "evt_1B2M2Y8AsgTpgAmY7PhCfg",
  "name": "export.completed",
  "payload": {
    "id": "exp_1B2M2Y8AsgTpgAmY7PhCfg",
    "resource_kind": "agreements",
    "output_format": "json",
    "status": "completed",
    "records_count": 1200,
    "file_name": "agreements-2026-06-11.json",
    "download_url": "https://app.soyio.id/attachments/..."
  },
  "created_at": "2026-06-11T15:31:22Z"
}

Si la exportación falla, recibirás export.failed con el motivo en error_message.

¿No usas webhooks? Consulta el estado con GET /api/v1/exports/{id} hasta que status sea completed.

Cuando solicitas "packaging": "zip", el mismo payload tiene file_name terminado en .zip, por ejemplo agreements-2026-06-11.zip. Los archivos internos conservan el formato solicitado, como agreements-0001.json, agreements-0002.json o consent-actions-0001.csv.

Revisa la referencia del API para los eventos export.completed y export.failed, y para Obtener estado de exportación. Si aún no configuras webhooks, parte por la guía de Webhooks.

Sincronización incremental

Para mantener tus sistemas al día no necesitas exportar todo cada vez. Guarda la fecha de tu última sincronización y exporta solo los registros nuevos:

curl -X POST \
  https://app.soyio.id/api/v1/exports \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "evidences",
    "output_format": "json",
    "where": "{\"created_at\":{\">\":\"2026-06-10T00:00:00Z\"}}"
  }'

Con esta estrategia, una sincronización periódica se reduce a tres pasos: crear la exportación con el filtro de fecha, esperar el evento export.completed y descargar el archivo generado con los registros nuevos. Es la alternativa recomendada a recorrer los endpoints de listado con polling.

Límites y consideraciones

Hasta 1.000.000 de registros por exportación. Si tu consulta supera el límite, la exportación falla con export.failed; acota con where o divide por rangos de fecha.
Formatos disponibles: csv (por defecto) y json. download_url entrega directamente el formato solicitado cuando packaging no se especifica.
Campos complejos en CSV: los objetos anidados se expanden en columnas con puntos, como metadata.product_id, data.full_name o consent.<template_id>.
ZIP opcional: envía "packaging": "zip" para obtener partes como agreements-0001.json o consent-actions-0001.csv, más un manifest.json con records_count, part_record_limit y el detalle de partes.
download_url es una URL firmada temporal. Si expira, consulta la exportación nuevamente para obtener una nueva.
El procesamiento es en segundo plano: el tiempo de generación depende del volumen de registros.

Cómo funciona​

Recursos disponibles​

Crea una exportación​

Exporta disclosure requests​

Recibe la notificación​

Sincronización incremental​

Límites y consideraciones​

Cómo funciona

Recursos disponibles

Crea una exportación

Exporta disclosure requests

Recibe la notificación

Sincronización incremental

Límites y consideraciones