Colección Postman

La colección centraliza todos los endpoints de la API con variables de entorno preconfiguradas, autenticación Bearer lista para usar y ejemplos de los parámetros más comunes. Permite explorar y probar la API sin necesidad de construir las peticiones desde cero.

Cubre los cinco recursos de la API organizados en carpetas:

Carpeta	Endpoints	Descripción
Health	1	Estado del servicio
DAGs	4	Listado, estadísticas, timeline y búsqueda de ejecuciones
Runs	2	Resumen y payload de evento de una ejecución concreta
Phases	5	Metadatos, datos, logs y errores por fase — con streaming NDJSON
Artifacts	2	Listado y descarga de artefactos generados por una ejecución

Importar la colección

Descarga el archivo: hub-log-middleware.postman_collection.json
En Postman, haz clic en Import.
Arrastra el archivo descargado o selecciónalo desde el explorador.
La colección aparecerá en tu panel izquierdo bajo el nombre Hub Log Middleware.

Configurar las variables

Antes de hacer cualquier petición, configura las variables de la colección. Haz clic en el nombre de la colección y selecciona la pestaña Variables:

Variable	Descripción	Ejemplo
`baseUrl`	URL base del servicio, incluye el prefijo `/api/v1`	`https://one.fracttal.com/hub/api/v1`
`token`	Bearer token de autenticación (sin el prefijo `Bearer`)	`eyJhbGci...`
`dag_id`	Identificador del DAG a consultar	`mi-dag-de-ejemplo`
`run_date`	Fecha de la ejecución en formato `YYYY-MM-DD`	`2026-05-01`
`run_id`	Identificador completo de la ejecución	`scheduled__2026-05-01T00:00:00+00:00`
`phase`	Fase de la ejecución	`extract`, `transform`, `load` o `event`

La autenticación está configurada a nivel de colección: todas las peticiones heredan el token automáticamente desde la variable token. Solo es necesario configurarlo una vez.

Estructura de la colección

Health

Verifica que el servicio está activo y disponible antes de hacer cualquier consulta.

Nombre	Método	Ruta
Health check	`GET`	`/health`

Respuesta esperada (200):

{
  "status": "healthy",
  "app_name": "Hub Log Middleware",
  "version": "1.0.0",
  "environment": "production"
}

Úsalo como primer paso para confirmar que el servicio responde y que tu baseUrl está bien configurada.

DAGs

Permite navegar los DAGs disponibles para tu empresa y explorar sus ejecuciones.

Nombre	Método	Ruta
List DAGs	`GET`	`/dags`
Run statistics for a DAG	`GET`	`/dags/{dag_id}/stats`
Run timeline for a DAG	`GET`	`/dags/{dag_id}/timeline`
Search runs for a DAG	`GET`	`/dags/{dag_id}/runs`

List DAGs — devuelve todos los DAGs accesibles para la empresa del token. El campo dag_id que aparece aquí es el que debes guardar en la variable dag_id.

Run statistics — retorna contadores agrupados por estado (success, failed, running) para un rango de fechas. Los parámetros start_date y end_date usan formato YYYY-MM-DD y están precargados en la petición.

Run timeline — devuelve las ejecuciones ordenadas cronológicamente para construir visualizaciones tipo Gantt o calendario. Acepta los mismos parámetros de fechas que statistics.

Search runs — busca ejecuciones paginadas con limit y offset. De aquí obtienes run_date y run_id para consultar los endpoints de Runs y Phases.

Runs

Devuelve el detalle de una ejecución específica identificada por dag_id + run_date + run_id.

Nombre	Método	Ruta
Run summary	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}`
Event payload	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/event`

Run summary — retorna el resumen de la ejecución: estado global, duración, fases completadas, artefactos generados y métricas de filas procesadas.

Event payload — devuelve el payload de evento original que disparó la ejecución (por ejemplo, el mensaje del trigger de Airflow). Útil para depurar qué datos de entrada recibió el ETL.

Phases

Accede a los detalles de cada fase (extract, transform, load, event) de una ejecución concreta.

Nombre	Método	Ruta
Phase metadata	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}`
Phase data rows	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}/data`
Phase logs	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}/logs`
Phase logs (stream NDJSON)	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}/logs`
Phase errors	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}/errors`

Phase metadata — retorna el resumen de la fase: estado, tiempos de inicio/fin, número de filas procesadas y número de intentos (attempt). El parámetro attempt permite consultar reintentos previos.

Phase data rows — devuelve las filas de datos procesadas durante la fase, paginadas con page y limit. Permite inspeccionar qué registros procesó el ETL.

Phase logs — devuelve los logs estructurados de la fase en formato JSON paginado. Acepta los parámetros opcionales level (filtro por nivel de log) y keyword (búsqueda de texto libre).

Phase logs — stream NDJSON — es la misma ruta que Phase logs pero el header Accept: application/x-ndjson activa el modo streaming. El servidor envía cada línea de log como un objeto JSON separado por salto de línea (NDJSON), lo que permite procesar logs de gran volumen sin cargar toda la respuesta en memoria. Esta petición ya tiene el header configurado.

Cómo probar el stream

En Postman, selecciona la petición Phase logs (stream NDJSON) y haz clic en Send. Verás la respuesta llegar progresivamente en el panel inferior. Para consumirlo programáticamente usa requests con stream=True o fetch con ReadableStream.

Phase errors — devuelve únicamente los registros de log con nivel ERROR o CRITICAL, paginados. Es un atajo rápido para ver qué falló sin filtrar manualmente.

Artifacts

Lista y descarga los artefactos (archivos) generados por una ejecución: reportes, exportaciones, snapshots de datos, etc.

Nombre	Método	Ruta
List artifacts	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/artifacts`
Get artifact presigned URL	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/artifacts/{artifact_kind}`

List artifacts — retorna los artefactos disponibles para la ejecución, con su artifact_kind (tipo), tamaño y fecha de generación.

Get artifact presigned URL — devuelve una URL pre-firmada de S3 válida por tiempo limitado (~15 min) para descargar directamente el artefacto desde el navegador o con curl sin necesidad de autenticación adicional. Sustituye :artifact_kind con el valor que retornó List artifacts.

Flujo de consulta recomendado

Para llegar a los logs de una fase específica desde cero:

1. Health check          → confirma que el servicio responde
         ↓
2. List DAGs             → obtén el dag_id del ETL que te interesa
         ↓
3. Search runs           → busca por rango de fechas → obtén run_date y run_id
         ↓
4. Run summary           → confirma el estado general de la ejecución
         ↓
5. Phase logs / errors   → consulta los logs de la fase que falló
         ↓
6. List artifacts        → descarga artefactos si los hay

Para diagnóstico rápido de un fallo conocido, puedes saltar directamente al paso 5 si ya tienes dag_id, run_date, run_id y phase.

Parámetros deshabilitados

Algunas peticiones incluyen parámetros deshabilitados (marcados como inactivos en Postman). Son opcionales y están listos para activarse sin tener que escribirlos desde cero:

Petición	Parámetro deshabilitado	Cuándo activarlo
Phase logs	`level`	Filtrar por nivel: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
Phase logs	`keyword`	Buscar texto libre en el mensaje de log
Search runs	`status`	Filtrar ejecuciones por estado: `success`, `failed`, `running`
Run statistics	`status`	Filtrar contadores por estado específico

Para activar un parámetro, ábrelo en la pestaña Params de la petición y marca el checkbox a la izquierda.

Resolución de problemas comunes

401 Unauthorized — el token expiró o es incorrecto. Actualiza la variable token con un token fresco.

403 Forbidden — el token no contiene id_company. Verifica que estás usando un token de usuario o de OAuth2 generado correctamente (no un token de servicio sin empresa).

404 Not Found en runs o phases — el run_id contiene caracteres especiales (:, +, /). Asegúrate de que esté URL-encoded. Postman lo codifica automáticamente si lo dejas en la variable sin codificar manualmente.

429 Too Many Requests — se alcanzó el límite de 1 200 peticiones/minuto por IP o 60/minuto por token. Espera el tiempo indicado en el header Retry-After y reintenta. Ver Manejo de errores.

Respuesta vacía en Phase data rows — la fase no procesó filas o el attempt indicado no existe. Verifica el número de intentos en Phase metadata.

Stream NDJSON no llega en Postman — algunos proxies corporativos o versiones antiguas de Postman no manejan bien el streaming. Si no ves la respuesta llegar línea a línea, prueba desde curl:

curl -N "{{baseUrl}}/dags/{{dag_id}}/runs/{{run_date}}/{{run_id}}/phases/{{phase}}/logs?attempt=1" \
  -H "Authorization: Bearer {{token}}" \
  -H "Accept: application/x-ndjson"