Fatura de Energia de Alta e Baixa Tensão
Modelo na Plataforma
Sigla: FATURA-AB
Descrição: Fatura de Energia de Alta e Baixa Tensão
Modelo Via API
Type: 35
Este modelo extrai informações-chave de um Fatura de Energia de Alta e Baixa Tensão (FATURA-AB).
O processo de extração é assíncrono e consiste em dois passos principais:
- Enviar o documento para a fila de processamento.
- Consultar o resultado após a conclusão do processamento.
Passo 1: Enviar o Documento para Processamento
Para iniciar a extração, envie uma requisição POST para o endpoint abaixo.
POST URL Ambiente/documents/upload
Headers
| Identificador | Valor |
|---|---|
Content-Type | multipart/form-data |
IDEXA-API-KEY | sua_api_key |
Payload (Corpo da Requisição)
A requisição deve conter os seguintes parâmetros obrigatórios:
| Parâmetro | Descriçao | Tipo |
|---|---|---|
files | O arquivo do documento a ser processado. | File |
type | Código interno do modelo. Use 35 para LV_HV_ELECTRICITY_BILL. | Integer |
Os parâmetros a seguir são opcionais:
| Parâmetro | Descriçao | Tipo |
|---|---|---|
pages | Define páginas específicas para análise (ex: "1,2,5-10"). | String |
externalId | Id externo para seu controle (não pode repetir). | String |
Exemplos de Requisição
- cURL
- JavaScript
- Python
- PHP
curl -X POST "URL_BASE/documents/upload" \
-H "IDEXA-API-KEY: sua_api_key" \
-H "Content-Type: multipart/form-data" \
-F "files=@/path/to/seu/documento.pdf" \
-F "type=35" \
-F "externalId=pedido-cliente-123"
const myHeaders = new Headers();
myHeaders.append("IDEXA-API-KEY", "sua_api_key");
const formdata = new FormData();
formdata.append("files", fileInput.files[0], "documento.pdf");
formdata.append("type", "35");
formdata.append("externalId", "pedido-cliente-123");
const requestOptions = { method: 'POST', headers: myHeaders, body: formdata };
fetch("URL_BASE/documents/upload", requestOptions)
.then(response => response.json())
.then(result => console.log(result));
import requests
url = "URL_BASE/documents/upload"
payload = {'type': '35', 'externalId': 'pedido-123'}
files=[('files',('documento.pdf',open('/path/to/documento.pdf','rb'),'application/pdf'))]
headers = {'IDEXA-API-KEY': 'sua_api_key'}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "URL_BASE/documents/upload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => [
'files' => new CURLFile('/path/to/documento.pdf'),
'type' => '35',
'externalId' => 'pedido-cliente-123'
],
CURLOPT_HTTPHEADER => [
"IDEXA-API-KEY: sua_api_key"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Resposta Imediata (Status 200)
A resposta confirma o recebimento. Guarde o id para consultar o resultado no próximo passo.
{
"id": "95893394-337c-429c-a63e-1b8210de47d2",
"externalId": "pedido-cliente-123",
"type": 35,
"status": 0,
"statusDesc": "RECEIVED",
"createdAt": "2026-01-07T14:38:50.045Z",
"updatedAt": "2026-01-07T14:38:50.045Z"
}
A extração de dados pode levar alguns segundos. Por isso, a API funciona de forma assíncrona. Após enviar o documento, aguarde um momento e então use o id retornado para consultar o resultado final. Para ser notificado automaticamente, considere utilizar nossos Webhooks.
Passo 2: Consultar o Resultado
Use o id do documento para fazer uma requisição GET e buscar o resultado completo da extração.
GET URL Ambiente/documents/[id]
Resposta Final (Status 200)
Quando o status for 1 (FINISHED), o objeto data conterá os campos extraídos.
{
"id": "95893394-337c-429c-a63e-1b8210de47d2",
"externalId": "pedido-cliente-123",
"type": 35,
"data": {
"titular": {
"id": "*****3000000007000143***",
"uf": "RS",
"cep": "12345-678",
"nome": "EMPRESA",
"bairro": "BAIRRO",
"cidade": "PORTO ALEGRE",
"numero": "12",
"endereco": "RUA X",
"complemento": "AP 00003",
"conta_contrato": "0000000000",
"parceiro_negocio": "0000000000",
"unidade_consumidora": "00000000"
},
"bandeira": {
"cor": "VERDE",
"adicional": "0,00"
},
"tributos": {
"pis": {
"base": "100,00",
"valor": "17,00",
"aliquota": "17,00"
},
"icms": {
"base": "100,00",
"valor": "17,00",
"aliquota": "17,00"
},
"cofins": {
"base": "100,00",
"valor": "17,00",
"aliquota": "17,00"
}
},
"historico": [
{
"dias": "32",
"mes_ref": "MAI/2024",
"consumo_p_t": "32",
"demanda_p_t": "32",
"consumo_f_p_t": "32",
"consumo_unico": "32",
"demanda_f_p_t": "32"
}
],
"nota_fiscal": [
{
"serie": "0",
"numero": "00000000",
"chave_acesso": "38545619",
"data_emissao": "11/06/2024",
"protocolo_autorizacao": "00000000"
}
],
"dados_fatura": {
"conta_ref": "MAI/2024",
"vencimento": "11/06/2024",
"aviso_corte": false,
"cip_municipal": "10,50",
"total_a_pagar": "103,50",
"concessionaria": "EMPRESA LTDA",
"leitura_debito": false
},
"itens_fatura": [
{
"icms": "22,06",
"item": "CONSUMO",
"valor": "112,60",
"tarifa": "TUSD",
"horario": "PONTA",
"unidade": "KWH",
"pis_cofins": "4,20",
"quantidade": "116",
"tarifa_unitaria": "0,364490",
"preco_unitario_tributos": "0,460142"
}
],
"juros_multas": [
{
"valor": "5,00",
"descricao": "MULTA"
}
],
"dados_energia": {
"classificacao": "RESIDENCIAL",
"tensao_nominal": "127-125",
"grupo_tarifario": "B1",
"tipo_fornecimento": "TRIFÁSICO",
"modalidade_tarifaria": "CONVENCIONAL"
},
"datas_leituras": {
"qtd_dias": "30",
"leitura_atual": "11/06/2024",
"proxima_leitura": "11/07/2024",
"leitura_anterior": "11/05/2024"
},
"informacoes_cliente": [
{
"descricao": "SALDO DE ENERGIA",
"quantidade": "100",
"posto_horario": "FORA PONTA"
}
],
"detalhamento_leitura": [
{
"medidor": "50342063",
"unidade": "KWH",
"grandeza": "CONSUMO",
"consumok_wh": "282",
"const_medidor": "1",
"leitura_atual": "4018",
"postos_horarios": "TP",
"leitura_anterior": "3736"
}
]
},
"processTime": 8.123,
"status": 1,
"statusDesc": "FINISHED",
"createdAt": "2026-01-07T14:38:50.045Z",
"updatedAt": "2026-01-07T14:38:58.168Z"
}
Dicionário de Dados: Fatura de Energia de Alta e Baixa Tensão
Estes são os campos retornados dentro do objeto data.
- Modelo
| Campo | Tipo | Descrição | Exemplo |
|---|---|---|---|
| titular.id | String | id | "**3000000007000143" |
| titular.uf | String | uf | "RS" |
| titular.cep | String | cep | "12345-678" |
| titular.nome | String | nome | "EMPRESA" |
| titular.bairro | String | bairro | "BAIRRO" |
| titular.cidade | String | cidade | "PORTO ALEGRE" |
| titular.numero | String | numero | "12" |
| titular.endereco | String | endereco | "RUA X" |
| titular.complemento | String | complemento | "AP 00003" |
| titular.contaContrato | String | conta_contrato | "0000000000" |
| titular.parceiroNegocio | String | parceiro_negocio | "0000000000" |
| titular.unidadeConsumidora | String | unidade_consumidora | "00000000" |
| bandeira.cor | String | cor | "VERDE" |
| bandeira.adicional | String | adicional | "0,00" |
| tributos.pis.base | String | base | "100,00" |
| tributos.pis.valor | String | valor | "17,00" |
| tributos.pis.aliquota | String | aliquota | "17,00" |
| tributos.icms.base | String | base | "100,00" |
| tributos.icms.valor | String | valor | "17,00" |
| tributos.icms.aliquota | String | aliquota | "17,00" |
| tributos.cofins.base | String | base | "100,00" |
| tributos.cofins.valor | String | valor | "17,00" |
| tributos.cofins.aliquota | String | aliquota | "17,00" |
| historico[].mesRef | String | mes_ref | "MAI/2024" |
| historico[].consumoUnico | String | consumo_unico | "32" |
| historico[].consumoPT | String | consumo_p_t | "32" |
| historico[].consumoFPT | String | consumo_f_p_t | "32" |
| historico[].dias | String | dias | "32" |
| historico[].demandaPT | String | demanda_p_t | "32" |
| historico[].demandaFPT | String | demanda_f_p_t | "32" |
| notaFiscal[].numero | String | numero | "00000000" |
| notaFiscal[].serie | String | serie | "0" |
| notaFiscal[].dataEmissao | String | data_emissao | "11/06/2024" |
| notaFiscal[].chaveAcesso | String | chave_acesso | "38545619" |
| notaFiscal[].protocoloAutorizacao | String | protocolo_autorizacao | "00000000" |
| dadosFatura.contaRef | String | conta_ref | "MAI/2024" |
| dadosFatura.vencimento | String | vencimento | "11/06/2024" |
| dadosFatura.avisoCorte | Boolean | aviso_corte | false |
| dadosFatura.cipMunicipal | String | cip_municipal | "10,50" |
| dadosFatura.totalAPagar | String | total_a_pagar | "103,50" |
| dadosFatura.concessionaria | String | concessionaria | "EMPRESA LTDA" |
| dadosFatura.leituraDebito | Boolean | leitura_debito | false |
| itensFatura[].item | String | item | "CONSUMO" |
| itensFatura[].horario | String | horario | "PONTA" |
| itensFatura[].tarifa | String | tarifa | "TUSD" |
| itensFatura[].unidade | String | unidade | "KWH" |
| itensFatura[].quantidade | String | quantidade | "116" |
| itensFatura[].valor | String | valor | "112,60" |
| itensFatura[].precoUnitarioTributos | String | preco_unitario_tributos | "0,460142" |
| itensFatura[].tarifaUnitaria | String | tarifa_unitaria | "0,364490" |
| itensFatura[].pisCofins | String | pis_cofins | "4,20" |
| itensFatura[].icms | String | icms | "22,06" |
| jurosMultas[].descricao | String | descricao | "MULTA" |
| jurosMultas[].valor | String | valor | "5,00" |
| dadosEnergia.classificacao | String | classificacao | "RESIDENCIAL" |
| dadosEnergia.tensaoNominal | String | tensao_nominal | "127-125" |
| dadosEnergia.grupoTarifario | String | grupo_tarifario | "B1" |
| dadosEnergia.tipoFornecimento | String | tipo_fornecimento | "TRIFÁSICO" |
| dadosEnergia.modalidadeTarifaria | String | modalidade_tarifaria | "CONVENCIONAL" |
| datasLeituras.qtdDias | String | qtd_dias | "30" |
| datasLeituras.leituraAtual | String | leitura_atual | "11/06/2024" |
| datasLeituras.proximaLeitura | String | proxima_leitura | "11/07/2024" |
| datasLeituras.leituraAnterior | String | leitura_anterior | "11/05/2024" |
| informacoesCliente[].descricao | String | descricao | "SALDO DE ENERGIA" |
| informacoesCliente[].quantidade | String | quantidade | "100" |
| informacoesCliente[].postoHorario | String | posto_horario | "FORA PONTA" |
| detalhamentoLeitura[].grandeza | String | grandeza | "CONSUMO" |
| detalhamentoLeitura[].constMedidor | String | const_medidor | "1" |
| detalhamentoLeitura[].unidade | String | unidade | "KWH" |
| detalhamentoLeitura[].postosHorarios | String | postos_horarios | "TP" |
| detalhamentoLeitura[].leituraAnterior | String | leitura_anterior | "3736" |
| detalhamentoLeitura[].leituraAtual | String | leitura_atual | "4018" |
| detalhamentoLeitura[].consumokWh | String | consumok_wh | "282" |
| detalhamentoLeitura[].medidor | String | medidor | "50342063" |