NF3-e · TF Fiscal API

Nota

NF3e — Nota Fiscal de Energía Eléctrica Electrónica

La API de NF3e (modelo 66, layout 1.00) permite emitir, consultar, cancelar y obtener el PDF (DANF3E) de Notas Fiscales de Energía Eléctrica Electrónicas — la "cuenta de luz" electrónica que sustituye a la Nota Fiscal/Cuenta de Energía Eléctrica (modelo 6). La autorización se realiza en el ambiente nacional único (SVRS). Los datos del emisor se rellenan automáticamente a partir del registro de la empresa (CNPJ, IE, razón social y dirección); los campos técnicos de la clave de acceso (cNF, cDV, cUF, dhEmi, mod, serie) son rellenados por el servidor. El QR-Code de consulta (qrCodNF3e) también se genera automáticamente.

Endpoint	Método	Descripción
`/api/nf3e/create`	POST	Emitir NF3e
`/api/nf3e/consult`	POST	Consultar situación de la NF3e
`/api/nf3e/cancel`	POST	Cancelar NF3e autorizada
`/api/nf3e/pdf`	POST	Obtener el DANF3E (PDF) de la NF3e
`/api/nf3e/get_list`	GET	Listar NF3e (paginado)

Acreditación obligatoria: la emisión de NF3e exige que el CNPJ emisor esté acreditado para el modelo 66 ante la autoridad fiscal de su UF (habilitación restringida a distribuidoras y comercializadoras de energía eléctrica). Sin la acreditación, la autoridad fiscal rechaza la emisión con cStat=203 ("Emissor não habilitado para emissão da NF3e"). Además, a partir del 03/08/2026 los grupos de IBS/CBS (Reforma Tributaria) pasan a ser exigidos en el ambiente de producción.

La NF3e exige el grupo gANEEL (histórico de facturación — 13 competencias por magnitud). Cuando no se envía, el servidor genera automáticamente las 13 competencias a partir del valor facturado.

POST/api/nf3e/create

Emitir NF3e

Emite una NF3e a partir del cuerpo enviado. El cliente envía únicamente los datos de negocio — el bloque del emisor (emit) se monta automáticamente a partir del registro de la empresa del token, y los campos técnicos de la clave de acceso son calculados por el servidor. El débito de crédito ocurre solo en producción (tpAmb=1) y cuando la NF3e es autorizada. Tras la autorización, el XML (nf3eProc) y el DANF3E (PDF) se generan y quedan disponibles por URL.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Body — raíz

Campo	Tipo	Descripción
ide	object	Identificación de la NF3e (ambiente, competencia del hecho generador)
dest *	object	Datos del destinatario/consumidor
acessante *	object	Datos de la unidad consumidora (obligatorio en el layout de la NF3e)
det *	array	Ítems facturados — mínimo 1
total	object	Totalizador. Opcional — calculado a partir de los ítems cuando se omite
gFat	object	Datos de la factura (competencia, vencimiento, próxima lectura, código de barras)
gANEEL	array	Histórico de facturación (13 competencias por magnitud). Opcional — generado automáticamente cuando se omite
infAdFisco	string	Información de interés del Fisco
infCpl	array	Información complementaria (lista de textos)
autXML	array	CNPJ/CPF autorizados a acceder al XML (lista de strings)

Campos obligatorios en la solicitud: dest con xNome, uno de CNPJ/CPF/idOutros y enderDest (xLgr, nro, xBairro, cMun, xMun, CEP con 8 dígitos, UF); acessante.idAcesso; y al menos 1 ítem en det con xProd, cClass (7 dígitos de la tabla de clasificación de ítems de la NF3e), vItem y vProd. Todos los demás campos son opcionales.

ide — Identificación

Campo	Tipo	Descripción
tpAmb	int	Ambiente: `1`=producción, `2`=homologación. Default: `2`
nNF	long	Número secuencial de la NF3e. Opcional — auto-incrementado por el servidor cuando se omite o es `0`
dhEmi	string	Fecha/hora de emisión. Opcional — generada por el servidor cuando se omite
cMunFG	long	Código IBGE del municipio del hecho generador (7 dígitos). Opcional — default: municipio del registro de la empresa
finNF3e	int	Finalidad: `1`=Normal, `2`=Sustitución, `3`=Normal con ajuste. Default: `1`
nSiteAutoriz	int	Sitio autorizador (1 dígito de la clave). Default: `0`

Rellenados automáticamente por el servidor — no es necesario enviarlos: mod (fijo en 66), serie (serie de NF3e registrada en la empresa; configúrela en /api/company/edit vía serie_nf3e), cUF (derivado del registro de la empresa), cNF (código numérico de 7 dígitos), cDV (dígito verificador de la clave), tpEmis (normal) y verProc. El bloque emit completo y el infNF3eSupl (QR-Code) también son montados por el servidor.

dest — Destinatario / Consumidor

Campo	Tipo	Descripción
xNome *	string	Nombre o razón social del consumidor
CNPJ ⚠	string	CNPJ del consumidor (14 dígitos)
CPF ⚠	string	CPF del consumidor (11 dígitos)
idOutros ⚠	string	Otro documento de identificación
indIEDest	int	Indicador de IE: `1`=contribuyente, `2`=exento, `9`=no contribuyente. Default: `9`
IE	string	Inscripción Estatal del consumidor (cuando es contribuyente)
enderDest *	object	Dirección del consumidor (ver estructura abajo)

enderDest — Dirección

Campo	Tipo	Descripción
xLgr *	string	Calle
nro *	string	Número
xCpl	string	Complemento
xBairro *	string	Barrio
cMun *	long	Código IBGE del municipio (7 dígitos)
xMun *	string	Nombre del municipio
CEP *	string	Código postal (8 dígitos)
UF *	string	Sigla de la UF (2 letras)
fone	string	Teléfono
email	string	Correo electrónico

acessante — Unidad consumidora

Campo	Tipo	Descripción
idAcesso *	string	Código de identificación de la unidad consumidora / punto de acceso (hasta 15 caracteres)
tpAcesso	int	Tipo de acceso: `0`=Generador, `1`=Cautivo, `2`=Libre, `3`=Parc. Libre, `4`=Cons. Especial, `5`=Parc. Especial, `6`=Comunión, `7`=Suministro, `8`=Distribuidora. Default: `1`
xNomeUC	string	Nombre de la unidad consumidora
tpClasse	string	Clase de consumo: `01`=Comercial, `02`=Consumo Propio, `03`=Alumbrado Público, `04`=Industrial, `05`=Poder Público, `06`=Residencial, `07`=Rural, `08`=Servicio Público. Default: `06`
tpSubClasse	string	Subclase de consumo (`01`–`29`, `99`)
tpFase	int	Tipo de conexión: `1`=Monofásico, `2`=Bifásico, `3`=Trifásico. Default: `3`
tpGrpTensao	string	Grupo de tensión (`01`–`14`: A1..B4b). Default: `12`
tpModTar	string	Modalidad tarifaria (`01`–`10`: Convencional/Horaria Azul/Verde/Blanca...). Default: `01`
latGPS	string	Latitud del punto de captura. Exactamente 6 decimales (ej.: `"-23.550500"`). Default: coordenada por defecto
longGPS	string	Longitud del punto de captura. Exactamente 6 decimales (ej.: `"-46.633300"`). Default: coordenada por defecto

det[] — Ítems facturados

Campo	Tipo	Descripción
cProd	string	Código del ítem. Opcional — default: número secuencial
xProd *	string	Descripción del ítem facturado (ej.: "Consumo de energía eléctrica")
cClass *	string	Código de clasificación del ítem (7 dígitos — tabla de clasificación de ítems de la NF3e)
CFOP	string	CFOP de la operación (obligatorio cuando el ítem tiene ICMS)
uMed	string	Unidad de medida: `1`=kW, `2`=kWh, `3`=kVAr, `4`=kVArh, `5`=UN. Default: `2`
qFaturada	string	Cantidad facturada. Default: `"1"`
vItem *	string	Valor unitario (tarifa) del ítem
vProd *	string	Valor total del ítem
indOrigemQtd	string	Origen de la cantidad: `1`=Promedio, `2`=Medido, `3`=Contratada, `4`=Calculada, `5`=Costo disp., `6`=Sin cant. Default: `2`
infAdProd	string	Información adicional del ítem
icms	object	Tributación de ICMS del ítem (ver abajo)
pis	object	PIS del ítem (ver abajo)
cofins	object	COFINS del ítem (misma estructura del PIS)
ibscbs	object	IBS/CBS — Reforma Tributaria (ver abajo)

det[].icms — ICMS del ítem

Campo	Tipo	Descripción
cst	string	CST del ICMS. Default: `"00"` (tributación integral)
vBC	string	Base de cálculo del ICMS
pICMS	string	Alícuota del ICMS (%)
vICMS	string	Valor del ICMS
isento	bool	`true` = ítem exento/no tributado (grupo `ICMS40`)
semCST	bool	`true` = ítem sin relación con el ICMS (`indSemCST`; no informe CFOP en ese caso)

det[].pis / det[].cofins

Campo	Tipo	Descripción
cst	string	CST del PIS/COFINS. Default: `"01"`
vBC	string	Base de cálculo
pAliq	string	Alícuota (%)
valor	string	Valor del tributo

det[].ibscbs — IBS/CBS (Reforma Tributaria)

Campo	Tipo	Descripción
cst	string	CST del IBS/CBS (3 dígitos)
cClassTrib	string	Código de clasificación tributaria
vBC	string	Base de cálculo
pIBSUF / vIBSUF	string	Alícuota y valor del IBS estadual
pIBSMun / vIBSMun	string	Alícuota y valor del IBS municipal
vIBS	string	Valor total del IBS
pCBS / vCBS	string	Alícuota y valor de la CBS

gFat — Datos de la factura

Campo	Tipo	Descripción
CompetFat	string	Competencia de la factura en formato `AAAAMM`
dVencFat	string	Fecha de vencimiento en formato `AAAA-MM-DD`
dProxLeitura	string	Fecha prevista de la próxima lectura (`AAAA-MM-DD`). Opcional — default: +30 días
codBarras	string	Línea digitable del código de barras (solo dígitos, 1–48)
codDebAuto	string	Código de autorización de débito en cuenta (alternativa a `codBanco`+`codAgencia`)
codBanco / codAgencia	string	Banco y agencia para débito en cuenta. Uno de los dos grupos (`codDebAuto` O `codBanco`+`codAgencia`) es exigido por el schema — default: banco `001`, agencia `0001`

* Campo obligatorio. ⚠ En el destinatario, al menos uno de CNPJ, CPF o idOutros es obligatorio. Los valores monetarios y alícuotas se envían como string con punto decimal (ej.: "75.00").

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 situación de la NF3e

Consulta la situación actual de la NF3e en el ambiente nacional (SVRS) a partir de la clave de acceso.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chNF3e *	string	Clave de acceso de la NF3e (44 dígitos)

* Campo obligatorio.

POST/api/nf3e/cancel

Cancelar NF3e

Cancela una NF3e autorizada (evento 110111). Requiere que la NF3e haya sido autorizada (posea protocolo) y aún no esté cancelada.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chNF3e *	string	Clave de acceso de la NF3e (44 dígitos)
xJust *	string	Justificación de la cancelación (mínimo 15 caracteres por exigencia de la autoridad fiscal)
nProt *	string	Protocolo de autorización de la NF3e (16 dígitos)

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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

Obtener PDF de la NF3e

Retorna la URL del DANF3E — la representación en PDF de la NF3e (cuenta de energía). El PDF se genera automáticamente en la autorización; cuando aún no existe en el almacenamiento, se genera bajo demanda a partir del XML.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chNF3e *	string	Clave de acceso de la NF3e (44 dígitos)

* Campo obligatorio.

GET/api/nf3e/get_list

Listar NF3e (con paginación)

Lista las NF3e de la empresa con paginación. Los parámetros se pasan por query string (no en el body).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
page *	int	Número de página (≥ 1)
page_size *	int	Tamaño de página (1–50)

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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
          }
        }