Faturas e PDFs
Escolha a operação correta para metadados de fatura, dados estruturados do documento ou download do PDF sanitizado.
Nesta página
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.
invoice_sync_latest: últimas 1 a 120 faturas.invoice_sync_period: um mês emYYYY-MM.invoice_sync_range: intervalo inclusivo de até 36 meses.
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.
/api/v1/jobs{
"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.
{
"pdf": {
"available": true,
"fileName": "invoice_2026-07_20265042553890.pdf",
"contentType": "application/pdf",
"downloadUrl": "/api/v1/jobs/job_exemplo_01/files/20265042553890"
}
}/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.
{
"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.
{
"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:
- Crie um novo trabalho com
getPdfData: truemais tarde. A DistriSync tenta obter novamente da distribuidora todo PDF que ainda não foi entregue, mesmo comforceRefresh: false. Uma falha anterior nunca é reaproveitada. - Se você só precisa dos dados da fatura, crie o trabalho com
getPdfData: false. Ele pode ser concluído com os dados já obtidos, sem nova consulta à distribuidora.
Qual operação usar
| Necessidade | Tipo recomendado | Resultado |
|---|---|---|
| Últimas faturas | invoice_sync_latest | Itens schema 3.0 |
| Um período | invoice_sync_period | Fatura daquele mês |
| Vários períodos | invoice_sync_range | Até 36 meses |
| Somente arquivo | invoice_pdf_fetch | Descritor e download |
| Arquivo original, sem ocultação | invoice_pdf_fetch + rawPdf: true | Bytes da distribuidora |
| Campos detalhados do PDF | invoice_pdf_parse | pdf_data 2.13 |
| PDF local ou em URL pública | POST /pdf/parse | pdf_data 2.13 direto |