Schema CELESC

Contrato da fatura

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

A fatura CELESC também inclui códigos de pagamento, leituras, bandeira tarifária, médias, energia por posto horário, demanda e informações complementares. Esses campos fazem parte do contrato mesmo quando o valor de uma fatura específica é null.

payment.pixQrCode contém o payload PIX copia e cola quando disponível; payment.barcode contém o código de pagamento. Uma fatura paga pode retornar esses campos como null.

energy.timeSlots separa ponta (peak), fora de ponta (offPeak), intermediário e reservado. Consumo registrado e consumo faturado podem diferir. Os campos de demanda usam kW; os de energia usam kWh.

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": "CELESC",
  "consumerUnit": {
    "installationId": "123456701100",
    "legacyInstallationId": "12345678",
    "contractAccount": "12345678",
    "city": null,
    "state": null
  },
  "invoice": {
    "id": "000000000001",
    "billingPeriod": "2026-08",
    "dueDate": "2026-09-15",
    "amount": 120.5,
    "averageAmount": 100,
    "currency": "BRL"
  },
  "payment": {
    "status": "open",
    "paidAt": null,
    "sourceStatus": null,
    "sourceCompensation": "Em aberto",
    "barcode": null,
    "pixQrCode": null,
    "compensationBlocked": false,
    "hasActiveInstallment": false
  },
  "reading": {
    "days": 30,
    "method": "actual",
    "sourceMethod": "Leitura através empresa - SAP",
    "providerMethodId": null,
    "currentMeterReading": 1200
  },
  "tariff": {
    "group": null,
    "sourceGroup": null,
    "flag": "yellow",
    "sourceFlag": "Amarela",
    "providerFlagId": "AM"
  },
  "energy": {
    "unit": "kWh",
    "consumed": 150,
    "previousConsumed": 140,
    "injected": 20,
    "averageConsumed": 145,
    "averageInjected": 15,
    "timeSlots": {
      "peak": {
        "billedConsumed": null,
        "registeredConsumed": null,
        "injected": null,
        "averageBilledConsumed": null,
        "averageRegisteredConsumed": null,
        "averageInjected": null
      },
      "offPeak": {
        "billedConsumed": null,
        "registeredConsumed": null,
        "injected": null,
        "averageBilledConsumed": null,
        "averageRegisteredConsumed": null,
        "averageInjected": null
      },
      "intermediate": {
        "billedConsumed": null,
        "registeredConsumed": null,
        "injected": null,
        "averageBilledConsumed": null,
        "averageRegisteredConsumed": null,
        "averageInjected": null
      },
      "reserved": {
        "consumed": null,
        "injected": null,
        "averageConsumed": null,
        "averageInjected": null
      }
    },
    "demand": {
      "unit": "kW",
      "contracted": null,
      "peak": null,
      "offPeak": null
    }
  },
  "providerMetadata": {
    "availability": {
      "status": null,
      "providerId": null
    },
    "service": {
      "code": null,
      "id": null,
      "protocol": null
    },
    "launchBlocked": false
  },
  "normalization": {
    "status": "normalized",
    "issues": []
  },
  "pdf_data": {},
  "pdf": null,
  "lastUpdated": "2026-09-04T12:00:00-03:00"
}

Todos os campos da fatura

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.sourceCompensation apresentou Em aberto, Vencida e Paga. payment.sourceStatus pode ser null.

reading.method aceita actual, estimated, customer_reported, not_reported ou null. “Leitura através empresa - SAP” corresponde a actual; “Estimativa automática - SAP”, a estimated. Consulte o rótulo completo em reading.sourceMethod.

A tabela mostra as combinações observadas. tariff.flag também admite red, water_scarcity, mixed, not_reported e null. tariff.group aceita A, B ou null; o grupo e o subgrupo impressos estão em pdf_data.consumer_unit.

providerMetadata.availability.status pode informar “Faturado pelo mínimo da fase”. É um rótulo textual, não um enum fechado. Códigos e rótulos source* também não são enums fechados.

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 CELESC. 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": "123456701100",
    "city": "Florianópolis",
    "state": "SC",
    "classification": "residential",
    "tariff_group": "B",
    "tariff_subgroup": "B1",
    "tariff_category": "b1_residential",
    "supply_type": "single_phase",
    "source_labels": {
      "pdf_installation": "123456701100",
      "classification": "residencial",
      "tariff_category": "B1 Residencial",
      "supply_type": "monofasico",
      "group": "B/B1"
    }
  },
  "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": "actual",
    "source_method": "Leitura pela empresa"
  },
  "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": "0P",
      "type": "energy_consumption",
      "component": "te",
      "tariff_flag": null,
      "effect": "charge",
      "source_description": "(0P) Consumo TE",
      "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": "CELESC",
    "invoice_id": "000000000001",
    "layout": "celesc_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.

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.

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.

Códigos de itens CELESC

Este catálogo descreve os códigos das faturas celesc_danf3e_a4_v1. Em celesc_generator_danf3e_v1, códigos iguais podem designar outros lançamentos: use type, component e source_description retornados no item.

Os códigos 12 e 13 podem incluir energia da própria UC ou de outra UC, meses distintos e variantes de geração. Essas diferenças permanecem em source_description. Para benefícios tarifários, créditos e devoluções, consulte effect e o sinal de amount.

Os códigos OB, TV e FQ identificam donation (doação), third_party_service (serviço de terceiros) e installment (parcela). CJ, E4 e 8F são compensation; C8 é refund; 96 e 97 são monetary_adjustment. A descrição e o sinal do valor distinguem créditos, estornos e cobranças.

A série “Conversão entre postos horários” usa time_slot_conversion, com valores em kWh por mês.

No histórico, consumption representa consumo; injected_energy, energia injetada; injected_energy_used, injeção utilizada; distributed_energy_surplus e received_energy_surplus, excedentes distribuídos e recebidos. previous_credit_balance, used_credits e updated_credit_balance representam saldo anterior, créditos utilizados e saldo atualizado, em kWh.

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 CELESC. Ela complementa o vocabulário aceito acima e não limita novos documentos a essas combinações. Valores ausentes não aparecem na lista.

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, além de unmapped_reading_method e unmapped_tariff_flag. 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. Os códigos de pagamento disponíveis ficam em payment.barcode e payment.pixQrCode.