Trabalhos

Contrato completo para criar, consultar, paginar, cancelar e baixar arquivos vinculados a operações assíncronas.

Nesta página

Criar
Tipos
Listar para monitoramento
Consultar
Cancelar
Baixar arquivo

Criar um trabalho

POST/api/v1/jobs200 ou 202

A API pode responder HTTP 202 com estado queued ou HTTP 200 com estado completed. O corpo segue o mesmo envelope.

{
  "type": "invoice_sync_latest",
  "dist": "CELESC",
  "connectionId": "conn_exemplo_123",
  "uc": "154026601110",
  "count": 1,
  "getPdfData": false,
  "forceRefresh": false
}

{
  "schemaVersion": "3.0",
  "jobId": "job_exemplo_01",
  "type": "invoice_sync_period",
  "status": "queued",
  "dist": "CELESC",
  "connectionId": "conn_exemplo_123",
  "createdAt": "2026-08-24T14:00:00Z"
}

{
  "error": {
    "code": "invalid_uc",
    "message": "UC must contain ASCII digits only.",
    "retryable": false,
    "details": {}
  }
}

Campo	Tipo	Obrigatório	Descrição
`type`	string	sim	Tipo do trabalho. Consulte a tabela de tipos aceitos.
`dist`	string	sim	Código da distribuidora: CELESC ou COPEL.
`connectionId`	string	sim	Conexão pertencente ao mesmo cliente da chave de API.
`uc`	string	por tipo	UC com somente dígitos ASCII. Aceita identificador atual ou legado.
`count`	integer	latest	Quantidade de faturas mais recentes, de 1 a 120.
`billingPeriod`	string	period	Período de faturamento no formato YYYY-MM.
`from`	string	range	Primeiro período, inclusivo, no formato YYYY-MM.
`to`	string	range	Último período, inclusivo, no formato YYYY-MM; intervalo máximo de 36 meses.
`invoiceId`	string	alternativa	Fatura específica para operações de PDF. Não converta para número.
`latestCount`	integer	alternativa	Quantidade das faturas mais recentes para uma operação de PDF ou sincronização completa.
`getPdfData`	boolean	não	Quando true, inclui o objeto estruturado pdf_data e disponibiliza o PDF sanitizado.
`includePdfFetch`	boolean	não	Em installation_sync, também disponibiliza os PDFs sanitizados.
`includePdfParse`	boolean	não	Em installation_sync, também inclui pdf_data.
`forceRefresh`	boolean	não	Quando true, solicita dados atuais à distribuidora para esta operação.

Tipos de trabalho

`type`	Entrega	Seletores
`uc_discovery`	Lista todas as UCs disponíveis para a conexão.	dist, connectionId
`invoice_sync_latest`	Retorna as últimas N faturas.	uc, count
`invoice_sync_period`	Retorna um período de faturamento.	uc, billingPeriod
`invoice_sync_range`	Retorna um intervalo de até 36 meses.	uc, from, to
`invoice_pdf_fetch`	Disponibiliza PDFs sanitizados.	uc + invoiceId ou latestCount
`invoice_pdf_parse`	Retorna pdf_data estruturado.	uc + invoiceId ou latestCount
`installation_sync`	Executa sincronização completa de uma UC.	uc, latestCount e opções

Os três tipos de sincronização aceitam getPdfData. Os tipos de PDF aceitam uma fatura por invoiceId ou várias por latestCount.

Listar para monitoramento

GET/api/v1/jobs?status=FAILED&createdWithin=24h&limit=1

Esta rota lista resumos de trabalhos em ordem decrescente de createdAt. Ela aceita uma chave de cliente, sempre limitada ao próprio tenant, ou uma chave administrativa vinculada a um IP para consultas entre clientes.

O campo count informa o total exato que corresponde aos filtros, antes da paginação. A lista jobs não inclui result nem arquivos.

Consultar e paginar

GET/api/v1/jobs/{jobId}?limit=50&offset=0

limit varia de 1 a 200 e usa 50 por padrão. offset começa em 0. A paginação altera somente result.items; result.count continua indicando o total de itens do trabalho.

Exemplo: 600 UCs em páginas de 200

Depois de concluir um trabalho uc_discovery, consulte sempre o mesmo jobId. Se a primeira resposta trouxer offset: 0 e hasMore: true, avance o offset pelo limit retornado.

GET/api/v1/jobs/{jobId}?limit=200&offset=0itens 1–200

{
  "result": {
    "count": 600,
    "pagination": {
      "limit": 200,
      "offset": 0,
      "hasMore": true
    }
  }
}

GET/api/v1/jobs/{jobId}?limit=200&offset=200itens 201–400

GET/api/v1/jobs/{jobId}?limit=200&offset=400itens 401–600; hasMore: false

Pare quando result.pagination.hasMore for false. Para evitar suposições, calcule a próxima posição como pagination.offset + pagination.limit, usando os valores efetivamente retornados pela API.

const items = [];
let offset = 0;
const limit = 200;
let hasMore;

do {
  const response = await fetch(
    `${BASE_URL}/jobs/${jobId}?limit=${limit}&offset=${offset}`,
    { headers: { "X-API-Key": API_KEY } },
  );
  const job = await response.json();

  items.push(...job.result.items);
  hasMore = job.result.pagination.hasMore;
  offset = job.result.pagination.offset + job.result.pagination.limit;
} while (hasMore);

Trabalho duplicado

Um trabalho ativo com o mesmo alvo retorna HTTP 409 job_already_exists. Consulte o details.jobId já existente.

Cancelar

POST/api/v1/jobs/{jobId}/cancel

Retorna 200 e cancelled: true quando o cancelamento é imediato, ou 202 e status: "cancelling" quando ainda precisa concluir. Estados terminais retornam job_not_cancellable.

Baixar arquivo do trabalho

GET/api/v1/jobs/{jobId}/files/{invoiceId}

Disponível somente quando o item retornou pdf.available: true. A URL completa está em pdf.downloadUrl. Um arquivo que não pertence ao trabalho retorna invoice_not_found.