Extracción de información desde Parsable

La extracción de información desde Parsable se realiza mediante un conjunto de procesos asíncronos que permiten obtener información de Jobs, Deviations y recursos asociados, como imágenes.

Para realizar la extracción se utilizan diferentes APIs de Parsable, dependiendo del tipo de información requerida. Los flujos se ejecutan de manera independiente y permiten obtener los datos necesarios para su posterior procesamiento e integración con la plataforma.

Actualmente, la integración contempla tres flujos para la obtención de información desde Parsable:

Jobs: extracción asíncrona mediante 4 endpoints secuenciales.
Deviations: extracción asíncrona mediante 4 endpoints secuenciales.
Imágenes: recuperación de recursos gráficos mediante un endpoint independiente.

Nota:

En conjunto, estas APIs permiten obtener la información operativa de Parsable y sus recursos asociados para posteriormente procesarla y almacenarla en los sistemas de destino.

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ámetro	Tipo	Origen / Ámbito	Descripción
`url_reportes`	Configuración	Entorno (`.env`)	URL raíz utilizada para consumir los servicios de Parsable relacionados con la generación y descarga de reportes de Jobs y Deviations. Valor: `https://api.us-west-2.parsable.net/`.
`url_imagenes`	Configuración	Entorno (`.env`)	URL raíz utilizada para consumir los servicios de Parsable relacionados con la recuperación de imágenes. Valor: `https://api.parsable.net/`.
`token_reportes`	Credencial	Configuración / Proveedor	Token de autenticación proporcionado por el proveedor de Parsable y configurado de forma fija para el consumo de los servicios de reportes de Jobs y Deviations. Se envía en el header `Authorization` utilizando el esquema Bearer.
`token_imagenes`	Credencial	Configuración / Proveedor	Token de autenticación proporcionado por el proveedor de Parsable y configurado de forma fija para el consumo de los servicios de recuperación de imágenes. Se envía en el header `Authorization` utilizando el esquema Token.
`team_id`	Identificador	Plataforma Parsable	Código único global que identifica a la organización o equipo de Alpura dentro del tenant de Parsable.
`report_id`	Identificador	Dinámico	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.
`file_parsable_id`	Identificador	Dinámico	ID único asignado a cada Archivo que se encuentra en Parsable.
`signedDownloadUrl`	URL	Dinámico	Enlace seguro y firmado criptográficamente que apunta directamente al almacenamiento en la nube (`CloudFront/S3`). Contiene tokens de expiración y firma mutua.
`parsable-custom-touchstone`	Identificador	Configuración / Proveedor	Identificador proporcionado por Parsable para localizar y direccionar los servicios que serán invocados. Para la integración con Alpura se utiliza el valor `parsable-alpura-touchstone`, de acuerdo con la configuración e indicaciones proporcionadas por el proveedor.

Nota de Seguridad

Los valores de token_reportes, token_imagenes, 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. Flujos de extracción

La integración con Parsable contempla tres flujos principales para la obtención de información. Los flujos de Jobs y Deviations utilizan un mecanismo asíncrono de generación de reportes, mientras que la recuperación de imágenes se realiza mediante un servicio específico proporcionado por Parsable.

Los flujos de extracción de reportes siguen una secuencia de 4 endpoints, en la cual cada etapa depende del resultado obtenido en la etapa anterior. Este mecanismo permite solicitar la generación de la información, consultar su disponibilidad, obtener una URL temporal de descarga y finalmente consumir el archivo generado.

La recuperación de imágenes utiliza un endpoint independiente y una URL base diferente a la utilizada para los reportes.

2.1 Jobs

La extracción de información de Jobs se realiza mediante un proceso asíncrono que involucra 4 endpoints secuenciales.

Este flujo permite:

Paso	Método	Endpoint / URL	Descripción
1	`POST`	`/v2/csv-reports/v1/reports/{team_id}/jobs-inputs`	Solicita la generación del reporte. Retorna un `report_id`.
2	`GET`	`/v2/csv-reports/v1/reports/{team_id}/jobs-inputs/{report_id}`	Consulta el estado del procesamiento (Polling).
3	`GET`	`/v2/csv-reports/v1/reports/{team_id}/jobs-inputs/{report_id}/file`	Obtiene la URL firmada de descarga una vez esté `READY`.
4	`GET`	`{signedDownloadUrl}`	Descarga el archivo físico `.csv` desde el servidor de almacenamiento.

URL

Los flujos de extracción de Jobs utilizan la URL base definida en la variable url_reportes, correspondiente al servicio regional de reportes de Parsable: https://api.us-west-2.parsable.net/.

2.2 Deviations

La extracción de información de Deviations utiliza un proceso asíncrono similar al empleado para Jobs y está compuesto por 4 endpoints secuenciales.

El flujo permite:

Paso	Método	Endpoint / URL	Descripción
1	`POST`	`/api/v3/teams/{team_id}/csv-reports/deviations`	Solicita la generación del reporte. Retorna un `report_id`.
2	`GET`	`/api/v3/teams/{team_id}/csv-reports/deviations/{report_id}`	Consulta el estado del procesamiento (Polling).
3	`GET`	`/api/v3/teams/{team_id}/csv-reports/deviations/{report_id}/file`	Obtiene la URL firmada de descarga una vez esté `READY`.
4	`GET`	`{signedDownloadUrl}`	Descarga el archivo físico `.csv` desde el servidor de almacenamiento.

URL

Los flujos de extracción de Deviations utilizan la URL base definida en la variable url_reportes, correspondiente al servicio regional de reportes de Parsable: https://api.us-west-2.parsable.net/.

2.3 Imágenes

Adicionalmente, se cuenta con un endpoint destinado a la recuperación de imágenes asociadas a la información extraída desde Parsable.

Método	Endpoint / URL	Descripción
`GET`	`/api/documents/{file_parsable_id}/locator`	Recupera la imagen almacenada en Parsable de acuerdo al `file_parsable_id`.

URL

La Recuperación de Imagenes utiliza la URL base definida en la variable url_imagenes, correspondiente al servicio regional de reportes de Parsable: https://api.parsable.net/.

3. Diagrama General

3.1. Diagrama Jobs

3.2. Diagrama Deviations

3.3. Diagrama Imagenes

4. Explicación de los Flujos de Comunicación

La integración con Parsable contempla tres flujos de comunicación para la obtención de información y recursos:

Jobs: extracción asíncrona de información de Jobs mediante la generación y descarga de un reporte CSV.
Deviations: extracción asíncrona de información de Deviations mediante la generación y descarga de un reporte CSV.
Imágenes: recuperación directa de imágenes asociadas a los registros obtenidos desde Parsable.

Los flujos de Jobs y Deviations utilizan un mecanismo de procesamiento asíncrono compuesto por cuatro pasos: solicitud del reporte, consulta de estado, obtención de la URL de descarga y descarga del archivo.

El flujo de Imágenes es independiente y realiza directamente la recuperación del recurso mediante el identificador de archivo proporcionado por Parsable.

Pasos Jobs / Deviations
Pasos Imagenes

Paso	Tipo	Descripción
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 procesa la solicitud de forma asíncrona debido al volumen potencial de datos y devuelve un código `202 Accepted` junto con un identificador único de seguimiento denominado `report_id` (ej. `6a3aaf3a0d7387409fa6bafa`).
2	Polling	El sistema cliente inicia un ciclo de consulta periódica (Polling Loop) mediante peticiones HTTP `GET` cada 5 a 10 segundos, utilizando el `report_id` obtenido en el Paso 1. El proceso continúa hasta obtener un estado final del reporte.
3	Firma / Autorización	Una vez que el reporte alcanza el estado `READY`, el sistema cliente realiza una petición HTTP `GET` al endpoint `/file` para obtener la URL temporal y firmada de descarga (`signedDownloadUrl`).
4	Descarga	El sistema cliente realiza una petición HTTP `GET` directamente sobre `signedDownloadUrl` para descargar el archivo físico `.csv` desde el almacenamiento seguro.

Paso	Tipo	Descripción
1	Solicitud / Recuperación	El sistema cliente realiza una petición HTTP `GET` al endpoint `/api/documents/{file_parsable_id}/locator`, utilizando el `file_parsable_id` proporcionado por Parsable. El servicio localiza el recurso asociado y devuelve la imagen correspondiente para su posterior procesamiento o almacenamiento.

5. Especificación Técnica de los Endpoints

5.1. Jobs - Solicitud

Este endpoint permite solicitar la generación de un reporte CSV basado en los inputs de los trabajos (jobs-inputs), aplicando filtros avanzados por fechas, tipos de trabajo y plantillas específicas de Parsable.

Información General

Elemento	Valor
Método HTTP	`POST`
URL	`<url_api_reportes>/v2/csv-reports/v1/reports/<team_id>/jobs-inputs`
Content-Type	`application/json`
Authorization	`Bearer <token_reportes>`

Body
cURL
Ejemplo Body
Reponse

{
  "jobTypes": ["Normal"],
  "createdDate": {
    "from": "<fecha_inicio>",
    "to": "<fecha_fin>"
  },
  "templates": {
    <templates>
  },
  "businessFunctions": [],
  "businessUnits": [],
  "locations": [],
  "jobIds": [],
  "excludeEmptyInputFields": false,
  "columns": []
}

Parámetros dinámicos

Antes de ejecutar la solicitud, reemplaza los siguientes valores:

Parámetro	Descripción
`<fecha_inicio>`	Fecha y hora inicial del periodo a consultar, utilizando el formato ISO 8601 en UTC. Ejemplo: `2026-06-01T06:00:00.000Z`.
`<fecha_fin>`	Fecha y hora final del periodo a consultar, utilizando el formato ISO 8601 en UTC. Ejemplo: `2026-06-22T05:59:59.999Z`.
`<templates>`	Identificadores de los templates que se incluirán en la extracción. Los templates deben definirse de acuerdo con las reglas de negocio correspondientes.

Los templates utilizados actualmente son:

{
  "711177e4-b93a-485d-a838-2c52d90423e5": [],
  "bf7a6a62-c225-4311-8149-58b3aaffe5b7": []
}

curl --location '<url_api_reportes>/v2/csv-reports/v1/reports/<team_id>/jobs-inputs' \
--header 'Authorization: Bearer <token_reportes>' \
--header 'Content-Type: application/json' \
--data '{
  "jobTypes": ["Normal"],
  "createdDate": {
    "from": "<fecha_inicio>",
    "to": "<fecha_fin>"
  },
  "templates": {
    "711177e4-b93a-485d-a838-2c52d90423e5": [],
    "bf7a6a62-c225-4311-8149-58b3aaffe5b7": []
  },
  "businessFunctions": [],
  "businessUnits": [],
  "locations": [],
  "jobIds": [],
  "excludeEmptyInputFields": false,
  "columns": []
}'

Parámetros dinámicos

Antes de ejecutar la solicitud, reemplaza los siguientes valores:

Parámetro	Descripción
`<url_api_reportes>`	URL base utilizada para consumir los servicios de reportes de Parsable. Para este flujo corresponde a `https://api.us-west-2.parsable.net/`.
`<team_id>`	Identificador único del equipo de Alpura dentro de Parsable.
`<token_reportes>`	Token de autenticación proporcionado por Parsable para el consumo de los servicios de reportes. Se envía en la cabecera `Authorization` utilizando el esquema `Bearer`.
`<fecha_inicio>`	Fecha y hora inicial del periodo a consultar, utilizando el formato ISO 8601 en UTC. Ejemplo: `2026-06-01T06:00:00.000Z`.
`<fecha_fin>`	Fecha y hora final del periodo a consultar, utilizando el formato ISO 8601 en UTC. Ejemplo: `2026-06-22T05:59:59.999Z`.
`<templates>`	Identificadores de los templates que se incluirán en la extracción. Deben definirse de acuerdo con las reglas de negocio correspondientes. Actualmente se utilizan los templates `711177e4-b93a-485d-a838-2c52d90423e5` y `bf7a6a62-c225-4311-8149-58b3aaffe5b7`.

{
  "jobTypes": ["Normal"],
  "createdDate": {
    "from": "2026-06-01T06:00:00.000Z",
    "to": "2026-06-22T05:59:59.999Z"
  },
  "templates": {
    "711177e4-b93a-485d-a838-2c52d90423e5": [],
    "bf7a6a62-c225-4311-8149-58b3aaffe5b7": []
  },
  "businessFunctions": [],
  "businessUnits": [],
  "locations": [],
  "jobIds": [],
  "excludeEmptyInputFields": false,
  "columns": []
}

{
    "id": "6a887c50373fff286f557db4",
    "state": "INITIAL",
    "createdAt": "2026-08-21T16:26:56.730525746Z",
    "createdBy": "6fbedaab-cb85-4455-870a-601a2011ae6e",
    "params": {
        "createdDate": {
            "from": "2026-06-01T06:00:00Z",
            "to": "2026-06-22T05:59:59.999Z"
        },
        "columns": [],
        "templates": {
            "711177e4-b93a-485d-a838-2c52d90423e5": [],
            "bf7a6a62-c225-4311-8149-58b3aaffe5b7": []
        },
        "businessFunctions": [],
        "businessUnits": [],
        "locations": [],
        "jobTypes": [
            "Normal"
        ],
        "jobIds": [],
        "excludeEmptyInputFields": false
    }
}

Identificación del reporte

En la respuesta de este endpoint, el valor del campo id corresponde al identificador único del reporte, denominado report_id.

Este valor debe conservarse y utilizarse en los siguientes pasos del flujo para consultar el estado del reporte y obtener el archivo generado.

5.2. Jobs - Polling

Este endpoint permite consultar periódicamente el estado de procesamiento de un reporte CSV de Jobs (jobs-inputs) previamente solicitado, utilizando el report_id generado en la Jobs - Solicitud. La consulta se realiza mediante un mecanismo de Polling hasta que el reporte alcance un estado final.

Información General

Elemento	Valor
Método HTTP	`GET`
URL	`<url_api_reportes>/v2/csv-reports/v1/reports/<team_id>/jobs-inputs/<report_id>`
Content-Type	`application/json`
Authorization	`Bearer <token_reportes>`

cURL
Reponse

curl --location '<url_api_reportes>/v2/csv-reports/v1/reports/<team_id>/jobs-inputs/<report_id>' \
--header 'Authorization: Bearer <token_reportes>'

Parámetros dinámicos

Antes de ejecutar la solicitud, reemplaza los siguientes valores:

Parámetro	Descripción
`<url_api_reportes>`	URL base utilizada para consumir los servicios de reportes de Parsable. Para este flujo corresponde a `https://api.us-west-2.parsable.net/`.
`<team_id>`	Identificador único del equipo de Alpura dentro de Parsable.
`<report_id>`	ID del Reporte que se recupera con el servicio de `Jobs - Solicitud`
`<token_reportes>`	Token de autenticación proporcionado por Parsable para el consumo de los servicios de reportes. Se envía en la cabecera `Authorization` utilizando el esquema `Bearer`.

{
    "id": "6a887c50373fff286f557db4",
    "state": "READY",
    "createdAt": "2026-08-21T16:26:56.730Z",
    "createdBy": "6fbedaab-cb85-4455-870a-601a2011ae6e",
    "comment": "Processed by Lambda via SQS",
    "params": {
        "createdDate": {
            "from": "2026-06-01T06:00:00Z",
            "to": "2026-06-22T05:59:59.999Z"
        },
        "columns": [],
        "templates": {
            "711177e4-b93a-485d-a838-2c52d90423e5": [],
            "bf7a6a62-c225-4311-8149-58b3aaffe5b7": []
        },
        "businessFunctions": [],
        "businessUnits": [],
        "locations": [],
        "jobTypes": [
            "Normal"
        ],
        "jobIds": [],
        "excludeEmptyInputFields": false
    }
}

Ciclo de Vida del Reporte

Tipo de Estado	Estado	Descripción
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.
Final (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.

5.3. Jobs - Firma/Autorización

Este endpoint permite obtener la URL temporal y firmada de descarga (signedDownloadUrl) de un reporte CSV de Jobs (jobs-inputs) cuyo procesamiento ha finalizado correctamente. La solicitud debe realizarse utilizando el report_id obtenido durante en la Jobs - Solicitud y únicamente cuando el estado del reporte sea READY.

Información General

Elemento	Valor
Método HTTP	`GET`
URL	`<url_api_reportes>/v2/csv-reports/v1/reports/<team_id>/jobs-inputs/<report_id>/file`
Content-Type	`application/json`
Authorization	`Bearer <token_reportes>`

cURL
Reponse

curl --location '<url_api_reportes>/v2/csv-reports/v1/reports/<team_id>/jobs-inputs/<report_id>/file' \
--header 'Authorization: Bearer <token_reportes>'

Parámetros dinámicos

Antes de ejecutar la solicitud, reemplaza los siguientes valores:

Parámetro	Descripción
`<url_api_reportes>`	URL base utilizada para consumir los servicios de reportes de Parsable. Para este flujo corresponde a `https://api.us-west-2.parsable.net/`.
`<team_id>`	Identificador único del equipo de Alpura dentro de Parsable.
`<report_id>`	ID del Reporte que se recupera con el servicio de `Jobs - Solicitud`
`<token_reportes>`	Token de autenticación proporcionado por Parsable para el consumo de los servicios de reportes. Se envía en la cabecera `Authorization` utilizando el esquema `Bearer`.

{
    "type": "csv",
    "sizeInBytes": 15831873,
    "signedDownloadUrl": "https://document-service-ro-us.parsable.net/27d1ad35-d38a-5bff-9ce1-35d145f6b611/673362cf-0d9e-4c06-a67d-9e60bd69a90a/jobs_inputs-report-8e84fd84-eb94-4838-bdf9-d246bfabbc81-2026-08-21_16-27-58-889-UTC.csv?versionId=m3SBSSFnRVGayD0Kf5oEmcgfnvnMsTmY&Expires=1787336901&Signature=tlA4qdOUxBCBt1ntQ1tLzeLX6wsz4Nyop1x26wF1HWIlOrGrIHSmyQBdaUcf2apqeQpUMv9kkC441mc-san-8Dp5pcET1AZSDlOL5mbtH1UMyCC3-8h-pyWqv0cNdwXgIo331niwyJhJSMS9SJ2F87DLCbimstZujabxebL55iOITyh0pqeE6GJyQxmwhc9znZS6MHELHk~IQnseNdym67~asj8Oxh0uKyY2DBQIsDp1IEWlYDk9ky66QE49W1qavHKYXdCxxwgliqoxpdgQxsZsimvdOSn~LvTLsAZDUINPbwZSROwA~S3KCc2AkdDI1bS3DXYOFVUvNM~V0Y4ycA__&Key-Pair-Id=K6IZ3YL4GCIIR",
    "urlExpirationDateUtc": "2026-08-21T18:28:21.989614426"
}

Nota

La propiedad signedDownloadUrl contiene la ubicación exacta del archivo físico y expira de forma estricta en la marca de tiempo indicada por urlExpirationDateUtc.

5.4. Jobs - Descarga

Este endpoint permite descargar el archivo CSV generado por Parsable mediante la URL temporal y firmada (signedDownloadUrl) obtenida en el Jobs - Firma/Autorización. La descarga se realiza directamente desde el servicio de almacenamiento asociado a Parsable y no requiere enviar nuevamente el token de autenticación utilizado en los pasos anteriores.

Información General

Elemento	Valor
Método HTTP	`GET`
URL	`<signedDownloadUrl>`

cURL
Reponse

curl --location '<signedDownloadUrl>'

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.

"job_id","job_guid","record_type","job_title","job_created_date_utc","job_status","job_template_title","step_title","field_label","field_type","field_value","attr_locations","attr_bus_func"
"Job-1009","c60f0c6a-9506-4729-8d45-6e279cc52914","Job","SA-01-01 Salud del hato...","2026-06-15 17:15:04","Completed","SA-02-01 SALUD DEL HATO","Datos generales","Nombre de Asesor Técnico","list","JORGE ALBERTO CALDERÓN SÁNCHEZ","Dirección de Calidad","Calidad Torreón"
"Job-1009","c60f0c6a-9506-4729-8d45-6e279cc52914","Job","SA-01-01 Salud del hato...","2026-06-15 17:15:04","Completed","SA-02-01 SALUD DEL HATO","Datos generales","REGION","list","TORREON","Dirección de Calidad","Calidad Torreón"
"Job-1009","c60f0c6a-9506-4729-8d45-6e279cc52914","Job","SA-01-01 Salud del hato...","2026-06-15 17:15:04","Completed","SA-02-01 SALUD DEL HATO","Campañas Zoosanitarias","¿Participa en campaña oficial de Brucelosis?","yesno","yes","Dirección de Calidad","Calidad Torreón"

Nota

Cada fila del CSV representa un campo evaluado (field_guid) individualmente dentro de los pasos del formulario técnico.

5.5. Deviations - Solicitud

Este endpoint permite solicitar la generación de un reporte CSV basado en las Deviations registradas en Parsable, aplicando los criterios de filtrado definidos para la extracción.

Información General

Elemento	Valor
Método HTTP	`POST`
URL	`<url_api_reportes>/api/v3/teams/<team_id>/csv-reports/deviations`
Content-Type	`application/json`
Authorization	`Bearer <token_reportes>`
parsable-custom-touchstone	`parsable-alpura-touchstone`

Body
cURL
Ejemplo Body
Reponse

{
  "deviationCreatedDate": {
    "from": "<fecha_inicio>",
    "to": "<fecha_fin>"
  },
  "templates": {
            <templates>
        }      
}

Parámetros dinámicos

Antes de ejecutar la solicitud, reemplaza los siguientes valores:

Parámetro	Descripción
`<fecha_inicio>`	Fecha y hora inicial del periodo a consultar, utilizando el formato ISO 8601 en UTC. Ejemplo: `2026-06-01T06:00:00.000Z`.
`<fecha_fin>`	Fecha y hora final del periodo a consultar, utilizando el formato ISO 8601 en UTC. Ejemplo: `2026-06-22T05:59:59.999Z`.
`<templates>`	Identificadores de los templates que se incluirán en la extracción. Los templates deben definirse de acuerdo con las reglas de negocio correspondientes.

Los templates utilizados actualmente son:

{
  "711177e4-b93a-485d-a838-2c52d90423e5": [],
  "bf7a6a62-c225-4311-8149-58b3aaffe5b7": []
}

curl --location '<url_api_reportes>/api/v3/teams/<team_id>/csv-reports/deviations' \
--header 'accept: application/json' \
--header 'parsable-custom-touchstone: <parsable-custom-touchstone>' \
--header 'Authorization: Bearer <token_reportes>' \
--header 'Content-Type: application/json' \
--data '{
  "deviationCreatedDate": {
    "from": "<fecha_inicio>",
    "to": "<fecha_fin>"
  },
  "templates": {
            <templates>
        }
    
}'

Parámetros dinámicos

Antes de ejecutar la solicitud, reemplaza los siguientes valores:

Parámetro	Descripción
`<url_api_reportes>`	URL base utilizada para consumir los servicios de reportes de Parsable. Para este flujo corresponde a `https://api.us-west-2.parsable.net/`.
`<team_id>`	Identificador único del equipo de Alpura dentro de Parsable.
`<parsable-custom-touchstone>`	Identificador para indetificar las peticiones de Alpura Default dentro de Parsable `parsable-alpura-touchstone`.
`<token_reportes>`	Token de autenticación proporcionado por Parsable para el consumo de los servicios de reportes. Se envía en la cabecera `Authorization` utilizando el esquema `Bearer`.
`<fecha_inicio>`	Fecha y hora inicial del periodo a consultar, utilizando el formato ISO 8601 en UTC. Ejemplo: `2026-06-01T06:00:00.000Z`.
`<fecha_fin>`	Fecha y hora final del periodo a consultar, utilizando el formato ISO 8601 en UTC. Ejemplo: `2026-06-22T05:59:59.999Z`.
`<templates>`	Identificadores de los templates que se incluirán en la extracción. Deben definirse de acuerdo con las reglas de negocio correspondientes. Actualmente se utilizan los templates `711177e4-b93a-485d-a838-2c52d90423e5` y `bf7a6a62-c225-4311-8149-58b3aaffe5b7`.

{
  "deviationCreatedDate": {
    "from": "2026-08-01T03:27:11.751Z",
    "to": "2026-08-30T23:59:59.999Z"
  },
  "templates": {
            "711177e4-b93a-485d-a838-2c52d90423e5": [],
            "bf7a6a62-c225-4311-8149-58b3aaffe5b7": []
        }
}

{
    "id": "6a889ba4373fff286f557df5",
    "state": "INITIAL",
    "createdAt": "2026-08-21T18:40:36.815150546Z",
    "createdBy": "6fbedaab-cb85-4455-870a-601a2011ae6e",
    "params": {
        "deviationCreatedDate": {
            "from": "2026-08-01T03:27:11.751Z",
            "to": "2026-08-30T23:59:59.999Z"
        }
    }
}

Identificación del reporte

En la respuesta de este endpoint, el valor del campo id corresponde al identificador único del reporte, denominado report_id.

Este valor debe conservarse y utilizarse en los siguientes pasos del flujo para consultar el estado del reporte y obtener el archivo generado.

5.6. Deviations - Polling

Este endpoint permite consultar periódicamente el estado de procesamiento de un reporte CSV de Deviations previamente solicitado, utilizando el report_id generado en Deviations - Solicitud. La consulta se realiza mediante un mecanismo de Polling hasta que el reporte alcance un estado final.

Información General

Elemento	Valor
Método HTTP	`POST`
URL	`<url_api_reportes>/api/v3/teams/<team_id>/csv-reports/deviations/<report_id>`
Content-Type	`application/json`
Authorization	`Bearer <token_reportes>`
parsable-custom-touchstone	`parsable-alpura-touchstone`

cURL
Reponse

curl --location '<url_api_reportes>/api/v3/teams/<team_id>/csv-reports/deviations/<report_id>' \
--header 'accept: application/json' \
--header 'parsable-custom-touchstone: <parsable-custom-touchstone>' \
--header 'Authorization: Bearer <token_reportes>' \
--header 'Content-Type: application/json' \
--data ''

Parámetros dinámicos

Antes de ejecutar la solicitud, reemplaza los siguientes valores:

Parámetro	Descripción
`<url_api_reportes>`	URL base utilizada para consumir los servicios de reportes de Parsable. Para este flujo corresponde a `https://api.us-west-2.parsable.net/`.
`<team_id>`	Identificador único del equipo de Alpura dentro de Parsable.
`<report_id>`	ID del Reporte que se recupera con el servicio de `Deviations - Solicitud`
`<parsable-custom-touchstone>`	Identificador para indetificar las peticiones de Alpura Default dentro de Parsable `parsable-alpura-touchstone`.
`<token_reportes>`	Token de autenticación proporcionado por Parsable para el consumo de los servicios de reportes. Se envía en la cabecera `Authorization` utilizando el esquema `Bearer`.

{
    "id": "6a889ba4373fff286f557df5",
    "state": "READY",
    "createdAt": "2026-08-21T18:40:36.815Z",
    "createdBy": "6fbedaab-cb85-4455-870a-601a2011ae6e",
    "comment": "Processed by Lambda via SQS",
    "params": {
        "deviationCreatedDate": {
            "from": "2026-08-01T03:27:11.751Z",
            "to": "2026-08-30T23:59:59.999Z"
        }
    }
}

Ciclo de Vida del Reporte

Tipo de Estado	Estado	Descripción
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.
Final (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.

5.7. Deviations - Firma/Autorización

Este endpoint permite obtener la URL temporal y firmada de descarga (signedDownloadUrl) de un reporte CSV de Deviations cuyo procesamiento ha finalizado correctamente. La solicitud debe realizarse utilizando el report_id obtenido durante Deviations - Solicitud y únicamente cuando el estado del reporte sea READY.

Información General

Elemento	Valor
Método HTTP	`POST`
URL	`<url_api_reportes>/api/v3/teams/<team_id>/csv-reports/deviations/<report_id>/file`
Content-Type	`application/json`
Authorization	`Bearer <token_reportes>`
parsable-custom-touchstone	`parsable-alpura-touchstone`

cURL
Reponse

curl --location '<url_api_reportes>/api/v3/teams/<team_id>/csv-reports/deviations/<report_id>/file' \
--header 'accept: application/json' \
--header 'parsable-custom-touchstone: <parsable-custom-touchstone>' \
--header 'Authorization: Bearer e<token_reportes>' \
--header 'Content-Type: application/json' \
--data ''

Parámetros dinámicos

Antes de ejecutar la solicitud, reemplaza los siguientes valores:

Parámetro	Descripción
`<url_api_reportes>`	URL base utilizada para consumir los servicios de reportes de Parsable. Para este flujo corresponde a `https://api.us-west-2.parsable.net/`.
`<team_id>`	Identificador único del equipo de Alpura dentro de Parsable.
`<report_id>`	ID del Reporte que se recupera con el servicio de `Deviations - Solicitud`
`<parsable-custom-touchstone>`	Identificador para indetificar las peticiones de Alpura Default dentro de Parsable `parsable-alpura-touchstone`.
`<token_reportes>`	Token de autenticación proporcionado por Parsable para el consumo de los servicios de reportes. Se envía en la cabecera `Authorization` utilizando el esquema `Bearer`.

{
    "type": "csv",
    "sizeInBytes": 15831873,
    "signedDownloadUrl": "https://document-service-ro-us.parsable.net/27d1ad35-d38a-5bff-9ce1-35d145f6b611/673362cf-0d9e-4c06-a67d-9e60bd69a90a/jobs_inputs-report-8e84fd84-eb94-4838-bdf9-d246bfabbc81-2026-08-21_16-27-58-889-UTC.csv?versionId=m3SBSSFnRVGayD0Kf5oEmcgfnvnMsTmY&Expires=1787336901&Signature=tlA4qdOUxBCBt1ntQ1tLzeLX6wsz4Nyop1x26wF1HWIlOrGrIHSmyQBdaUcf2apqeQpUMv9kkC441mc-san-8Dp5pcET1AZSDlOL5mbtH1UMyCC3-8h-pyWqv0cNdwXgIo331niwyJhJSMS9SJ2F87DLCbimstZujabxebL55iOITyh0pqeE6GJyQxmwhc9znZS6MHELHk~IQnseNdym67~asj8Oxh0uKyY2DBQIsDp1IEWlYDk9ky66QE49W1qavHKYXdCxxwgliqoxpdgQxsZsimvdOSn~LvTLsAZDUINPbwZSROwA~S3KCc2AkdDI1bS3DXYOFVUvNM~V0Y4ycA__&Key-Pair-Id=K6IZ3YL4GCIIR",
    "urlExpirationDateUtc": "2026-08-21T18:28:21.989614426"
}

Nota

La propiedad signedDownloadUrl contiene la ubicación exacta del archivo físico y expira de forma estricta en la marca de tiempo indicada por urlExpirationDateUtc.

5.8. Deviations - Descarga

Este endpoint permite descargar el archivo CSV de Deviations generado por Parsable mediante la URL temporal y firmada (signedDownloadUrl) obtenida en Deviations - Firma/Autorización. La descarga se realiza directamente desde el servicio de almacenamiento asociado a Parsable y no requiere enviar nuevamente el token de autenticación utilizado en los pasos anteriores.

Información General

Elemento	Valor
Método HTTP	`GET`
URL	`<signedDownloadUrl>`

cURL
Reponse

curl --location '<signedDownloadUrl>'

Comportamiento del Storage

"job_id","job_guid","job_title","job_type","job_created_date_utc","job_started_date_utc","job_last_updated_date_utc","job_completed_date_utc","job_cancelation_date_utc","job_archived_date_utc","job_status","job_total_steps","job_completed_steps","job_template_guid","job_template_title","job_template_version","job_template_publisher_name","job_template_publisher_email","template_order_number","attr_locations","attr_bus_func","attr_bus_units","template_attr_locations","template_attr_bus_func","template_attr_bus_units","deviation_guid","deviation_created_date_utc","deviation_last_updated_date_utc","deviation_type","deviation_condition","deviation_condition_trigger","is_deviation_actual","deviation_field_label","deviation_field_last_updated_date_utc","deviation_field_value_type","deviation_field_value","deviation_field_exec_updated_date_utc","deviation_field_is_na","deviation_field_measurement_units","deviation_field_executor_user_name","deviation_field_executor_user_email","deviation_field_seq_id","deviation_field_is_required","deviation_step_title","deviation_step_hierarchy_order","deviation_step_hierarchy_position","deviation_step_type","deviation_step_status","deviation_step_is_na","deviation_step_last_updated_date_utc","deviation_step_started_date_utc","deviation_client_step_started_date_utc","deviation_step_completed_date_utc","deviation_client_step_completed_date_utc","deviation_step_duration","deviation_client_step_duration","deviation_step_completer_user_name","deviation_step_completer_user_email","Job Parameter Tags"
"Job-7864","2281ab3a-5d4a-485d-82f4-6204131513c2","SA-01-01 Salud del hato: Programada-QUERETARO-JUAN ANTONIO MEJÍA ESPITIA-134 | SAN FANDILA-2026-08-06","Normal","2026-08-06 13:54:12","2026-08-06 13:54:12","2026-08-06 22:21:17","2026-08-06 22:21:16",,,"Completed","10","10","711177e4-b93a-485d-a838-2c52d90423e5","SA-02-01 SALUD DEL HATO","19","ALEJANDRO TREJO MEJIA","alejandro.trejo@alpura.com","1","Dirección de Calidad","Calidad Queretaro","Calidad del Origen","Dirección de Calidad","Calidad Cuautitlán,Calidad Delicias,Calidad Irapuato,Calidad Queretaro,Calidad Torreón","Calidad del Origen","08734664-4423-414b-9fd0-1cc6a7955034","2026-08-06 15:08:39","2026-08-06 15:08:39","DEVIATION_VALIDATION_TRIGGERED","No","true","true","Fertilidad a 1er. Servicio Vacas 45%","2026-08-06 22:21:17","yesno","no","2026-08-06 15:08:39","false",,"Juan Antonio Mejia Espitia","jmejia@alpura.com","118066322","false","Parámetros Reproducción","8","7","Normal","Complete","false","2026-08-06 15:09:30","2026-08-06 15:08:34","2026-08-06 15:08:32","2026-08-06 15:09:30","2026-08-06 15:09:28","56.0","56.0","Juan Antonio Mejia Espitia","jmejia@alpura.com",
"Job-7864","2281ab3a-5d4a-485d-82f4-6204131513c2","SA-01-01 Salud del hato: Programada-QUERETARO-JUAN ANTONIO MEJÍA ESPITIA-134 | SAN FANDILA-2026-08-06","Normal","2026-08-06 13:54:12","2026-08-06 13:54:12","2026-08-06 22:21:17","2026-08-06 22:21:16",,,"Completed","10","10","711177e4-b93a-485d-a838-2c52d90423e5","SA-02-01 SALUD DEL HATO","19","ALEJANDRO TREJO MEJIA","alejandro.trejo@alpura.com","1","Dirección de Calidad","Calidad Queretaro","Calidad del Origen","Dirección de Calidad","Calidad Cuautitlán,Calidad Delicias,Calidad Irapuato,Calidad Queretaro,Calidad Torreón","Calidad del Origen","07102ec6-bc41-4f5c-aa41-77b1834563f9","2026-08-06 15:09:16","2026-08-06 15:09:16","DEVIATION_VALIDATION_TRIGGERED","No","true","true","% De Abortos Total Mensual 0.91%","2026-08-06 22:21:17","yesno","no","2026-08-06 15:09:16","false",,"Juan Antonio Mejia Espitia","jmejia@alpura.com","118066336","false","Parámetros Reproducción","8","7","Normal","Complete","false","2026-08-06 15:09:30","2026-08-06 15:08:34","2026-08-06 15:08:32","2026-08-06 15:09:30","2026-08-06 15:09:28","56.0","56.0","Juan Antonio Mejia Espitia","jmejia@alpura.com",
"Job-7864","2281ab3a-5d4a-485d-82f4-6204131513c2","SA-01-01 Salud del hato: Programada-QUERETARO-JUAN ANTONIO MEJÍA ESPITIA-134 | SAN FANDILA-2026-08-06","Normal","2026-08-06 13:54:12","2026-08-06 13:54:12","2026-08-06 22:21:17","2026-08-06 22:21:16",,,"Completed","10","10","711177e4-b93a-485d-a838-2c52d90423e5","SA-02-01 SALUD DEL HATO","19","ALEJANDRO TREJO MEJIA","alejandro.trejo@alpura.com","1","Dirección de Calidad","Calidad Queretaro","Calidad del Origen","Dirección de Calidad","Calidad Cuautitlán,Calidad Delicias,Calidad Irapuato,Calidad Queretaro,Calidad Torreón","Calidad del Origen","0b377ba8-d745-49fc-aa15-3e1d1a714fe8","2026-08-06 15:07:57","2026-08-06 15:07:57","DEVIATION_VALIDATION_TRIGGERED","Equal To","<25%,<50%,<75%","true","¿El ganado de recría cuenta con arete SINIIGA?","2026-08-06 22:21:17","list","<75%","2026-08-06 15:07:57","false",,"Juan Antonio Mejia Espitia","jmejia@alpura.com","118062967","true","Generales","5","4","Normal","Complete","false","2026-08-06 15:45:17","2026-08-06 15:07:49","2026-08-06 15:07:47","2026-08-06 15:45:17","2026-08-06 15:45:15","2248.0","2248.0","Juan Antonio Mejia Espitia","jmejia@alpura.com"

Nota

Cada fila del CSV representa un campo evaluado (field_guid) individualmente dentro de los pasos del formulario técnico.

5.9. Imagenes - Solicitud / Recuperación

Este endpoint permite recuperar una imagen asociada a un archivo almacenado en Parsable, utilizando el identificador file_parsable_id proporcionado por la plataforma.

Información General

Elemento	Valor
Método HTTP	`GET`
URL	`<url_imagenes>/api/documents/<file_parsable_id>/locator`
Accept	`application/json`
Authorization	`Token <token_imagenes>`

cURL

curl --location '<url_imagenes>/api/documents/<file_parsable_id>/locator' \
--header 'Authorization: Token <token_imagenes>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data ''

Parámetros dinámicos

Antes de ejecutar la solicitud, reemplaza los siguientes valores:

Parámetro	Descripción
`<url_imagenes>`	URL base utilizada para consumir los servicios de recuperación de imágenes de Parsable. Corresponde a `https://api.parsable.net/`.
`<file_parsable_id>`	Identificador único del archivo o recurso almacenado en Parsable que se desea recuperar. Este identificador es proporcionado por Parsable y permite localizar la imagen asociada.
`<token_imagenes>`	Token de autenticación proporcionado por Parsable para el consumo del servicio de recuperación de imágenes. Se envía en la cabecera `Authorization` utilizando el esquema `Token`.

1. Glosario de Parámetros y Variables​

2. Flujos de extracción​

2.1 Jobs​

2.2 Deviations​

2.3 Imágenes​

3. Diagrama General​

3.1. Diagrama Jobs​

3.2. Diagrama Deviations​

3.3. Diagrama Imagenes​

4. Explicación de los Flujos de Comunicación​

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

5.1. Jobs - Solicitud​

Información General​

5.2. Jobs - Polling​

Información General​

5.3. Jobs - Firma/Autorización​

Información General​

5.4. Jobs - Descarga​

5.5. Deviations - Solicitud​

Información General​

5.6. Deviations - Polling​

Información General​

5.7. Deviations - Firma/Autorización​

Información General​

5.8. Deviations - Descarga​

Información General​

5.9. Imagenes - Solicitud / Recuperación​

Información General​

cURL​

1. Glosario de Parámetros y Variables

2. Flujos de extracción

2.1 Jobs

2.2 Deviations

2.3 Imágenes

3. Diagrama General

3.1. Diagrama Jobs

3.2. Diagrama Deviations

3.3. Diagrama Imagenes

4. Explicación de los Flujos de Comunicación

5. Especificación Técnica de los Endpoints

5.1. Jobs - Solicitud

Información General

5.2. Jobs - Polling

Información General

5.3. Jobs - Firma/Autorización

Información General

5.4. Jobs - Descarga

5.5. Deviations - Solicitud

Información General

5.6. Deviations - Polling

Información General

5.7. Deviations - Firma/Autorización

Información General

5.8. Deviations - Descarga

Información General

5.9. Imagenes - Solicitud / Recuperación

Información General

cURL