Exportaciones de datos

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

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

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

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.

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

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.

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 un único archivo con los registros nuevos. Es la alternativa recomendada a recorrer los endpoints de listado con polling.

Límites y consideraciones

• Hasta 100.000 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. El archivo JSON contiene un arreglo con los mismos objetos que retornan los endpoints de listado.
• 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.