NF3-e Electricity · TF Fiscal API

Note

NF3e — Electronic Electricity Invoice

The NF3e API (model 66, layout 1.00) lets you issue, consult, cancel and get the PDF (DANF3E) of Electronic Electricity Invoices — the electronic "electricity bill" that replaces the Electricity Invoice/Bill (model 6). Authorization takes place in the single national environment (SVRS). The issuer data is filled in automatically from the company registration (CNPJ, IE, corporate name and address); the technical access-key fields (cNF, cDV, cUF, dhEmi, mod, serie) are filled in by the server. The consultation QR code (qrCodNF3e) is also generated automatically.

Endpoint	Method	Description
`/api/nf3e/create`	POST	Issue NF3e
`/api/nf3e/consult`	POST	Consult NF3e status
`/api/nf3e/cancel`	POST	Cancel an authorized NF3e
`/api/nf3e/pdf`	POST	Get the DANF3E (PDF) of the NF3e
`/api/nf3e/get_list`	GET	List NF3e (paginated)

Mandatory accreditation: issuing NF3e requires the issuing CNPJ to be accredited for model 66 with the tax authority of its state (enablement restricted to electricity distributors and traders). Without the accreditation, tax authority rejects the issuance with cStat=203 ("Emissor não habilitado para emissão da NF3e"). In addition, from August 3, 2026 the IBS/CBS groups (Tax Reform) become required in the production environment.

The NF3e requires the gANEEL group (billing history — 13 periods per quantity). When not sent, the server automatically generates the 13 periods from the billed value.

POST/api/nf3e/create

Issue NF3e

Issues an NF3e from the submitted body. The client sends only the business data — the issuer block (emit) is built automatically from the registration of the token's company, and the technical access-key fields are calculated by the server. Credit is debited only in production (tpAmb=1) and when the NF3e is authorized. After authorization, the XML (nf3eProc) and the DANF3E (PDF) are generated and made available by URL.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Body — root

Field	Type	Description
ide	object	NF3e identification (environment, taxable event period)
dest *	object	Recipient / consumer data
acessante *	object	Consumer unit data (required in the NF3e layout)
det *	array	Billed items — at least 1
total	object	Totals. Optional — calculated from the items when omitted
gFat	object	Invoice data (billing period, due date, next reading, barcode)
gANEEL	array	Billing history (13 periods per quantity). Optional — generated automatically when omitted
infAdFisco	string	Information of interest to the tax authority
infCpl	array	Complementary information (list of texts)
autXML	array	CNPJs/CPFs authorized to access the XML (list of strings)

Required fields in the request: dest with xNome, one of CNPJ/CPF/idOutros and enderDest (xLgr, nro, xBairro, cMun, xMun, CEP with 8 digits, UF); acessante.idAcesso; and at least 1 item in det with xProd, cClass (7 digits from the NF3e item classification table), vItem and vProd. All other fields are optional.

ide — Identification

Field	Type	Description
tpAmb	int	Environment: `1`=production, `2`=staging. Default: `2`
nNF	long	Sequential NF3e number. Optional — auto-incremented by the server when omitted or `0`
dhEmi	string	Issuance date/time. Optional — generated by the server when omitted
cMunFG	long	IBGE code of the taxable event municipality (7 digits). Optional — default: the municipality from the company registration
finNF3e	int	Purpose: `1`=Normal, `2`=Replacement, `3`=Normal with adjustment. Default: `1`
nSiteAutoriz	int	Authorizing site (1 digit of the access key). Default: `0`

Filled in automatically by the server — you do not need to send them: mod (fixed at 66), serie (the NF3e series registered for the company; set it in /api/company/edit via serie_nf3e), cUF (derived from the company registration), cNF (7-digit numeric code), cDV (access key check digit), tpEmis (normal) and verProc. The complete emit block and the infNF3eSupl (QR code) are also built by the server.

dest — Recipient / Consumer

Field	Type	Description
xNome *	string	Consumer name or corporate name
CNPJ ⚠	string	Consumer CNPJ (14 digits)
CPF ⚠	string	Consumer CPF (11 digits)
idOutros ⚠	string	Other identification document
indIEDest	int	IE indicator: `1`=taxpayer, `2`=exempt, `9`=non-taxpayer. Default: `9`
IE	string	Consumer state registration (when a taxpayer)
enderDest *	object	Consumer address (see structure below)

enderDest — Address

Field	Type	Description
xLgr *	string	Street
nro *	string	Number
xCpl	string	Complement
xBairro *	string	Neighborhood
cMun *	long	IBGE municipality code (7 digits)
xMun *	string	Municipality name
CEP *	string	Postal code (8 digits)
UF *	string	State abbreviation (2 letters)
fone	string	Phone
email	string	E-mail

acessante — Consumer unit

Field	Type	Description
idAcesso *	string	Consumer unit / access point identification code (up to 15 characters)
tpAcesso	int	Access type: `0`=Generator, `1`=Captive, `2`=Free, `3`=Partially free, `4`=Special consumer, `5`=Partially special, `6`=Communion, `7`=Supply, `8`=Distributor. Default: `1`
xNomeUC	string	Consumer unit name
tpClasse	string	Consumption class: `01`=Commercial, `02`=Own consumption, `03`=Public lighting, `04`=Industrial, `05`=Public authority, `06`=Residential, `07`=Rural, `08`=Public service. Default: `06`
tpSubClasse	string	Consumption subclass (`01`–`29`, `99`)
tpFase	int	Connection type: `1`=Single-phase, `2`=Two-phase, `3`=Three-phase. Default: `3`
tpGrpTensao	string	Voltage group (`01`–`14`: A1..B4b). Default: `12`
tpModTar	string	Tariff modality (`01`–`10`: Conventional/Time-of-use Blue/Green/White...). Default: `01`
latGPS	string	Latitude of the capture point. Exactly 6 decimal places (e.g.: `"-23.550500"`). Default: standard coordinate
longGPS	string	Longitude of the capture point. Exactly 6 decimal places (e.g.: `"-46.633300"`). Default: standard coordinate

det[] — Billed items

Field	Type	Description
cProd	string	Item code. Optional — default: sequential number
xProd *	string	Description of the billed item (e.g.: "Consumo de energia elétrica")
cClass *	string	Item classification code (7 digits — NF3e item classification table)
CFOP	string	CFOP of the operation (required when the item has ICMS)
uMed	string	Unit of measure: `1`=kW, `2`=kWh, `3`=kVAr, `4`=kVArh, `5`=UN. Default: `2`
qFaturada	string	Billed quantity. Default: `"1"`
vItem *	string	Unit value (tariff) of the item
vProd *	string	Total value of the item
indOrigemQtd	string	Quantity origin: `1`=Average, `2`=Measured, `3`=Contracted, `4`=Calculated, `5`=Available cost, `6`=No quantity. Default: `2`
infAdProd	string	Additional item information
icms	object	ICMS taxation of the item (see below)
pis	object	Item PIS (see below)
cofins	object	Item COFINS (same structure as PIS)
ibscbs	object	IBS/CBS — Tax Reform (see below)

det[].icms — Item ICMS

Field	Type	Description
cst	string	ICMS CST. Default: `"00"` (full taxation)
vBC	string	ICMS calculation base
pICMS	string	ICMS rate (%)
vICMS	string	ICMS value
isento	bool	`true` = exempt/non-taxed item (`ICMS40` group)
semCST	bool	`true` = item not related to ICMS (`indSemCST`; do not send CFOP in this case)

det[].pis / det[].cofins

Field	Type	Description
cst	string	PIS/COFINS CST. Default: `"01"`
vBC	string	Calculation base
pAliq	string	Rate (%)
valor	string	Tax value

det[].ibscbs — IBS/CBS (Tax Reform)

Field	Type	Description
cst	string	IBS/CBS CST (3 digits)
cClassTrib	string	Tax classification code
vBC	string	Calculation base
pIBSUF / vIBSUF	string	Rate and value of the state IBS
pIBSMun / vIBSMun	string	Rate and value of the municipal IBS
vIBS	string	Total IBS value
pCBS / vCBS	string	Rate and value of the CBS

gFat — Invoice data

Field	Type	Description
CompetFat	string	Invoice billing period in `AAAAMM` format
dVencFat	string	Due date in `AAAA-MM-DD` format
dProxLeitura	string	Expected date of the next reading (`AAAA-MM-DD`). Optional — default: +30 days
codBarras	string	Barcode digitable line (digits only, 1–48)
codDebAuto	string	Automatic account debit authorization code (alternative to `codBanco`+`codAgencia`)
codBanco / codAgencia	string	Bank and branch for direct debit. One of the two groups (`codDebAuto` OR `codBanco`+`codAgencia`) is required by the schema — default: bank `001`, branch `0001`

* Required field. ⚠ In the recipient, at least one of CNPJ, CPF or idOutros is required. Monetary values and rates are sent as strings with a decimal point (e.g.: "75.00").

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

Consult NF3e status

Consults the current status of the NF3e in the national environment (SVRS) from the access key.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chNF3e *	string	Access key of the NF3e (44 digits)

* Required field.

POST/api/nf3e/cancel

Cancel NF3e

Cancels an authorized NF3e (event 110111). Requires that the NF3e has been authorized (has a protocol) and is not yet cancelled.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chNF3e *	string	Access key of the NF3e (44 digits)
xJust *	string	Cancellation justification (minimum 15 characters as required by the tax authority)
nProt *	string	NF3e authorization protocol (16 digits)

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

Get NF3e PDF

Returns the URL of the DANF3E — the PDF representation of the NF3e (electricity bill). The PDF is generated automatically at authorization; when it does not yet exist in storage, it is generated on demand from the XML.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chNF3e *	string	Access key of the NF3e (44 digits)

* Required field.

GET/api/nf3e/get_list

List NF3e (paginated)

Lists the company's NF3e with pagination. Parameters are passed via query string (not in the body).

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature (path includes the query string)
timestamp	string	Unix timestamp in seconds

Query string

Parameter	Type	Description
page *	int	Page number (≥ 1)
page_size *	int	Page size (1–50)

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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
          }
        }