API atual/Referência completa/Exportação para BI

Execuções de exportação

Executa um job na hora, reexporta tudo zerando a marca d'água e consulta o histórico das execuções.

Uma execução (run) é uma passada do job: ele lê as linhas novas, grava os arquivos no bucket e registra o resultado. Normalmente o agendador faz isso; aqui você dispara na hora, reinicia a exportação do zero e confere o histórico.

Executar agora

A rota é síncrona: só responde quando a execução termina, o que pode levar tempo em conjuntos grandes. Duas execuções do mesmo job nunca se sobrepõem: se uma já está rodando, esta recusa. Se falhar, conta como falha consecutiva (3 seguidas desativam o job).

POST/api/v1/admin/warehouse/jobs/{id}/run-nowAdmin

Executa um job agora

Exige o privilégio manage_settings (também para ler). Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/warehouse/jobs/$JOB_ID/run-now" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Execução concluída

json

{
  "id": "5f6c1d2e-9a7b-4c3d-8e21-0b4a7c9d1e55",
  "job_id": "a5e3e4c8-4e2c-4923-a53c-d2a917a7259a",
  "status": "success",
  "rows_exported": 1843,
  "object_key": "venddor/orders/v1/dt=2026-10-11/1791754534000000000_3f2a9c1e-7b4d-4e8a-9d10-2c5b6a7e8f90.parquet",
  "started_at": "2026-10-11T22:00:00.100000Z",
  "finished_at": "2026-10-11T22:00:03.800000Z"
}

Campos da resposta

iduuid

Id da execução.

job_iduuid

Job.

statusstring

runningsuccessfailed

running, success ou failed.

rows_exportedinteger

Linhas exportadas nesta execução.

object_keystring

Caminho do último arquivo gravado no bucket. Vazio se nada foi gravado.

error_messagestring

Motivo da falha, sem credenciais. Ausente em sucesso.

started_atstring

Início, RFC 3339 em UTC.

finished_atstring

Fim, RFC 3339 em UTC. Ausente enquanto roda.

Zerar a marca d'água

Volta a marca d'água do job para 1970. Na próxima execução, todas as linhas são exportadas de novo. Use depois de mudar de destino, de perder arquivos no bucket ou para uma carga inicial limpa. Os arquivos antigos não são apagados: haverá duplicatas no bucket, que o seu pipeline precisa tratar (a coluna id identifica cada linha). Responde 204.

POST/api/v1/admin/warehouse/jobs/{id}/reset-watermarkAdmin

Zera a marca d'água de um job

Exige o privilégio manage_settings (também para ler). Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/warehouse/jobs/$JOB_ID/reset-watermark" \
  -H "Authorization: Bearer $TOKEN"

Resposta

Status 204 No Content, sem corpo.

Histórico de execuções

Devolve as 50 execuções mais recentes do job, da mais nova para a mais antiga. Um job que nunca rodou devolve [].

GET/api/v1/admin/warehouse/jobs/{id}/runsAdmin

Lista as execuções de um job

Exige o privilégio manage_settings (também para ler).

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/warehouse/jobs/$JOB_ID/runs" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Execuções retornadas

json

[
  {
    "id": "5f6c1d2e-9a7b-4c3d-8e21-0b4a7c9d1e55",
    "job_id": "a5e3e4c8-4e2c-4923-a53c-d2a917a7259a",
    "status": "success",
    "rows_exported": 1843,
    "object_key": "venddor/orders/v1/dt=2026-10-11/1791754534000000000_3f2a9c1e-7b4d-4e8a-9d10-2c5b6a7e8f90.parquet",
    "started_at": "2026-10-11T22:00:00.100000Z",
    "finished_at": "2026-10-11T22:00:03.800000Z"
  },
  {
    "id": "7d1e8f20-3b4c-4a5d-9e6f-1a2b3c4d5e66",
    "job_id": "a5e3e4c8-4e2c-4923-a53c-d2a917a7259a",
    "status": "failed",
    "rows_exported": 0,
    "object_key": "",
    "error_message": "upload failed: AccessDenied",
    "started_at": "2026-10-11T21:00:00.100000Z",
    "finished_at": "2026-10-11T21:00:01.200000Z"
  }
]

A resposta é um vetor JSON direto, com os mesmos campos da execução acima.

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_settings`	`{"error":"insufficient privileges","privilege_required_any":["manage_settings"]}`
503	Exportação indisponível nesta instalação	`{"error":"warehouse export unavailable"}`
500	Execução que falhou (o corpo traz o motivo); job já em execução; `id` que não é UUID	`{"error":"job run failed","detail":"warehouse: job already running"}` / `{"error":"job run failed","detail":"upload failed: AccessDenied"}`

Veja também

API atual/Referência completa/Exportação para BI

Execuções de exportação

Executa um job na hora, reexporta tudo zerando a marca d'água e consulta o histórico das execuções.

Executar agora

POST/api/v1/admin/warehouse/jobs/{id}/run-nowAdmin

Executa um job agora

Exige o privilégio manage_settings (também para ler). Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/warehouse/jobs/$JOB_ID/run-now" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Execução concluída

json

{
  "id": "5f6c1d2e-9a7b-4c3d-8e21-0b4a7c9d1e55",
  "job_id": "a5e3e4c8-4e2c-4923-a53c-d2a917a7259a",
  "status": "success",
  "rows_exported": 1843,
  "object_key": "venddor/orders/v1/dt=2026-10-11/1791754534000000000_3f2a9c1e-7b4d-4e8a-9d10-2c5b6a7e8f90.parquet",
  "started_at": "2026-10-11T22:00:00.100000Z",
  "finished_at": "2026-10-11T22:00:03.800000Z"
}

Campos da resposta

iduuid

Id da execução.

job_iduuid

Job.

statusstring

runningsuccessfailed

running, success ou failed.

rows_exportedinteger

Linhas exportadas nesta execução.

object_keystring

Caminho do último arquivo gravado no bucket. Vazio se nada foi gravado.

error_messagestring

Motivo da falha, sem credenciais. Ausente em sucesso.

started_atstring

Início, RFC 3339 em UTC.

finished_atstring

Fim, RFC 3339 em UTC. Ausente enquanto roda.

Zerar a marca d'água

POST/api/v1/admin/warehouse/jobs/{id}/reset-watermarkAdmin

Zera a marca d'água de um job

Exige o privilégio manage_settings (também para ler). Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/warehouse/jobs/$JOB_ID/reset-watermark" \
  -H "Authorization: Bearer $TOKEN"

Resposta

Status 204 No Content, sem corpo.

Histórico de execuções

Devolve as 50 execuções mais recentes do job, da mais nova para a mais antiga. Um job que nunca rodou devolve [].

GET/api/v1/admin/warehouse/jobs/{id}/runsAdmin

Lista as execuções de um job

Exige o privilégio manage_settings (também para ler).

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/warehouse/jobs/$JOB_ID/runs" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Execuções retornadas

json

[
  {
    "id": "5f6c1d2e-9a7b-4c3d-8e21-0b4a7c9d1e55",
    "job_id": "a5e3e4c8-4e2c-4923-a53c-d2a917a7259a",
    "status": "success",
    "rows_exported": 1843,
    "object_key": "venddor/orders/v1/dt=2026-10-11/1791754534000000000_3f2a9c1e-7b4d-4e8a-9d10-2c5b6a7e8f90.parquet",
    "started_at": "2026-10-11T22:00:00.100000Z",
    "finished_at": "2026-10-11T22:00:03.800000Z"
  },
  {
    "id": "7d1e8f20-3b4c-4a5d-9e6f-1a2b3c4d5e66",
    "job_id": "a5e3e4c8-4e2c-4923-a53c-d2a917a7259a",
    "status": "failed",
    "rows_exported": 0,
    "object_key": "",
    "error_message": "upload failed: AccessDenied",
    "started_at": "2026-10-11T21:00:00.100000Z",
    "finished_at": "2026-10-11T21:00:01.200000Z"
  }
]

A resposta é um vetor JSON direto, com os mesmos campos da execução acima.

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_settings`	`{"error":"insufficient privileges","privilege_required_any":["manage_settings"]}`
503	Exportação indisponível nesta instalação	`{"error":"warehouse export unavailable"}`
500	Execução que falhou (o corpo traz o motivo); job já em execução; `id` que não é UUID	`{"error":"job run failed","detail":"warehouse: job already running"}` / `{"error":"job run failed","detail":"upload failed: AccessDenied"}`