NF3-e 电力发票 · TF Fiscal API

说明

NF3e — 电子电能发票

NF3e API（型号 66，布局 1.00）支持开具、查询、取消电子电能发票（NF3e）并获取其 PDF（DANF3E）——即取代电能发票/账单（型号 6）的电子版"电费单"。授权在全国统一环境（SVRS）完成。开具方数据会自动填充，来自公司档案（CNPJ、IE、公司名称和地址）；访问密钥的技术字段（cNF、cDV、cUF、dhEmi、mod、serie）由服务器填充。查询二维码（qrCodNF3e）也会自动生成。

端点	方法	说明
`/api/nf3e/create`	POST	开具 NF3e
`/api/nf3e/consult`	POST	查询 NF3e 状态
`/api/nf3e/cancel`	POST	取消已授权的 NF3e
`/api/nf3e/pdf`	POST	获取 NF3e 的 DANF3E（PDF）
`/api/nf3e/get_list`	GET	列出 NF3e（分页）

必须事先完成准入登记（credenciamento）：开具 NF3e 要求开具方 CNPJ 已在其所在 UF 的税务局完成型号 66 的准入登记（该资质仅限配电与售电企业）。未完成准入登记时，税务局会以 cStat=203（"Emissor não habilitado para emissão da NF3e"）拒绝开具。此外，自 2026 年 8 月 3 日 起，生产环境将强制要求 IBS/CBS（税制改革）分组。

NF3e 需要 gANEEL 分组（计费历史——每项计量指标 13 个所属期）。未发送时，服务器会根据计费金额自动生成这 13 个所属期。

POST/api/nf3e/create

开具 NF3e

根据发送的请求体开具一张 NF3e。客户端只发送业务数据——开具方块（emit）会根据 token 对应公司的档案自动组装，访问密钥的技术字段由服务器计算。仅在生产环境（tpAmb=1）且 NF3e 被授权时才扣除额度。授权后，XML（nf3eProc）和 DANF3E（PDF）会生成并通过 URL 提供。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名：`MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒，5 分钟窗口）

Body — 根

字段	类型	说明
ide	object	NF3e 的标识（环境、应税事实所属期）
dest *	object	接收方/消费者数据
acessante *	object	消费单元数据（NF3e 布局中必填）
det *	array	计费项目——至少 1 项
total	object	合计块。可选——省略时根据项目计算
gFat	object	账单数据（所属期、到期日、下次抄表、条形码）
gANEEL	array	计费历史（每项计量指标 13 个所属期）。可选——省略时自动生成
infAdFisco	string	税务机关关注的信息
infCpl	array	补充信息（文本列表）
autXML	array	被授权访问 XML 的 CNPJ/CPF（字符串列表）

请求中的必填字段： dest 含 xNome、CNPJ/CPF/idOutros 之一以及 enderDest（xLgr、nro、xBairro、cMun、xMun、CEP 为 8 位、UF）；acessante.idAcesso；以及 det 中至少 1 项，含 xProd、cClass（NF3e 项目分类表的 7 位代码）、vItem 和 vProd。其余所有字段均为可选。

ide — 标识

字段	类型	说明
tpAmb	int	环境：`1`=生产，`2`=测试。默认：`2`
nNF	long	NF3e 的顺序编号。可选——省略或为 `0` 时由服务器自动递增
dhEmi	string	开具日期/时间。可选——省略时由服务器生成
cMunFG	long	应税事实发生地自治市的 IBGE 代码（7 位）。可选——默认：公司档案中的自治市
finNF3e	int	用途：`1`=正常，`2`=替代，`3`=带调整的正常。默认：`1`
nSiteAutoriz	int	授权站点（访问密钥的 1 位）。默认：`0`

由服务器自动填充——无须发送： mod（固定为 66）、serie（公司中登记的 NF3e 系列；通过 /api/company/edit 的 serie_nf3e 配置）、cUF（从公司档案推导）、cNF（7 位数字代码）、cDV（访问密钥校验位）、tpEmis（正常）和 verProc。完整的 emit 块和 infNF3eSupl（二维码）也由服务器组装。

dest — 接收方 / 消费者

字段	类型	说明
xNome *	string	消费者的姓名或公司名称
CNPJ ⚠	string	消费者 CNPJ（14 位）
CPF ⚠	string	消费者 CPF（11 位）
idOutros ⚠	string	其他身份证件（外国人等）
indIEDest	int	IE 指示符：`1`=纳税人，`2`=免税，`9`=非纳税人。默认：`9`
IE	string	消费者的州登记号（为纳税人时）
enderDest *	object	消费者地址（见下方结构）

enderDest — 地址

字段	类型	说明
xLgr *	string	街道
nro *	string	门牌号
xCpl	string	补充信息
xBairro *	string	街区
cMun *	long	自治市 IBGE 代码（7 位）
xMun *	string	自治市名称
CEP *	string	邮政编码（8 位）
UF *	string	UF 简称（2 个字母）
fone	string	电话
email	string	电子邮箱

acessante — 消费单元

字段	类型	说明
idAcesso *	string	消费单元/接入点的识别代码（最多 15 个字符）
tpAcesso	int	接入类型：`0`=发电方，`1`=专属，`2`=自由，`3`=部分自由，`4`=特殊消费者，`5`=部分特殊，`6`=共用，`7`=供电，`8`=配电商。默认：`1`
xNomeUC	string	消费单元名称
tpClasse	string	消费类别：`01`=商业，`02`=自用，`03`=公共照明，`04`=工业，`05`=公共部门，`06`=居民，`07`=农村，`08`=公共服务。默认：`06`
tpSubClasse	string	消费子类别（`01`–`29`、`99`）
tpFase	int	接线类型：`1`=单相，`2`=两相，`3`=三相。默认：`3`
tpGrpTensao	string	电压组（`01`–`14`：A1..B4b）。默认：`12`
tpModTar	string	电价方式（`01`–`10`：常规/蓝色分时/绿色/白色…）。默认：`01`
latGPS	string	采集点纬度。恰好 6 位小数（例如：`"-23.550500"`）。默认：标准坐标
longGPS	string	采集点经度。恰好 6 位小数（例如：`"-46.633300"`）。默认：标准坐标

det[] — 计费项目

字段	类型	说明
cProd	string	项目代码。可选——默认：顺序编号
xProd *	string	计费项目的描述（例如："电能消耗"）
cClass *	string	项目分类代码（7 位——NF3e 项目分类表）
CFOP	string	操作的 CFOP（项目含 ICMS 时必填）
uMed	string	计量单位：`1`=kW，`2`=kWh，`3`=kVAr，`4`=kVArh，`5`=UN。默认：`2`
qFaturada	string	计费数量。默认：`"1"`
vItem *	string	项目单价（电价）
vProd *	string	项目总金额
indOrigemQtd	string	数量来源：`1`=平均，`2`=实测，`3`=合同约定，`4`=计算，`5`=可用成本，`6`=无数量。默认：`2`
infAdProd	string	项目附加信息
icms	object	项目的 ICMS 税务处理（见下方）
pis	object	项目的 PIS（见下方）
cofins	object	项目的 COFINS（结构与 PIS 相同）
ibscbs	object	IBS/CBS——税制改革（见下方）

det[].icms — 项目的 ICMS

字段	类型	说明
cst	string	ICMS 的 CST。默认：`"00"`（全额征税）
vBC	string	ICMS 计税基数
pICMS	string	ICMS 税率（%）
vICMS	string	ICMS 金额
isento	bool	`true` = 项目免税/不征税（`ICMS40` 组）
semCST	bool	`true` = 项目与 ICMS 无关（`indSemCST`；此时请勿填写 CFOP）

det[].pis / det[].cofins

字段	类型	说明
cst	string	PIS/COFINS 的 CST。默认：`"01"`
vBC	string	计税基数
pAliq	string	税率（%）
valor	string	税额

det[].ibscbs — IBS/CBS（税制改革）

字段	类型	说明
cst	string	IBS/CBS 的 CST（3 位）
cClassTrib	string	税务分类代码
vBC	string	计税基数
pIBSUF / vIBSUF	string	州 IBS 的税率和金额
pIBSMun / vIBSMun	string	市 IBS 的税率和金额
vIBS	string	IBS 总额
pCBS / vCBS	string	CBS 的税率和金额

gFat — 账单数据

字段	类型	说明
CompetFat	string	账单所属期，格式 `AAAAMM`
dVencFat	string	到期日，格式 `AAAA-MM-DD`
dProxLeitura	string	下次抄表预计日期（`AAAA-MM-DD`）。可选——默认：+30 天
codBarras	string	条形码可识别行（仅数字，1–48 位）
codDebAuto	string	账户自动扣款授权码（可替代 `codBanco`+`codAgencia`）
codBanco / codAgencia	string	用于账户扣款的银行和网点。schema 要求 `codDebAuto` 或 `codBanco`+`codAgencia` 两组之一——默认：银行 `001`，网点 `0001`

* 必填字段。⚠ 接收方中，CNPJ、CPF 或 idOutros 至少须填一个。金额和税率以带小数点的字符串发送（例如："75.00"）。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
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

查询 NF3e 状态

根据访问密钥查询 NF3e 在全国统一环境（SVRS）中的当前状态。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chNF3e *	string	NF3e 访问密钥（44 位）

* 必填字段。

POST/api/nf3e/cancel

取消 NF3e

取消一张已授权的 NF3e（事件 110111）。要求 NF3e 已被授权（已有协议号）且尚未取消。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chNF3e *	string	NF3e 访问密钥（44 位）
xJust *	string	取消理由（按税务局要求至少 15 个字符）
nProt *	string	NF3e 的授权协议号（16 位）

* 必填字段。

POST/api/nf3e/pdf

获取 NF3e PDF

返回 DANF3E 的 URL——NF3e 的 PDF 表现形式（电费账单）。PDF 在授权时自动生成；当存储中尚不存在时，会根据 XML 按需生成。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chNF3e *	string	NF3e 访问密钥（44 位）

* 必填字段。

GET/api/nf3e/get_list

NF3e 列表（分页）

分页列出公司的 NF3e。参数通过 查询字符串（query string）传递（不在 body 中）。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名（path 包含查询字符串）
timestamp	string	Unix 时间戳（秒）

查询字符串

参数	类型	说明
page *	int	页码（≥ 1）
page_size *	int	每页大小（1–50）

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
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
          }
        }