NF3-e · TF Fiscal API

Nota

NF3e — Nota Fiscal de Energia Elétrica Eletrônica

A API de NF3e (modelo 66, leiaute 1.00) permite emitir, consultar, cancelar e obter o PDF (DANF3E) de Notas Fiscais de Energia Elétrica Eletrônicas — a "conta de luz" eletrônica que substitui a Nota Fiscal/Conta de Energia Elétrica (modelo 6). A autorização é feita no ambiente nacional único (SVRS). Os dados do emitente são preenchidos automaticamente a partir do cadastro da empresa (CNPJ, IE, razão social e endereço); os campos técnicos da chave de acesso (cNF, cDV, cUF, dhEmi, mod, serie) são preenchidos pelo servidor. O QR-Code de consulta (qrCodNF3e) também é gerado automaticamente.

Endpoint	Método	Descrição
`/api/nf3e/create`	POST	Emitir NF3e
`/api/nf3e/consult`	POST	Consultar situação da NF3e
`/api/nf3e/cancel`	POST	Cancelar NF3e autorizada
`/api/nf3e/pdf`	POST	Obter o DANF3E (PDF) da NF3e
`/api/nf3e/get_list`	GET	Listar NF3e (paginado)

Credenciamento obrigatório: a emissão de NF3e exige que o CNPJ emissor esteja credenciado para o modelo 66 junto ao Fisco da sua UF (habilitação restrita a distribuidoras e comercializadoras de energia elétrica). Sem o credenciamento, o Fisco rejeita a emissão com cStat=203 ("Emissor não habilitado para emissão da NF3e"). Além disso, a partir de 03/08/2026 os grupos de IBS/CBS (Reforma Tributária) passam a ser exigidos no ambiente de produção.

A NF3e exige o grupo gANEEL (histórico de faturamento — 13 competências por grandeza). Quando não enviado, o servidor gera automaticamente as 13 competências a partir do valor faturado.

POST/api/nf3e/create

Emitir NF3e

Emite uma NF3e a partir do corpo enviado. O cliente envia apenas os dados de negócio — o bloco do emitente (emit) é montado automaticamente a partir do cadastro da empresa do token, e os campos técnicos da chave de acesso são calculados pelo servidor. O débito de crédito ocorre somente em produção (tpAmb=1) e quando a NF3e é autorizada. Após a autorização, o XML (nf3eProc) e o DANF3E (PDF) são gerados e disponibilizados por URL.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Body — raiz

Campo	Tipo	Descrição
ide	object	Identificação da NF3e (ambiente, competência do fato gerador)
dest *	object	Dados do destinatário/consumidor
acessante *	object	Dados da unidade consumidora (obrigatório no leiaute da NF3e)
det *	array	Itens faturados — mínimo 1
total	object	Totalizador. Opcional — calculado a partir dos itens quando omitido
gFat	object	Dados da fatura (competência, vencimento, próxima leitura, código de barras)
gANEEL	array	Histórico de faturamento (13 competências por grandeza). Opcional — gerado automaticamente quando omitido
infAdFisco	string	Informações de interesse do Fisco
infCpl	array	Informações complementares (lista de textos)
autXML	array	CNPJs/CPFs autorizados a acessar o XML (lista de strings)

Campos obrigatórios na requisição: dest com xNome, um de CNPJ/CPF/idOutros e enderDest (xLgr, nro, xBairro, cMun, xMun, CEP com 8 dígitos, UF); acessante.idAcesso; e pelo menos 1 item em det com xProd, cClass (7 dígitos da tabela de classificação de itens da NF3e), vItem e vProd. Todos os demais campos são opcionais.

ide — Identificação

Campo	Tipo	Descrição
tpAmb	int	Ambiente: `1`=produção, `2`=homologação. Default: `2`
nNF	long	Número sequencial da NF3e. Opcional — auto-incrementado pelo servidor quando omitido ou `0`
dhEmi	string	Data/hora de emissão. Opcional — gerada pelo servidor quando omitida
cMunFG	long	Código IBGE do município do fato gerador (7 dígitos). Opcional — default: município do cadastro da empresa
finNF3e	int	Finalidade: `1`=Normal, `2`=Substituição, `3`=Normal com ajuste. Default: `1`
nSiteAutoriz	int	Site autorizador (1 dígito da chave). Default: `0`

Preenchidos automaticamente pelo servidor — não é necessário enviá-los: mod (fixo em 66), serie (série de NF3e cadastrada na empresa; configure em /api/company/edit via serie_nf3e), cUF (derivado do cadastro da empresa), cNF (código numérico de 7 dígitos), cDV (dígito verificador da chave), tpEmis (normal) e verProc. O bloco emit completo e o infNF3eSupl (QR-Code) também são montados pelo servidor.

dest — Destinatário / Consumidor

Campo	Tipo	Descrição
xNome *	string	Nome ou razão social do consumidor
CNPJ ⚠	string	CNPJ do consumidor (14 dígitos)
CPF ⚠	string	CPF do consumidor (11 dígitos)
idOutros ⚠	string	Outro documento de identificação
indIEDest	int	Indicador de IE: `1`=contribuinte, `2`=isento, `9`=não contribuinte. Default: `9`
IE	string	Inscrição Estadual do consumidor (quando contribuinte)
enderDest *	object	Endereço do consumidor (ver estrutura abaixo)

enderDest — Endereço

Campo	Tipo	Descrição
xLgr *	string	Logradouro
nro *	string	Número
xCpl	string	Complemento
xBairro *	string	Bairro
cMun *	long	Código IBGE do município (7 dígitos)
xMun *	string	Nome do município
CEP *	string	CEP (8 dígitos)
UF *	string	Sigla da UF (2 letras)
fone	string	Telefone
email	string	E-mail

acessante — Unidade consumidora

Campo	Tipo	Descrição
idAcesso *	string	Código de identificação da unidade consumidora / ponto de acesso (até 15 caracteres)
tpAcesso	int	Tipo de acesso: `0`=Gerador, `1`=Cativo, `2`=Livre, `3`=Parc. Livre, `4`=Cons. Especial, `5`=Parc. Especial, `6`=Comunhão, `7`=Suprimento, `8`=Distribuidora. Default: `1`
xNomeUC	string	Nome da unidade consumidora
tpClasse	string	Classe de consumo: `01`=Comercial, `02`=Consumo Próprio, `03`=Iluminação Pública, `04`=Industrial, `05`=Poder Público, `06`=Residencial, `07`=Rural, `08`=Serviço Público. Default: `06`
tpSubClasse	string	Subclasse de consumo (`01`–`29`, `99`)
tpFase	int	Tipo de ligação: `1`=Monofásico, `2`=Bifásico, `3`=Trifásico. Default: `3`
tpGrpTensao	string	Grupo de tensão (`01`–`14`: A1..B4b). Default: `12`
tpModTar	string	Modalidade tarifária (`01`–`10`: Convencional/Horária Azul/Verde/Branca...). Default: `01`
latGPS	string	Latitude do ponto de captura. Exatamente 6 casas decimais (ex.: `"-23.550500"`). Default: coordenada padrão
longGPS	string	Longitude do ponto de captura. Exatamente 6 casas decimais (ex.: `"-46.633300"`). Default: coordenada padrão

det[] — Itens faturados

Campo	Tipo	Descrição
cProd	string	Código do item. Opcional — default: número sequencial
xProd *	string	Descrição do item faturado (ex.: "Consumo de energia elétrica")
cClass *	string	Código de classificação do item (7 dígitos — tabela de classificação de itens da NF3e)
CFOP	string	CFOP da operação (obrigatório quando o item tem ICMS)
uMed	string	Unidade de medida: `1`=kW, `2`=kWh, `3`=kVAr, `4`=kVArh, `5`=UN. Default: `2`
qFaturada	string	Quantidade faturada. Default: `"1"`
vItem *	string	Valor unitário (tarifa) do item
vProd *	string	Valor total do item
indOrigemQtd	string	Origem da quantidade: `1`=Média, `2`=Medido, `3`=Contratada, `4`=Calculada, `5`=Custo disp., `6`=Sem qtd. Default: `2`
infAdProd	string	Informações adicionais do item
icms	object	Tributação de ICMS do item (ver abaixo)
pis	object	PIS do item (ver abaixo)
cofins	object	COFINS do item (mesma estrutura do PIS)
ibscbs	object	IBS/CBS — Reforma Tributária (ver abaixo)

det[].icms — ICMS do item

Campo	Tipo	Descrição
cst	string	CST do ICMS. Default: `"00"` (tributação integral)
vBC	string	Base de cálculo do ICMS
pICMS	string	Alíquota do ICMS (%)
vICMS	string	Valor do ICMS
isento	bool	`true` = item isento/não tributado (grupo `ICMS40`)
semCST	bool	`true` = item sem relação com o ICMS (`indSemCST`; não informe CFOP nesse caso)

det[].pis / det[].cofins

Campo	Tipo	Descrição
cst	string	CST do PIS/COFINS. Default: `"01"`
vBC	string	Base de cálculo
pAliq	string	Alíquota (%)
valor	string	Valor do tributo

det[].ibscbs — IBS/CBS (Reforma Tributária)

Campo	Tipo	Descrição
cst	string	CST do IBS/CBS (3 dígitos)
cClassTrib	string	Código de classificação tributária
vBC	string	Base de cálculo
pIBSUF / vIBSUF	string	Alíquota e valor do IBS estadual
pIBSMun / vIBSMun	string	Alíquota e valor do IBS municipal
vIBS	string	Valor total do IBS
pCBS / vCBS	string	Alíquota e valor da CBS

gFat — Dados da fatura

Campo	Tipo	Descrição
CompetFat	string	Competência da fatura no formato `AAAAMM`
dVencFat	string	Data de vencimento no formato `AAAA-MM-DD`
dProxLeitura	string	Data prevista da próxima leitura (`AAAA-MM-DD`). Opcional — default: +30 dias
codBarras	string	Linha digitável do código de barras (somente dígitos, 1–48)
codDebAuto	string	Código de autorização de débito em conta (alternativa a `codBanco`+`codAgencia`)
codBanco / codAgencia	string	Banco e agência para débito em conta. Um dos dois grupos (`codDebAuto` OU `codBanco`+`codAgencia`) é exigido pelo schema — default: banco `001`, agência `0001`

* Campo obrigatório. ⚠ No destinatário, pelo menos um de CNPJ, CPF ou idOutros é obrigatório. Valores monetários e alíquotas são enviados como string com ponto decimal (ex.: "75.00").

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/nf3e/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "ide": {
            "tpAmb": 2
          },
          "dest": {
            "xNome": "CONSUMIDOR EXEMPLO",
            "CPF": "12345678909",
            "indIEDest": 9,
            "enderDest": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": 3550308,
              "xMun": "SAO PAULO",
              "CEP": "01001000",
              "UF": "SP"
            }
          },
          "acessante": {
            "idAcesso": "000000000012345",
            "tpAcesso": 1,
            "xNomeUC": "UNIDADE CONSUMIDORA",
            "tpClasse": "06",
            "tpFase": 3,
            "tpGrpTensao": "12",
            "tpModTar": "01",
            "latGPS": "-23.550500",
            "longGPS": "-46.633300"
          },
          "det": [
            {
              "cProd": "1",
              "xProd": "CONSUMO DE ENERGIA ELETRICA",
              "cClass": "0100101",
              "CFOP": "5258",
              "uMed": "2",
              "qFaturada": "100.00",
              "vItem": "0.750000",
              "vProd": "75.00",
              "indOrigemQtd": "2",
              "icms": {
                "cst": "00",
                "vBC": "75.00",
                "pICMS": "25.00",
                "vICMS": "18.75"
              }
            }
          ],
          "total": {
            "vProd": "75.00",
            "vBC": "75.00",
            "vICMS": "18.75",
            "vNF": "75.00"
          },
          "gFat": {
            "CompetFat": "202607",
            "dVencFat": "2026-08-15",
            "dProxLeitura": "2026-08-22",
            "codBarras": "12345678901234567890"
          }
        }

        {
          "success": true,
          "message": "NF3e autorizada",
          "data": {
            "chave": "35260712345678000199660010000000011012345675",
            "serie": 1,
            "number": 1,
            "cStat": "100",
            "xMotivo": "Autorizado o uso da NF3e",
            "nProt": "353260000123456",
            "xml": "https://storage.../nf3e/35260712345678000199660010000000011012345675.xml",
            "danf3e": "https://storage.../nf3e/35260712345678000199660010000000011012345675.pdf"
          }
        }

        {
          "success": false,
          "message": "NF3e rejeitada: Rejeição: Emissor não habilitado para emissão da NF3e",
          "data": {
            "chave": "35260712345678000199660010000000011012345675",
            "serie": 1,
            "number": 1,
            "cStat": "203",
            "xMotivo": "Rejeição: Emissor não habilitado para emissão da NF3e",
            "nProt": "",
            "xml": "",
            "danf3e": ""
          }
        }

POST/api/nf3e/consult

Consultar situação da NF3e

Consulta a situação atual da NF3e no ambiente nacional (SVRS) a partir da chave de acesso.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
chNF3e *	string	Chave de acesso da NF3e (44 dígitos)

* Campo obrigatório.

POST/api/nf3e/cancel

Cancelar NF3e

Cancela uma NF3e autorizada (evento 110111). Requer que a NF3e tenha sido autorizada (possua protocolo) e ainda não esteja cancelada.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
chNF3e *	string	Chave de acesso da NF3e (44 dígitos)
xJust *	string	Justificativa do cancelamento (mínimo 15 caracteres por exigência Fisco)
nProt *	string	Protocolo de autorização da NF3e (16 dígitos)

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/nf3e/cancel" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "chNF3e": "35260712345678000199660010000000011012345675",
          "xJust": "Cancelamento por erro no faturamento da unidade consumidora",
          "nProt": "353260000123456"
        }

        {
          "success": true,
          "message": "NF3e cancelada",
          "data": {
            "cStat": "135",
            "xMotivo": "Evento registrado e vinculado a NF3e",
            "nProt": "353260000123457"
          }
        }

POST/api/nf3e/pdf

Obter PDF da NF3e

Retorna a URL do DANF3E — a representação em PDF da NF3e (conta de energia). O PDF é gerado automaticamente na autorização; quando ainda não existe no armazenamento, é gerado sob demanda a partir do XML.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
chNF3e *	string	Chave de acesso da NF3e (44 dígitos)

* Campo obrigatório.

GET/api/nf3e/get_list

Listar NF3e (com paginação)

Lista as NF3e da empresa com paginação. Parâmetros passados via query string (não no body).

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5 (path inclui a query string)
timestamp	string	Unix timestamp em segundos

Query string

Parâmetro	Tipo	Descrição
page *	int	Número da página (≥ 1)
page_size *	int	Tamanho da página (1–50)

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X GET "https://api.tffiscal.com/api/nf3e/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN"

GET /api/nf3e/get_list?page=1&page_size=20

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260712345678000199660010000000011012345675",
                "serie": 1,
                "number": 1,
                "status": "Success",
                "create": "2026-07-10T10:30:00Z",
                "issue_time": "2026-07-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 42,
            "total_pages": 3
          }
        }