Monitorar trabalhos

Liste trabalhos sem expor resultados

A rota retorna resumos em ordem decrescente de createdAt. Ela foi projetada para responder perguntas operacionais, como “houve algum trabalho com falha nas últimas 24 horas?”, sem transferir o resultado completo ou arquivos do trabalho.

GET /v1/jobs é um alias, mas use /api/v1/jobs nas novas integrações.

Autenticação e escopo

A chave administrativa pertence a uma conta platform_admin, permite um único IPv4 ou IPv6 sem CIDR e deixa de funcionar imediatamente quando revogada ou regenerada. O segredo completo é exibido somente na emissão.

O administrador cria e gerencia sua credencial em /admin/api. O nome da chave aceita de 2 a 120 caracteres, e cada conta administrativa pode manter uma chave ativa. A regeneração preserva o nome e o IP permitido, revoga o segredo anterior e exibe o novo segredo uma única vez. Para trocar o IP, revogue a chave e crie outra.

Combine filtros

Todos os filtros informados são combinados. Sem filtros de data, a consulta considera todo o histórico disponível.

Os estados aceitos são queued, running, cancelling, completed, partial_success, failed, cancelled e expired. A duração relativa aceita um valor de 1 a 9999 seguido por m, h, d ou w.

Não há filtros por tipo de trabalho, jobId, connectionId, UC, código de erro ou updatedAt.

Interprete a resposta

count é o total exato antes da paginação. jobs contém a página atual e pagination.hasMore informa se há outra. Cada resumo pode trazer alvo, progresso, erro e datas do ciclo de vida, além de tenantId e updatedAt.

A resposta envia Cache-Control: no-store. Os campos result e files são omitidos mesmo quando o trabalho já terminou.

{
  "schemaVersion": "3.0",
  "filters": {
    "status": "failed",
    "clientId": "client_123",
    "clientName": "Cliente Exemplo",
    "dist": "CELESC",
    "createdFrom": "2026-09-02T12:00:00+00:00",
    "createdTo": "2026-09-03T12:00:00+00:00",
    "createdWithin": "24h"
  },
  "count": 0,
  "jobs": [],
  "pagination": {
    "limit": 1,
    "offset": 0,
    "hasMore": false
  }
}

{
  "schemaVersion": "3.0",
  "filters": {
    "status": "failed",
    "clientId": "client_123",
    "clientName": null,
    "dist": "CELESC",
    "createdFrom": "2026-09-02T12:00:00+00:00",
    "createdTo": "2026-09-03T12:00:00+00:00",
    "createdWithin": "24h"
  },
  "count": 1,
  "jobs": [
    {
      "schemaVersion": "3.0",
      "jobId": "job_01JABC",
      "type": "invoice_sync_period",
      "status": "failed",
      "dist": "CELESC",
      "connectionId": "conn_123",
      "target": {
        "uc": "154026601110",
        "billingPeriod": "2026-08"
      },
      "progress": { "total": 1, "completed": 0, "failed": 1 },
      "error": {
        "code": "distributor_unavailable",
        "message": "The distributor is temporarily unavailable.",
        "retryable": true,
        "details": {}
      },
      "createdAt": "2026-09-03T10:00:00+00:00",
      "startedAt": "2026-09-03T10:00:03+00:00",
      "completedAt": "2026-09-03T10:00:09+00:00",
      "tenantId": "client_123",
      "updatedAt": "2026-09-03T10:00:09+00:00"
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "hasMore": false }
}

Exemplos de monitoramento

Falhas CELESC do próprio cliente nas últimas 24 horas

curl \
  -H "X-API-Key: <CHAVE_DO_CLIENTE>" \
  "<URL_BASE>/jobs?status=FAILED&dist=CELESC&createdWithin=24h&limit=1"

Falhas de um cliente selecionado pelo nome

curl \
  -H "X-API-Key: <CHAVE_ADMINISTRATIVA>" \
  "<URL_BASE>/jobs?status=FAILED&clientName=Cliente%20Exemplo&createdWithin=24h&limit=1"

Um administrador pode usar clientId=client_123 ou omitir os dois filtros para consultar todos os clientes. Um nome ou ID inexistente retorna count: 0. Se clientId e clientName forem enviados juntos, precisam identificar o mesmo cliente.

Gatus

endpoints:
  - name: Jobs DistriSync sem falhas
    group: DistriSync
    url: "https://api.example.com/api/v1/jobs?status=FAILED&dist=CELESC&createdWithin=24h&limit=1"
    method: GET
    interval: 5m
    headers:
      X-API-Key: "${DISTRISYNC_MONITORING_KEY}"
    conditions:
      - "[STATUS] == 200"
      - "[BODY].count == 0"

Guarde a chave em uma variável de ambiente ou gerenciador de segredos. Para monitoramento global, substitua pela chave administrativa e cadastre o IP público de saída do Gatus.

Erros específicos da listagem

Um nome de cliente desconhecido retorna uma lista vazia. Se dados legados contiverem mais de um cliente com o mesmo nome, a API retorna ambiguous_client_name; repita usando clientId.