Schema COPEL

Campos completos da fatura COPEL, exemplos, enums, mapeamentos e estrutura de pdf_data 2.13.

Nesta página

Contrato da fatura
Exemplo de fatura
Campos da fatura
Valores da fatura
pdf_data
Campos do PDF
Vocabulário do PDF
Mapeamentos
Valores observados
Qualidade e revisão

Contrato da fatura

Esta página descreve cada item de fatura com dist: "COPEL" e schemaVersion: "3.0". Nos trabalhos, leia result.items[]; nas consultas por conexão, leia invoices[].

A fatura COPEL contém identificação, cobrança, situação de pagamento, grupo tarifário e consumo. Os detalhes impressos de leitura, bandeiras, tributos, itens e histórico ficam em pdf_data quando solicitados.

Campos previstos permanecem presentes com null quando o valor não está disponível. Zero é um valor informado. pdf_data usa quando não solicitado e pdf usa null quando não há descritor de download. Todos os exemplos desta página são fictícios.

Exemplo completo de fatura sem PDF

{
  "schemaVersion": "3.0",
  "dist": "COPEL",
  "consumerUnit": {
    "installationId": "000123456789012",
    "legacyInstallationId": "12345678",
    "contractAccount": "12345678",
    "city": "Curitiba"
  },
  "invoice": {
    "id": "000000000001",
    "billingPeriod": "2026-08",
    "dueDate": "2026-09-15",
    "amount": 120.5,
    "currency": "BRL"
  },
  "payment": {
    "status": "open",
    "paidAt": null,
    "sourceStatus": "AB",
    "sourceCompensation": "A vencer"
  },
  "tariff": {
    "group": "B",
    "sourceGroup": "B"
  },
  "energy": {
    "unit": "kWh",
    "consumed": 150
  },
  "normalization": {
    "status": "normalized",
    "issues": []
  },
  "pdf_data": {},
  "pdf": null,
  "lastUpdated": "2026-09-04T12:00:00-03:00"
}

Todos os campos da fatura

Campo	Tipo	Descrição
`schemaVersion`	string	Versão do recurso: 3.0.
`dist`	string	COPEL.
`consumerUnit.installationId`	string	Identificador atual e canônico da UC.
`consumerUnit.legacyInstallationId`	string \| null	Identificador anterior quando fornecido.
`consumerUnit.contractAccount`	string \| null	Conta contrato quando fornecida.
`consumerUnit.city`	string \| null	Município disponível no resultado da distribuidora.
`invoice.id`	string	Identificador da fatura; preserva zeros à esquerda.
`invoice.billingPeriod`	string	Mês de referência em YYYY-MM.
`invoice.dueDate`	date \| null	Vencimento em YYYY-MM-DD.
`invoice.amount`	number \| null	Total em unidade monetária principal.
`invoice.currency`	string \| null	BRL quando informada; null quando indisponível.
`payment.status`	enum	paid, open, overdue ou unknown.
`payment.paidAt`	date \| null	Data de pagamento quando informada.
`payment.sourceStatus`	string \| null	Código original de status da distribuidora.
`payment.sourceCompensation`	string \| null	Rótulo original de compensação ou liquidação.
`tariff.group`	string \| null	Grupo tarifário normalizado quando disponível.
`tariff.sourceGroup`	string \| null	Grupo como retornado pela distribuidora.
`energy.unit`	string	Unidade dos campos de energia; normalmente kWh.
`energy.consumed`	number \| null	Energia consumida no período.
`normalization.status`	enum	normalized ou review_required.
`normalization.issues[]`	array	Avisos de mapeamento e validação.
`normalization.issues[].code`	string	Código estável do aviso.
`normalization.issues[].field`	string	Caminho do campo afetado.
`normalization.issues[].severity`	string	Nível do aviso, normalmente warning ou error.
`normalization.issues[].message`	string	Explicação legível do aviso.
`pdf_data`	object	{} quando não solicitado; schema 2.13 sanitizado quando solicitado.
`pdf`	object \| null	Descritor de download em trabalhos que disponibilizam PDF.
`pdf.available`	boolean	Indica que o arquivo pode ser baixado.
`pdf.fileName`	string	Nome sugerido para o arquivo.
`pdf.contentType`	string	application/pdf.
`pdf.downloadUrl`	string	Rota autenticada e vinculada ao trabalho.
`lastUpdated`	datetime	Última atualização do recurso em ISO 8601 com offset.

Valores da fatura

payment.status: paid (paga), open (em aberto, sem vencimento passado), overdue (vencida) ou unknown (situação não identificada). A data de vencimento participa da situação retornada; um rótulo de origem isolado não substitui status.

payment.sourceStatus conserva o código da COPEL. Os códigos observados são AB, AR e DA. AB aparece em faturas abertas; AR, em pagas. DA não tem equivalência isolada documentada: use status, sourceCompensation e os avisos de normalização.

payment.sourceCompensation apresentou A vencer, Vencida, Paga e Demonstrativa. Uma fatura demonstrativa pode ter total indisponível; isso não equivale a total zero ou a confirmação de pagamento.

tariff.group aceita A, B ou null. tariff.sourceGroup conserva o rótulo informado. Para bandeiras, consulte pdf_data.tariff_flag.

normalization.status aceita normalized e review_required. As severidades dos avisos são warning e error.

pdf_data 2.13

Solicite getPdfData: true em um trabalho de sincronização, invoice_pdf_parse, ou includePdfParse: true em installation_sync. Nas consultas por conexão, use get_pdf_data=true.

O objeto tem os mesmos campos nas duas distribuidoras. As tabelas abaixo descrevem o conteúdo esperado para COPEL. Campos numéricos ausentes usam null; tabelas sem linhas usam []. Um null em campo obrigatório para a interpretação da fatura exige consultar quality.issues.

consumer_unit.installation_id é o identificador impresso no PDF e pode ser atual ou legado. Não existe consumer_unit.legacy_installation_id neste objeto. Os dois identificadores da fatura continuam disponíveis em consumerUnit, fora de pdf_data.

{
  "schema_version": "2.13",
  "consumer_unit": {
    "client_id": null,
    "installation_id": "000123456789012",
    "city": "Curitiba",
    "state": "PR",
    "classification": "residential",
    "tariff_group": "B",
    "tariff_subgroup": "B1",
    "tariff_category": "b1_residential",
    "supply_type": "single_phase",
    "source_labels": {
      "pdf_installation": "000123456789012",
      "classification": "residencial",
      "tariff_category": "B1 Residencial",
      "supply_type": "monofasico",
      "group": "B"
    }
  },
  "billing": {
    "reference_month": "2026-08",
    "due_date": "2026-09-15",
    "total_amount": 120.5,
    "currency": "BRL"
  },
  "reading": {
    "previous_date": "2026-08-01",
    "current_date": "2026-08-31",
    "next_date": "2026-09-30",
    "billed_days": 30,
    "method": "not_reported",
    "source_method": "nao_informada"
  },
  "tariff_flag": {
    "name": "green",
    "total_days": 30,
    "periods": [
      {
        "name": "green",
        "days": 30,
        "additional_unit_price": 0,
        "unit": "BRL/kWh",
        "source_name": "Verde"
      }
    ]
  },
  "meter_readings": [
    {
      "meter_id": "000001",
      "measurement": "consumed_energy",
      "time_slot": "single",
      "unit": "kWh",
      "previous_reading": 1050,
      "current_reading": 1200,
      "multiplier": 1,
      "losses": 0,
      "measured_quantity": 150,
      "source_measurement": "Energia consumida",
      "source_time_slot": "TP"
    }
  ],
  "taxes": [
    {
      "type": "icms",
      "source_name": "ICMS",
      "base_amount": 120.5,
      "rates_percent": [
        12
      ],
      "source_rate": "12",
      "amount": 14.46
    }
  ],
  "line_items": [
    {
      "provider_code": null,
      "type": "energy_consumption",
      "component": "te",
      "tariff_flag": null,
      "effect": "charge",
      "source_description": "Energia eletrica consumo",
      "unit": "kWh",
      "quantity": 150,
      "unit_price_with_taxes": 0.8033333333,
      "amount": 120.5,
      "pis_cofins_amount": null,
      "icms_base_amount": null,
      "icms_rates_percent": [],
      "icms_amount": null,
      "tariff_unit_price": null
    }
  ],
  "history": [
    {
      "metric": "consumption",
      "source_name": "Consumo",
      "unit": "kWh",
      "values": {
        "2026-08": 150
      }
    }
  ],
  "document": {
    "provider": "COPEL",
    "invoice_id": "000000000001",
    "layout": "copel_danf3e_a4_v1"
  },
  "quality": {
    "score": 1,
    "status": "parsed",
    "api_cross_validated": false,
    "issues": []
  }
}

Todos os campos de pdf_data

Os caminhos desta tabela são relativos a pdf_data.

Campo	Tipo	Descrição
`schema_version`	string	Versão do objeto pdf_data: 2.13.
`consumer_unit.client_id`	string \| null	Identificador do cliente impresso no documento, quando distinto da UC.
`consumer_unit.installation_id`	string \| null	Identificador impresso no PDF; pode ser atual ou legado. Compare com os identificadores de consumerUnit.
`consumer_unit.city`	string \| null	Município extraído.
`consumer_unit.state`	string \| null	UF extraída.
`consumer_unit.classification`	enum \| null	Classificação canônica do consumidor.
`consumer_unit.tariff_group`	string \| null	Grupo tarifário, como A ou B.
`consumer_unit.tariff_subgroup`	string \| null	Subgrupo, como B1 ou B3.
`consumer_unit.tariff_category`	string \| null	Categoria composta, por exemplo b1_residential.
`consumer_unit.supply_type`	enum \| null	single_phase, two_phase ou three_phase.
`consumer_unit.source_labels`	object	Rótulos originais usados na normalização.
`consumer_unit.source_labels.pdf_installation`	string \| null	Instalação exatamente como lida do PDF.
`consumer_unit.source_labels.classification`	string \| null	Classificação impressa.
`consumer_unit.source_labels.tariff_category`	string \| null	Categoria tarifária impressa.
`consumer_unit.source_labels.supply_type`	string \| null	Tipo de fornecimento impresso.
`consumer_unit.source_labels.group`	string \| null	Grupo impresso, como B. Pode conter grupo A em faturas de geração.
`billing.reference_month`	string \| null	Mês de referência em YYYY-MM.
`billing.due_date`	date \| null	Vencimento em YYYY-MM-DD.
`billing.total_amount`	number \| null	Total da fatura em unidade monetária principal.
`billing.currency`	string	Moeda ISO; atualmente BRL.
`reading.previous_date`	date \| null	Data da leitura anterior.
`reading.current_date`	date \| null	Data da leitura atual.
`reading.next_date`	date \| null	Próxima leitura prevista.
`reading.billed_days`	integer \| null	Quantidade de dias faturados.
`reading.method`	enum	actual, estimated, customer_reported ou not_reported. Nos documentos consultados, not_reported; datas e dias podem estar preenchidos.
`reading.source_method`	string \| null	Método como impresso no documento.
`tariff_flag.name`	enum	Bandeira consolidada do período.
`tariff_flag.total_days`	integer \| null	Total de dias coberto pelas bandeiras.
`tariff_flag.periods[]`	array	Períodos de bandeira encontrados no documento.
`tariff_flag.periods[].name`	enum	Bandeira canônica daquele trecho.
`tariff_flag.periods[].days`	integer \| null	Dias cobertos pelo trecho.
`tariff_flag.periods[].additional_unit_price`	number \| null	Adicional unitário da bandeira.
`tariff_flag.periods[].unit`	string	BRL/kWh.
`tariff_flag.periods[].source_name`	string \| null	Nome da bandeira como impresso.
`meter_readings[].meter_id`	string \| null	Identificador do medidor.
`meter_readings[].measurement`	enum	consumed_energy, injected_energy, reactive_energy, demand ou not_reported.
`meter_readings[].time_slot`	enum	single, peak, off_peak, intermediate, reserved ou not_reported.
`meter_readings[].unit`	string \| null	Unidade da medição.
`meter_readings[].previous_reading`	number \| null	Leitura anterior.
`meter_readings[].current_reading`	number \| null	Leitura atual.
`meter_readings[].multiplier`	number \| null	Constante multiplicadora.
`meter_readings[].losses`	number \| null	Perdas aplicadas.
`meter_readings[].measured_quantity`	number \| null	Quantidade apurada.
`meter_readings[].source_measurement`	string \| null	Nome original da grandeza.
`meter_readings[].source_time_slot`	string \| null	Nome original do posto horário.
`taxes[].type`	string	Tipo canônico, como pis, cofins ou icms.
`taxes[].source_name`	string \| null	Nome do tributo no PDF.
`taxes[].base_amount`	number \| null	Base de cálculo.
`taxes[].rates_percent`	number[]	Alíquotas em pontos percentuais; 12 significa 12%.
`taxes[].source_rate`	string \| null	Alíquota como impressa.
`taxes[].amount`	number \| null	Valor do tributo.
`line_items[].provider_code`	string \| null	Código impresso, quando houver; null nos itens sem código. Consulte type e source_description.
`line_items[].type`	enum	Tipo canônico do item faturado.
`line_items[].component`	enum \| null	te, tusd ou null.
`line_items[].tariff_flag`	enum \| null	Bandeira associada ao item.
`line_items[].effect`	enum	charge, credit ou neutral.
`line_items[].source_description`	string \| null	Descrição original do item.
`line_items[].unit`	string \| null	Unidade física.
`line_items[].quantity`	number \| null	Quantidade física não negativa.
`line_items[].unit_price_with_taxes`	number \| null	Preço unitário com tributos.
`line_items[].amount`	number \| null	Valor com sinal contábil; créditos são negativos.
`line_items[].pis_cofins_amount`	number \| null	Parcela de PIS/COFINS.
`line_items[].icms_base_amount`	number \| null	Base de cálculo do ICMS.
`line_items[].icms_rates_percent`	number[]	Alíquotas de ICMS em pontos percentuais.
`line_items[].icms_amount`	number \| null	Valor de ICMS.
`line_items[].tariff_unit_price`	number \| null	Tarifa unitária sem arredondamento indevido.
`history[].metric`	string	Métrica canônica da série.
`history[].source_name`	string \| null	Nome original da série.
`history[].unit`	string	kWh ou day.
`history[].values`	object	Mapa YYYY-MM para number ou null.
`document.provider`	string \| null	COPEL.
`document.invoice_id`	string \| null	Identificador da fatura.
`document.layout`	string \| null	Família de layout reconhecida.
`quality.score`	number	Pontuação de 0 a 1.
`quality.status`	enum	verified, parsed, partial ou invalid.
`quality.api_cross_validated`	boolean	Indica comparação com metadados da resposta de fatura.
`quality.issues[]`	array	Avisos e erros encontrados na validação.
`quality.issues[].code`	string	Código estável do problema.
`quality.issues[].field`	string	Campo afetado.
`quality.issues[].severity`	enum	warning ou error.
`quality.issues[].message`	string	Explicação legível do problema.

Vocabulário aceito do PDF

Estes são os valores reconhecidos pelo contrato. Nem todos aparecem em toda fatura ou no conjunto de exemplos observado. Campos textuais, como descrições, códigos de origem e nomes de séries, não são enums fechados.

Campo	Tipo	Descrição
`consumer_unit.classification`	enum \| null	commercial, industrial, own_consumption, public_lighting, public_power, public_service, residential, rural. null quando não identificada.
`consumer_unit.supply_type`	enum \| null	single_phase, three_phase, two_phase. null quando não identificado.
`consumer_unit.tariff_group`	enum \| null	A ou B; null quando não identificado.
`consumer_unit.tariff_subgroup`	enum \| null	A1, A2, A3, A3A, A4, AS, B1, B2, B3 ou B4; null quando não identificado.
`consumer_unit.tariff_category`	string \| null	Subgrupo em minúsculas + classificação, como b1_residential ou a4_commercial. null se não houver subgrupo ou classificação.
`reading.method`	enum	actual, customer_reported, estimated, not_reported.
`tariff_flag.name / periods[].name / line_items[].tariff_flag`	enum	green, mixed, not_reported, red, red_tier_1, red_tier_2, water_scarcity, yellow. No item, null quando não se aplica.
`meter_readings[].measurement`	enum	consumed_energy, injected_energy, reactive_energy, demand ou not_reported.
`meter_readings[].time_slot`	enum	intermediate, not_reported, off_peak, peak, reserved, single.
`meter_readings[].unit`	enum \| null	kWh, kW ou kvarh conforme a unidade impressa. Energia consumida e injetada usam kWh quando o documento não separa a unidade; outras grandezas sem unidade identificada usam null.
`line_items[].unit`	enum \| null	kWh, MWh, kW, kvarh ou unit; null quando não informada ou não reconhecida.
`line_items[].type`	enum	energy_consumption, injected_energy, energy_adjustment, tariff_flag, municipal_public_lighting, late_payment_penalty, interest, monetary_adjustment, compensation, bonus, refund, demand, reactive_energy, other, balance_adjustment, donation, service_fee.
`taxes[].type`	string	icms, pis e cofins são os nomes conhecidos. Outros tributos podem aparecer com um nome em snake_case; other quando não identificado.
`line_items[].component`	enum \| null	te (energia), tusd (uso do sistema de distribuição) ou null.
`line_items[].effect`	enum	charge para valor positivo; credit para valor negativo; neutral para valor zero ou ausente. Consulte amount e quality antes de concluir que não houve cobrança.
`history[].metric`	string	Nome da série em snake_case. Os nomes conhecidos para esta distribuidora estão abaixo; o campo admite outras séries, acompanhadas de source_name.
`quality.status`	enum	verified, parsed, partial ou invalid.
`quality.issues[].severity`	enum	warning ou error.
`document.layout`	string	copel_danf3e_a4_v1, copel_generator_danf3e_a4_v1, copel_legacy_nf_conta_energia.

Mapeamentos e significado

Residencial corresponde a residential, comercial a commercial, industrial a industrial e rural a rural. Monofásico, bifásico e trifásico correspondem a single_phase, two_phase e three_phase. Os rótulos impressos ficam em consumer_unit.source_labels.

Verde, amarela, vermelha patamar 1 e vermelha patamar 2 correspondem a green, yellow, red_tier_1 e red_tier_2. Vermelha sem patamar usa red; mixed indica uma combinação de bandeiras. Consulte tariff_flag.periods[] para todos os trechos, mesmo quando o resumo indicar uma única bandeira.

Itens COPEL

Use type para a categoria e source_description para o significado completo do lançamento. Créditos têm amount negativo; quantidades e preços unitários são apresentados em valor absoluto.

Descrição	type	Significado
Energia elétrica consumo / uso do sistema	`energy_consumption`	te para energia; tusd para uso do sistema.
Energia injetada / energia inj.	`injected_energy`	Crédito ou cobrança conforme effect e amount.
Bandeira / B. amarela / B. vermelha	`tariff_flag`	A bandeira do item aparece em tariff_flag.
Tribut. dif. out. UC	`energy_adjustment`	Ajuste de energia relativo a outra UC.
Compensação / crédito / DIC mensal	`compensation`	O motivo completo permanece em source_description.
COSIP / iluminação pública	`municipal_public_lighting`	Contribuição de iluminação pública.
Multa / juros / acréscimo moratório ou correção	`late_payment_penalty / interest / monetary_adjustment`	Encargos distintos; não agrupe como consumo.
Bônus / devolução	`bonus / refund`	Consulte effect para o sinal contábil.
Demanda / energia reativa	`demand / reactive_energy`	Grandezas distintas do consumo ativo; consulte unit.
Valor ref. conta do mês / dev. conta anterior / diferença de saldo negativo	`balance_adjustment`	Ajuste de saldo de outra fatura; consulte effect e amount para distinguir crédito e cobrança.
Créd. violação de meta de continuidade	`compensation`	Crédito associado à meta de continuidade.
Dev. corr. monetária ajuste fat.	`monetary_adjustment`	Correção monetária de ajuste de fatura.
Dev. diferença a maior conta anterior	`refund`	Devolução de diferença da conta anterior.
Energia reat. exced. TE ponta / fora de ponta	`reactive_energy`	Energia reativa excedente; não confundir com consumo ativo.
Taxa visita técnica / serviço de entrega especial de fatura	`service_fee`	Cobrança de serviço.
Doação / Fund. Pró-Renal / Erasto Gaertner / Projeto Vida	`donation`	Doação identificada no lançamento; descrição original preservada.
Demais descrições	`other`	Descrição preservada; revise antes de classificar em sua aplicação.

Descrições FAT.NOVADAS-... e INEXIST.DOCUM.FAT.DESCONSOLIDADA permanecem como other. Consulte a descrição e o valor antes de atribuir uma categoria na sua aplicação.

Nos medidores de geração, a unidade impressa é preservada: Demanda em kW, Energia reativa indutiva em kvarh e, quando assim impresso, Energia reativa excedente em kWh.

No histórico, consumption representa consumo em kWh e billed_days representa dias faturados. Consulte history[].source_name para identificar a série e values para os valores por mês.

Nos medidores, energia consumida usa consumed_energy; energia injetada usa injected_energy. Posto único/TP usa single, ponta/PT usa peak, fora de ponta/FP usa off_peak. ICMS, PIS e COFINS aparecem como icms, pis e cofins; suas alíquotas estão em pontos percentuais.

Valores observados nos documentos

Esta lista ajuda a reconhecer os valores já encontrados para COPEL. Ela complementa o vocabulário aceito acima e não limita novos documentos a essas combinações. Valores ausentes não aparecem na lista.

Campo	Tipo	Descrição
`consumer_unit.classification`	observado	commercial, industrial, residential, rural
`consumer_unit.tariff_group`	observado	A, B
`consumer_unit.tariff_subgroup`	observado	A3A, B1, B2, B3
`consumer_unit.tariff_category`	observado	a3a_commercial, a3a_industrial, b1_residential, b2_rural, b3_commercial, b3_industrial
`consumer_unit.supply_type`	observado	single_phase, three_phase, two_phase
`reading.method`	observado	not_reported
`tariff_flag.name`	observado	yellow
`meter_readings[].measurement`	observado	consumed_energy, demand, injected_energy, reactive_energy
`meter_readings[].time_slot`	observado	off_peak, peak, single
`line_items[].type`	observado	balance_adjustment, bonus, compensation, demand, donation, energy_consumption, injected_energy, interest, late_payment_penalty, monetary_adjustment, municipal_public_lighting, other, reactive_energy, refund, service_fee, tariff_flag
`history[].metric`	observado	billed_days, consumption
`document.layout`	observado	copel_danf3e_a4_v1, copel_generator_danf3e_a4_v1
`meter_readings[].unit`	observado	kW, kWh, kvarh
`line_items[].component`	observado	te, tusd
`line_items[].effect`	observado	charge, credit
`line_items[].unit`	observado	kW, kWh, unit
`taxes[].type`	observado	cofins, icms, pis

Qualidade e revisão

quality.status indica verified (dados conferidos com a fatura), parsed (dados estruturados sem comparação com a fatura), partial (dados com avisos de completude) ou invalid (erro de estrutura, total ou divergência). quality.score varia de 0 a 1; consulte os avisos mesmo quando a pontuação for 1.

normalization.issues[] pode indicar unmapped_payment_status, unmapped_tariff_group, unmapped_provider_field, invalid_provider_date, invalid_provider_number ou missing_required_field. Confira o caminho em field e a explicação em message.

Em pdf_data.quality.issues[], unmapped_canonical_value indica um campo sem valor canônico; line_item_total_mismatch indica divergência entre itens e total; códigos api_*_mismatch indicam divergências com a fatura. Um tipo de item other ou uma série nova de histórico também exige que sua aplicação consulte a descrição, mesmo sem aviso de qualidade.

pdf_data não contém nome, CPF/CNPJ, endereço completo, CEP, código de barras nem chave de acesso do documento. O item COPEL também não fornece códigos de pagamento.