JSON da fatura de energia

O JSON produzido para uma fatura de energia em formato PDF tem o mesmo formato, independentemente da concessionária.

A seguir são apresentados as propriedades que o objeto raiz possui.

version: string

Identifica a versão do formato do JSON; atualmente é a string "2.0".

md5: string

O MD5 do arquivo que foi analisado para que o JSON fosse gerado.

pipeline: string:

O tipo de documento analisado; para faturas de energia é a string "energy".

providerData: object

Exemplo:

{
  "providerData": {
    "name": {
      "value": "Equatorial Alagoas Distribuidora de Energia S.A.",
      "confidence": "high"
    },
    "cnpj": {
      "value": "12272084000100",
      "confidence": "high"
    }
  }
}

Dados mais detalhados sobre a concessionária de energia, retirados do documento original. Tem os atributos name e cnpj, cujos valores são objetos com propriedades value e confidence. A propriedade confidence pode ter os valores "high" ou "low": "high" indica que o nome ou o CNPJ da concessionária foi extraído diretamente do documento; "low" significa que o nome ou o CNPJ foi apenas deduzido, pois não está textualmente presente no documento.

stdProvider: string

Exemplos:

Uma codificação padronizada da concessionária.

locationNumber: string

Exemplos (fictícios):

O número da unidade consumidora. Na fatura, este número pode estar descrito como "número da unidade consumidora", "número da instalação", etc. Este número pode ter maior ou menor importância, conforme a concessionária.

É extremamente raro, mas este campo pode estar ausente se a unidade consumidora não estiver identificada de nenhuma forma na fatura.

clientCode: string

Exemplos (fictícios):

O código do cliente, conforme consta na fatura. A interpretação do que exatamente é o "código do cliente", para que serve, etc., depende da concessionária.

class: string

Exemplos:

A classe de consumo, conforme consta na fatura.

subclass: string

Exemplos:

A subclasse de consumo, conforme consta na fatura.

subgroup: string

Exemplos:

O subgrupo de tensão, conforme consta na fatura.

group: string

Exemplos:

O grupo de tensão, conforme consta na fatura.

customer: object

Exemplo (fictício):

{
    "customer": {
        "cnpj": "00.000.000/0001-91",
        "name": "ACME LTDA",
        "address": {
            "streetAndNumber": "AV ALMIRANTE TAMANDARÉ, 99",
            "city": "FLORIANÓPOLIS",
            "state": "SC",
            "zipCode": "88900320"
        }
    }
}

São os dados do consumidor, conforme consta na fatura. Para pessoas jurídicas a propriedade é cnpj, e para pessoas físicas é cpf — mas é possível que nenhum número de documento esteja presente no objeto customer, pois frequentemente não consta nenhum na fatura.

O endereço está dividido nos seguintes itens, todos opcionais:

totalCharges: number

Exemplos (fictícios):

O valor a pagar da fatura. Em geral, mas não sempre, corresponde ao somatório dos itens faturados.

tariffModality: string

Exemplos:

A modalidade da tarifa: "blue" (azul), "green" (verde), "standard" (convencional) ou "white" (branca). Frequentemente não está presente no JSON por não existir na fatura.

dates: object

Exemplo (fictício):

{
  "due": "2022-11-23T00:00:00",
  "month": "2022-10-01T00:00:00",
  "issue": "2022-10-03T00:00:00",
  "reading": {
    "periodFrom": "2022-09-01T00:00:00",
    "periodUntil": "2022-10-02T00:00:00",
    "dateRead": "2022-10-02T00:00:00",
    "next": "2022-11-01T00:00:00"
  }
}

São as datas da fatura: "due" (vencimento), "month" (mês de referência), "issue" (data de emissão). Dentro de "reading" estão as datas de leitura: "periodFrom" (leitura anterior), "periodUntil" e "dateRead" (ambos são a data de leitura atual) e "next" (previsão da próxima leitura). O objeto "reading" também pode conter o atributo "days", que corresponde ao número de dias considerados no período.

Nenhuma das datas garantidamente encontra-se em todas as faturas. É raro, mas até mesmo a data de vencimento e o mês de referência podem estar ausentes.

barcode: string

Exemplos (fictícios):

A linha digitável, conforme consta na fatura. Normalmente não corresponde exatamente ao código de barras, que é codificado de outra maneira.

invoiceNumber: string

Exemplos (fictícios):

O número da nota fiscal, conforme consta na fatura.

invoiceSeries: string

Exemplos:

A série da nota fiscal, conforme consta na fatura.

connectionType: string

Exemplos:

O tipo de ligação: "one-phase" (monofásica), "two-phase" (bifásica) ou "three-phase" (trifásica).

automaticDebitEnabled: boolean

Quando a propriedade está presente e tem o valor true, indica que a fatura está em débito automático. Esta propriedade nunca tem o valor false, já que é difícil ou impossível afirmar, a partir da fatura, que ela com certeza não está em débito automático.

losses: number

Exemplos:

O valor das perdas de transformação, expresso em percentual (ou seja, 0.025 corresponde a 2,5% de perdas).

measuredItems: array

Exemplo (fictício):

{
    "measuredItems": [
      {
        "type": "energy",
        "kind": "Gen.",
        "period": "off-peak",
        "texts": [
          "Energia kWh"
        ],
        "measured": 3023.0,
        "previousMeterReading": 90877.0,
        "currentMeterReading": 93900.0,
        "meterMultiplier": 1.0
      }
    ]
}

São os itens medidos presentes na fatura. Cada elemento do array é a medição de uma grandeza diferente.

Os seguintes atributos estão sempre presentes:

Outros atributos:

items: array

Exemplo (fictício):

{
    "items": [
      {
        "type": "energy",
        "kind": "Gen.",
        "period": "peak",
        "billed": 1338.0,
        "rate": 1.77483873,
        "charge": 2374.73,
        "tusdRate": 0,
        "teRate": 0,
        "texts": [
          "Energia Ativa kWh HP"
        ]
      }
    ]
}

Este array contém os itens faturados do documento. O atributo "type" identifica, de forma geral, o tipo da cobrança. Os atributos restantes variam conforme o "type".

"type": regra geral

Exemplo (fictício):

{
  "type": "energy",
  "kind": "Gen.",
  "period": "injected energy, same consumer, same period",
  "billed": 13.0,
  "rate": 0.62235,
  "charge": -8.09,
  "texts": [
    "Energia Atv Injetada mUC 4/2023 mPT"
  ],
  "basicRate": 0.59908
}

Quando o atributo "type" representa uma grandeza conhecida, então os demais atributos seguem um mesmo padrão. Os tipos em questão são:

Os demais atributos seguem este padrão:

"type": "other"

Exemplo (fictício):

{
  "type": "other",
  "name": "Atualização Monetária IPCA",
  "charge": 2.53
}

Quando o item não se encaixou em nenhuma categoria que o sistema reconhece, ele figura com "type": "other". O atributo "name" contém o texto conforme a fatura. Outros atributos que podem estar presentes:

Em alguns casos em que optou-se pela manutenção de compatibilidade, o campo "name" pode vir padronizado e, neste caso, o texto original está no atributo "texts".

"type": "flagSurcharge"

Exemplo (fictício):

{
  "type": "flagSurcharge",
  "color": "scarcity",
  "charge": 837.0,
  "summable": false,
  "texts": [
    "Bandeira Escassez Hídrica"
  ]
}

É uma cobrança de adicional de bandeira tarifária. A cor/tipo da bandeira está no atributo "color", que pode conter os seguintes valores:

O atributo "summable" indica se o adicional de bandeira deve ser incluído no somatório de cobranças para que seja atingido o valor total da fatura.

"type": "tax"

Exemplo (fictício):

{
  "type": "tax",
  "name": "COFINS",
  "taxable": 998.33,
  "rate": 0.0404,
  "charge": 40.33,
  "summable": true,
  "texts": [
    "COFINS"
  ]
}

Um item de impostos. O nome padronizado do imposto está em "name". Os outros atributos, opcionais, são:

"type": "publicLighting"

{
  "type": "publicLighting",
  "charge": 26.35,
  "texts": [
    "COBRANCA ILUM PUBLICA PARA"
  ]
}

Item de cobrança de contribuição de iluminação pública. O valor monetário está em "charge" e a descrição textual em "texts".

distributedGeneration: array

Exemplo (fictício):

[
  {
    "name": "global expiring balance",
    "value": 0.0
  },
  {
    "name": "global accumulated balance",
    "value": 2296.10
  },
  {
    "name": "global monthly balance",
    "value": 1299.0
  }
]

Este array contém pares de nome/valor com informações específicas de geração distribuída.

history: object

Exemplo (fictício):

{
  "2023-05-01": {
    "items": [
      {
        "name": "off-peak energy",
        "value": 279.0
      }
    ],
    "days": 32
  }
}

Este é o histórico que frequentemente aparece nas faturas.

stdProvider: lista completa