Coleção Postman

A coleção centraliza todos os endpoints da API com variáveis de ambiente pré-configuradas, autenticação Bearer pronta para uso e exemplos dos parâmetros mais comuns. Permite explorar e testar a API sem precisar construir as requisições do zero.

Abrange os cinco recursos da API organizados em pastas:

Pasta	Endpoints	Descrição
Health	1	Status do serviço
DAGs	4	Listagem, estatísticas, timeline e busca de execuções
Runs	2	Resumo e payload de evento de uma execução específica
Phases	5	Metadados, dados, logs e erros por fase — com streaming NDJSON
Artifacts	2	Listagem e download de artefatos gerados por uma execução

Importar a coleção

Baixe o arquivo: hub-log-middleware.postman_collection.json
No Postman, clique em Import.
Arraste o arquivo baixado ou selecione-o pelo explorador de arquivos.
A coleção aparecerá no painel esquerdo com o nome Hub Log Middleware.

Configurar as variáveis

Antes de fazer qualquer requisição, configure as variáveis da coleção. Clique no nome da coleção e selecione a aba Variables:

Variável	Descrição	Exemplo
`baseUrl`	URL base do serviço, inclui o prefixo `/api/v1`	`https://one.fracttal.com/hub/api/v1`
`token`	Bearer token de autenticação (sem o prefixo `Bearer`)	`eyJhbGci...`
`dag_id`	Identificador do DAG a consultar	`meu-dag-exemplo`
`run_date`	Data da execução no formato `YYYY-MM-DD`	`2026-05-01`
`run_id`	Identificador completo da execução	`scheduled__2026-05-01T00:00:00+00:00`
`phase`	Fase da execução	`extract`, `transform`, `load` ou `event`

A autenticação está configurada no nível da coleção: todas as requisições herdam o token automaticamente da variável token. Só é necessário configurá-lo uma vez.

Estrutura da coleção

Health

Verifica se o serviço está ativo e disponível antes de fazer qualquer consulta.

Nome	Método	Caminho
Health check	`GET`	`/health`

Resposta esperada (200):

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

Use como primeiro passo para confirmar que o serviço responde e que seu baseUrl está corretamente configurado.

DAGs

Permite navegar pelos DAGs disponíveis para sua empresa e explorar suas execuções.

Nome	Método	Caminho
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 — retorna todos os DAGs acessíveis para a empresa do token. O campo dag_id aqui é o que você deve salvar na variável dag_id.

Run statistics — retorna contadores agrupados por status (success, failed, running) para um intervalo de datas. Os parâmetros start_date e end_date usam o formato YYYY-MM-DD e estão pré-carregados na requisição.

Run timeline — retorna as execuções ordenadas cronologicamente para construir visualizações tipo Gantt ou calendário. Aceita os mesmos parâmetros de data que statistics.

Search runs — busca execuções paginadas com limit e offset. Daqui você obtém run_date e run_id para consultar os endpoints de Runs e Phases.

Runs

Retorna os detalhes de uma execução específica identificada por dag_id + run_date + run_id.

Nome	Método	Caminho
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 o resumo da execução: status geral, duração, fases concluídas, artefatos gerados e métricas de linhas processadas.

Event payload — retorna o payload de evento original que disparou a execução (por exemplo, a mensagem do trigger do Airflow). Útil para depurar quais dados de entrada o ETL recebeu.

Phases

Acesse os detalhes de cada fase (extract, transform, load, event) de uma execução específica.

Nome	Método	Caminho
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 o resumo da fase: status, horários de início/fim, número de linhas processadas e número de tentativas (attempt). O parâmetro attempt permite consultar tentativas anteriores.

Phase data rows — retorna as linhas de dados processadas durante a fase, paginadas com page e limit. Permite inspecionar quais registros o ETL processou.

Phase logs — retorna os logs estruturados da fase em formato JSON paginado. Aceita os parâmetros opcionais level (filtro por nível de log) e keyword (busca de texto livre).

Phase logs — stream NDJSON — é o mesmo caminho que Phase logs, mas o header Accept: application/x-ndjson ativa o modo streaming. O servidor envia cada linha de log como um objeto JSON separado por quebra de linha (NDJSON), permitindo processar logs de grande volume sem carregar toda a resposta na memória. Esta requisição já tem o header configurado.

Como testar o stream

No Postman, selecione a requisição Phase logs (stream NDJSON) e clique em Send. Você verá a resposta chegando progressivamente no painel inferior. Para consumir programaticamente, use requests com stream=True ou fetch com ReadableStream.

Phase errors — retorna apenas os registros de log com nível ERROR ou CRITICAL, paginados. É um atalho rápido para ver o que falhou sem filtrar manualmente.

Artifacts

Lista e baixa os artefatos (arquivos) gerados por uma execução: relatórios, exportações, snapshots de dados, etc.

Nome	Método	Caminho
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 os artefatos disponíveis para a execução, com seu artifact_kind (tipo), tamanho e data de geração.

Get artifact presigned URL — retorna uma URL pré-assinada do S3 válida por tempo limitado (~15 min) para baixar diretamente o artefato pelo navegador ou com curl sem autenticação adicional. Substitua :artifact_kind pelo valor retornado por List artifacts.

Fluxo de consulta recomendado

Para chegar aos logs de uma fase específica do zero:

1. Health check          → confirma que o serviço responde
         ↓
2. List DAGs             → obtenha o dag_id do ETL que te interessa
         ↓
3. Search runs           → busque por intervalo de datas → obtenha run_date e run_id
         ↓
4. Run summary           → confirme o status geral da execução
         ↓
5. Phase logs / errors   → consulte os logs da fase que falhou
         ↓
6. List artifacts        → baixe artefatos se houver

Para diagnóstico rápido de uma falha conhecida, você pode ir diretamente ao passo 5 se já tiver dag_id, run_date, run_id e phase.

Parâmetros desabilitados

Algumas requisições incluem parâmetros desabilitados (marcados como inativos no Postman). São opcionais e prontos para ativar sem precisar escrevê-los do zero:

Requisição	Parâmetro desabilitado	Quando ativar
Phase logs	`level`	Filtrar por nível: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
Phase logs	`keyword`	Busca de texto livre na mensagem de log
Search runs	`status`	Filtrar execuções por status: `success`, `failed`, `running`
Run statistics	`status`	Filtrar contadores por status específico

Para ativar um parâmetro, abra-o na aba Params da requisição e marque a caixa de seleção à esquerda.

Resolução de problemas comuns

401 Unauthorized — o token expirou ou é incorreto. Atualize a variável token com um token novo.

403 Forbidden — o token não contém id_company. Verifique se está usando um token de usuário ou OAuth2 gerado corretamente (não um token de serviço sem empresa).

404 Not Found em runs ou phases — o run_id contém caracteres especiais (:, +, /). Certifique-se de que está URL-encoded. O Postman codifica automaticamente se você deixar na variável sem codificar manualmente.

429 Too Many Requests — o limite de 1.200 requisições/minuto por IP ou 60/minuto por token foi atingido. Aguarde o tempo indicado no header Retry-After e tente novamente.

Resposta vazia em Phase data rows — a fase não processou linhas ou a attempt indicada não existe. Verifique o número de tentativas em Phase metadata.

Stream NDJSON não chega no Postman — alguns proxies corporativos ou versões antigas do Postman não lidam bem com streaming. Se não vir a resposta chegando linha a linha, tente pelo 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"