Faturas e PDFs

Escolha a operação correta para metadados de fatura, dados estruturados do documento ou download do PDF sanitizado.

Nesta página
  1. Sincronizar faturas
  2. Obter pdf_data
  3. Ler um PDF avulso
  4. Baixar PDF
  5. PDF original
  6. PDF indisponível
  7. Escolher operação

Sincronize os metadados

Use invoice_sync_latest, invoice_sync_period ou invoice_sync_range. Todos retornam faturas com schema 3.0. Consulte os campos específicos no schema COPEL ou no schema CELESC.

Obtenha pdf_data

Use invoice_pdf_parse quando precisa das tabelas detalhadas do documento. Como alternativa, defina getPdfData: true em um trabalho de sincronização.

POST/api/v1/jobs
Corpo da requisiçãojson
{
  "type": "invoice_pdf_parse",
  "dist": "COPEL",
  "connectionId": "conn_exemplo_123",
  "uc": "000093254403147",
  "invoiceId": "20265042553890",
  "forceRefresh": false
}

Leia um PDF que você já possui

Se o arquivo já está com você ou disponível em uma URL pública, use o POST /api/v1/pdf/parse. A resposta síncrona contém pdf_data diretamente e dispensa conexão, trabalho e polling.

Baixe o PDF sanitizado

Use invoice_pdf_fetch ou uma sincronização com getPdfData: true. O item retornará um descritor pdf.

Descritor no itemjson
{
  "pdf": {
    "available": true,
    "fileName": "invoice_2026-07_20265042553890.pdf",
    "contentType": "application/pdf",
    "downloadUrl": "/api/v1/jobs/job_exemplo_01/files/20265042553890"
  }
}
GET/api/v1/jobs/{jobId}/files/{invoiceId}

Envie a mesma X-API-Key. A resposta tem Content-Type: application/pdf e Content-Disposition com o nome do arquivo.

Receba o PDF original, sem ocultação

Por padrão, dados sensíveis como nome, CPF/CNPJ, endereço, identificadores da unidade e códigos de pagamento são ocultados no PDF antes do cache e do download. Quando todos os dados das faturas pertencem ao próprio cliente da integração, por exemplo um consórcio, defina rawPdf: true no trabalho. O download retorna os bytes exatamente como a distribuidora os entrega.

Corpo da requisiçãojson
{
  "type": "invoice_pdf_fetch",
  "dist": "COPEL",
  "connectionId": "conn_exemplo_123",
  "uc": "000093254403147",
  "invoiceId": "20265042553890",
  "rawPdf": true
}

rawPdf vale para invoice_pdf_fetch, invoice_pdf_parse, installation_sync com includePdfFetch: true e sincronizações com getPdfData: true. Na rota por conexão, use o parâmetro raw_pdf=true em GET /api/v1/connections/{connectionId}/invoices/{invoiceId}/pdf.

Quando o PDF não está disponível

Em invoice_sync_latest, invoice_sync_period e invoice_sync_range com getPdfData: true, uma instabilidade temporária da distribuidora ao gerar o PDF não descarta a fatura. O item continua no resultado com os dados da fatura, inclusive situação de pagamento e PIX quando a distribuidora os fornece. pdf_data fica vazio, pdf.available é false e pdf.error explica o motivo. O trabalho termina como partial_success e progress.failed conta os itens sem PDF.

Trabalho com um PDF indisponível (itens resumidos)json200 OK
{
  "schemaVersion": "3.0",
  "jobId": "job_exemplo_02",
  "type": "invoice_sync_latest",
  "status": "partial_success",
  "dist": "COPEL",
  "connectionId": "conn_exemplo_123",
  "createdAt": "2026-11-12T19:49:21Z",
  "target": { "uc": "000093254403147", "count": 2, "getPdfData": true },
  "progress": { "total": 2, "completed": 1, "failed": 1 },
  "startedAt": "2026-11-12T19:49:21Z",
  "completedAt": "2026-11-12T19:49:40Z",
  "result": {
    "schemaVersion": "3.0",
    "count": 2,
    "items": [
      {
        "schemaVersion": "3.0",
        "dist": "COPEL",
        "invoice": { "id": "20265042553890", "billingPeriod": "2026-10", "dueDate": "2026-12-15", "amount": 248.42, "currency": "BRL" },
        "payment": { "status": "open", "barcode": null, "pixQrCode": "00020101021226..." },
        "pdf_data": {},
        "pdf": {
          "available": false,
          "error": {
            "code": "pdf_unavailable",
            "message": "The invoice PDF could not be downloaded because the distributor is temporarily unavailable. Invoice data is still returned.",
            "retryable": true,
            "details": { "cause": "distributor_unavailable" }
          }
        },
        "lastUpdated": "2026-11-12T19:49:38Z"
      },
      {
        "schemaVersion": "3.0",
        "dist": "COPEL",
        "invoice": { "id": "20265042014482", "billingPeriod": "2026-09", "dueDate": "2026-11-14", "amount": 231.07, "currency": "BRL" },
        "payment": { "status": "paid", "barcode": null, "pixQrCode": null },
        "pdf_data": { "schema_version": "2.13" },
        "pdf": {
          "available": true,
          "fileName": "invoice_2026-09_20265042014482.pdf",
          "contentType": "application/pdf",
          "downloadUrl": "/api/v1/jobs/job_exemplo_02/files/20265042014482"
        },
        "lastUpdated": "2026-11-12T19:49:40Z"
      }
    ],
    "pagination": { "limit": 50, "offset": 0, "hasMore": false }
  }
}

Antes de baixar, confira pdf.available em cada item. Para obter o PDF que faltou:

Qual operação usar

NecessidadeTipo recomendadoResultado
Últimas faturasinvoice_sync_latestItens schema 3.0
Um períodoinvoice_sync_periodFatura daquele mês
Vários períodosinvoice_sync_rangeAté 36 meses
Somente arquivoinvoice_pdf_fetchDescritor e download
Arquivo original, sem ocultaçãoinvoice_pdf_fetch + rawPdf: trueBytes da distribuidora
Campos detalhados do PDFinvoice_pdf_parsepdf_data 2.13
PDF local ou em URL públicaPOST /pdf/parsepdf_data 2.13 direto

Digite para buscar em guias, referências, schemas e erros.