Skip to main content

Extracción de Datos

La extracción de datos desde Parsable se realiza mediante un proceso asíncrono que involucra 4 endpoints secuenciales. Este flujo permite programar la generación del reporte, monitorear su estado, obtener una URL de descarga segura y, finalmente, consumir el archivo CSV.

1. Glosario de Parámetros y Variables​

Para facilitar la integración y comprensión del flujo de extracción de datos, a continuación se detallan los identificadores, variables de entorno y tokens utilizados en esta documentación:

Variable / ParámetroTipoOrigen / ÁmbitoDescripción
url_base_apiConfiguraciónEntorno (.env)URL raíz de los servicios web de Parsable (ej. https://api.parsable.net o la variante regional correspondiente).
token_accesoCredencialAutenticaciónToken de tipo Bearer JWT temporal obtenido tras autenticarse con las credenciales del sistema cliente. Es obligatorio para los endpoints de estado y firma.
team_idIdentificadorPlataforma ParsableCódigo único global que identifica a la organización o equipo de Alpura dentro del tenant de Parsable.
report_idIdentificadorDinámico (Paso 3.1)ID único asignado a la tarea de compilación del reporte asíncrono. Se genera al solicitar la exportación de datos de los formularios.
signedDownloadUrlURLDinámico (Paso 3.3)Enlace seguro y firmado criptográficamente que apunta directamente al almacenamiento en la nube (CloudFront/S3). Contiene tokens de expiración y firma mutua.
Nota de Seguridad

Los valores de token_acceso y las firmas dinámicas dentro de signedDownloadUrl contienen credenciales de acceso a datos sensibles de producción (calidad, ranchos, asesores). Nunca deben quedar expuestos de forma fija en repositorios públicos de código.

2. Resumen del Flujo Asíncrono​

El ciclo de vida para obtener el reporte de entradas de trabajo consta de los siguientes pasos:

PasoMétodoEndpoint / URLDescripción
1POST/v2/csv-reports/v1/reports/{team_id}/jobs-inputsSolicita la generación del reporte. Retorna un report_id.
2GET/v2/csv-reports/v1/reports/{team_id}/jobs-inputs/{report_id}Consulta el estado del procesamiento (Polling).
3GET/v2/csv-reports/v1/reports/{team_id}/jobs-inputs/{report_id}/fileObtiene la URL firmada de descarga una vez esté READY.
4GET{signedDownloadUrl}Descarga el archivo físico .csv desde el servidor de almacenamiento.

3. Diagrama​

4. Explicación del Flujo de Comunicación​

El ciclo de vida para la extracción y consumo del reporte de entradas de trabajo (jobs-inputs) se compone de 4 pasos secuenciales detallados a continuación:

4.1. Paso 1 (Solicitud)​

El sistema cliente inicializa el flujo enviando una petición HTTP POST con los criterios de filtrado específicos al endpoint del equipo. La API de Parsable no procesa ni genera el archivo de forma síncrona debido al volumen potencial de datos; en su lugar, registra la tarea en una cola de fondo y devuelve de inmediato un código 202 Accepted junto con un token único de seguimiento llamado report_id (ej. 6a3aaf3a0d7387409fa6bafa).

Criterios de Filtrado Disponibles (Cuerpo del JSON)

Tipo: Arreglo de cadenas.
Segmenta por la naturaleza del trabajo. Valores válidos: ["Normal", "On-Demand", "Recurring", "Issue"].
Recomendación: Filtrar "On-Demand" si solo se desean ver ejecuciones reales de asesores y no los jobs padre del sistema.

4.2. Paso 2 (Polling)​

Debido a que la generación de reportes masivos se procesa de forma asíncrona, el sistema cliente inicia un bucle de consulta periódica (Polling Loop) realizando peticiones HTTP GET cada 5 a 10 segundos utilizando el report_id obtenido. El sistema debe interpretar el estado devuelto conforme a la siguiente matriz de ciclo de vida:

Matriz de Estados del Reporte
  • Estados de Transición (Continuar Polling):
    • INITIAL: La solicitud de reporte ha sido registrada exitosamente en la base de datos de Parsable.
    • SCHEDULED: La tarea se encuentra en la cola de procesamiento, esperando asignación de recursos.
    • IN_PROGRESS: El motor de reportes está extrayendo de forma activa los inputs de los jobs y estructurando el CSV.
    • PUBLISHING: El archivo plano .csv ya fue generado y se está transmitiendo hacia el storage cloud seguro.
  • Estados Finales (Terminar Polling):
    • READY: El procesamiento ha culminado con éxito. El archivo está totalmente disponible para pasar al Paso 3.
    • ERROR: Ocurrió un fallo crítico e inesperado. Se debe abortar el bucle, alertar al orquestador (ej. Airflow) y revisar los filtros del Paso 1.
    • DUPLICATE: Se detectó una solicitud idéntica en proceso. Se sugiere reutilizar el flujo original.

4.3. Paso 3 (Firma/Autorización)​

Una vez que el estado del reporte cambia de forma estricta a READY, el cliente realiza una petición HTTP GET al endpoint finalizador del reporte (/file). Parsable valida internamente que el archivo exista en su infraestructura y responde con un objeto JSON que contiene un enlace directo expuesto. Este enlace cuenta con parámetros de seguridad y firmas criptográficas de acceso que son tanto temporales como seguras.

4.4. Paso 4 (Descarga)​

El sistema cliente realiza la última petición HTTP GET apuntando directamente a la infraestructura de almacenamiento seguro de Parsable (signedDownloadUrl).

Autenticación por URL

En este punto, se deben omitir las cabeceras tradicionales de autenticación (como Authorization: Bearer <token>), dado que la autorización de lectura de AWS S3 / CloudFront, las llaves públicas de acceso y el tiempo límite de expiración vienen delegados e inyectados directamente dentro de los query parameters de la URL generada: signedDownloadUrl&urlExpirationDateUtc.

Autenticación por URL

El servidor procesa la firma de la URL y responde con un Content-Type: text/csv, entregando el flujo de datos del archivo físico para su posterior ingesta y transformación en la base de datos destino.

5. Especificación Técnica de los Endpoints​

5.1 Headers Globales​

Para realizar las peticiones a la API base de Parsable, es obligatorio incluir las siguientes cabeceras:

Authorization: Bearer <token_acceso>
Content-Type: application/json

6. APIs​

6.1. Solicitud​

El sistema cliente inicializa el flujo enviando una petición HTTP POST con los criterios de filtrado específicos al endpoint del equipo. La API de Parsable no procesa ni genera el archivo de forma síncrona debido al volumen potencial de datos; en su lugar, registra la tarea en una cola de fondo y devuelve de inmediato un código 202 Accepted junto con la entidad del reporte en estado inicial.

Detalles del Payload (Cuerpo del JSON)
  • jobTypes: Arreglo de cadenas para segmentar por la naturaleza del trabajo. Valores válidos: ["Normal", "On-Demand", "Recurring", "Issue"].
  • createdDate: Rango de tiempo basado en la creación del Job utilizando formato extendido ISO 8601 (from y to). Ej: {"from": "2026-06-01T06:00:00.000Z"}.
  • templates: Diccionario de UUIDs de plantillas para restringir la extracción a formularios específicos (ej. Calidad de Leche). Si se deja vacío, extrae todos de forma global.
  • columns: Arreglo explícito con los identificadores técnicos de las columnas requeridas para optimizar el tamaño del archivo resultante.

6.2. Polling​

Debido a que la generación de reportes masivos se procesa de forma asíncrona, el sistema cliente inicia un bucle de consulta periódica (Polling Loop) realizando peticiones HTTP GET cada 5 a 10 segundos utilizando el id del reporte (ej. 6a3aefc580e6bc3bc369fe1a) obtenido en el paso anterior. El sistema debe interpretar el estado devuelto conforme a las siguientes especificaciones:

Ciclo de Vida del Reporte
Tipo de EstadoEstadoDescripción
Transición (Continuar Polling)INITIALLa solicitud de reporte ha sido registrada exitosamente en la base de datos de Parsable.
SCHEDULEDLa tarea se encuentra en la cola de procesamiento, esperando asignación de recursos.
IN_PROGRESSEl motor de reportes está extrayendo de forma activa los inputs de los jobs y estructurando el CSV.
PUBLISHINGEl archivo plano .csv ya fue generado y se está transmitiendo hacia el storage cloud seguro.
Final (Terminar Polling)READYEl procesamiento ha culminado con éxito. El archivo está totalmente disponible para pasar al Paso 3.
ERROROcurrió un fallo crítico e inesperado. Se debe abortar el bucle, alertar al orquestador (ej. Airflow) y revisar los filtros del Paso 1.
DUPLICATESe detectó una solicitud idéntica en proceso. Se sugiere reutilizar el flujo original.

6.3. Firma/Autorización​

Una vez que el estado del reporte cambia de forma estricta a READY, el sistema cliente solicita la generación del enlace seguro de descarga. La API de Parsable valida internamente la existencia del recurso y genera un acceso firmado criptográficamente de carácter temporal.

Información de la Solicitud
AtributoDetalle
Método HTTPGET
Endpoint<url_base_api>/v2/csv-reports/v1/reports/<team_id>/jobs-inputs/<report_id>/file
PropósitoMutar el estado lógico a un recurso físico delegando la seguridad de la descarga a firmas de URL de almacenamiento seguro con tiempo de expiración definido.

6.4. Descarga​

El paso final del flujo ejecuta el consumo físico del archivo plano .csv. La descarga se realiza directamente contra la infraestructura de almacenamiento distribuido seguro de Parsable.

Importante: Cabeceras de Autenticación

En este endpoint se deben omitir por completo los encabezados tradicionales de autenticación (como Authorization: Bearer). Intentar inyectar el token Bearer en el almacenamiento seguro resultará en un fallo técnico de firma mutua (HTTP 400 Bad Request o HTTP 403 Forbidden).

Comportamiento del Storage

El servidor de storage lee los query parameters inyectados dentro de la propiedad signedDownloadUrl (Signature, Expires, versionId, Key-Pair-Id), valida la firma delegada y abre un canal de transmisión de datos directos (Stream) devolviendo un encabezado Content-Type: text/csv.