NFCom 通信发票 · TF Fiscal API

说明

NFCom — 电子通信服务发票

NFCom API（型号 62，布局 1.00）支持开具、查询、取消电子通信服务发票（NFCom）并获取其 PDF（DANFE-COM）。NFCom 取代了旧的 21/22 型号，用于记录电信服务账单——电话、互联网、付费电视、数据。授权在全国统一环境（SVRS）完成。开具方数据会自动填充，来自公司档案（CNPJ、IE、公司名称和地址）；访问密钥的技术字段（cNF、cDV、cUF、dhEmi、mod）由服务器计算。查询二维码（qrCodNFCom）也会自动生成。

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

必须事先完成准入登记（credenciamento）：开具 NFCom 要求开具方 CNPJ 已在其所在 UF 的税务局完成型号 62 的准入登记（该资质仅限电信服务提供商）。未完成准入登记时，税务局会以 cStat=203（"Emissor não habilitado para emissão da NFCom"）拒绝开具。测试环境与生产环境的准入登记是相互独立的步骤。

POST/api/nfcom/create

开具 NFCom

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

必需请求头

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

Body — 根

字段	类型	说明
ide	object	NFCom 的标识（环境、系列号、应税事实所属期）
dest *	object	接收方/承接方数据
assinante *	object	服务订户数据（NFCom 布局中必填）
det *	array	计费项目——至少 1 项
total	object	合计块。可选——省略时根据项目计算
gFat	object	账单数据（所属期、到期日、条形码）
infAdFisco	string	税务机关关注的信息
infCpl	array	补充信息（文本列表）
autXML	array	被授权访问 XML 的 CNPJ/CPF（字符串列表）

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

ide — 标识

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

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

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	电子邮箱

assinante — 服务订户

字段	类型	说明
iCodAssinante *	string	订户唯一识别代码（1–30 个字符）
tpAssinante	int	订户类型：`1`=商业，`2`=工业，`3`=住宅，`4`=农业生产者，`5`=公共机构，`6`=电信服务提供商，`7`=外交使团，`8`=教堂与寺庙，`99`=其他。默认：`1`
tpServUtil	int	所用服务类型：`1`=电话，`2`=数据通信，`3`=付费电视，`4`=互联网接入，`5`=多媒体，`6`=其他，`7`=多种。默认：`1`
nContrato	string	订户合同编号

det[] — 计费项目

字段	类型	说明
cProd	string	项目代码。可选——默认：顺序编号
xProd *	string	所计费服务/项目的描述
cClass *	string	项目分类代码（7 位——NFCom 项目分类表）
CFOP	string	服务的 CFOP（项目含 ICMS 时必填）
uMed	string	计量单位：`1`=分钟，`2`=MB，`3`=GB，`4`=UN。默认：`4`
qFaturada	string	计费数量。默认：`"1"`
vItem *	string	项目单价
vProd *	string	项目总金额
vDesc	string	折扣金额
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 金额
simplesNacional	bool	`true` = 开具方为简易税制（Simples Nacional）（`ICMSSN` 组）
semCST	bool	`true` = 项目与 ICMS 无关（`indSemCST`；此时请勿填写 CFOP）

det[].pis / det[].cofins

字段	类型	说明
cst	string	PIS/COFINS 的 CST（`01`、`02`、`06`、`07`、`08`、`09`、`49`）。默认：`"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 的税率和金额

total — 合计（可选）

字段	类型	说明
vProd	string	各项目之和。省略时自动计算
vBC	string	ICMS 计税基数合计
vICMS	string	ICMS 总额
vDesc	string	折扣合计
vNF	string	NFCom 总额。默认：与 `vProd` 相同

gFat — 账单数据

字段	类型	说明
CompetFat	string	账单所属期，格式 `AAAAMM`
dVencFat	string	到期日，格式 `AAAA-MM-DD`
codBarras	string	账单条形码（仅数字，1–48 位）

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

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/nfcom/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "ide": {
            "tpAmb": 2
          },
          "dest": {
            "xNome": "CLIENTE EXEMPLO LTDA",
            "CNPJ": "98765432000188",
            "indIEDest": 9,
            "enderDest": {
              "xLgr": "AVENIDA EXEMPLO",
              "nro": "500",
              "xBairro": "CENTRO",
              "cMun": 3550308,
              "xMun": "SAO PAULO",
              "CEP": "01001000",
              "UF": "SP"
            }
          },
          "assinante": {
            "iCodAssinante": "CLI-0001",
            "tpAssinante": 1,
            "tpServUtil": 4,
            "nContrato": "CT-2026-0001"
          },
          "det": [
            {
              "cProd": "1",
              "xProd": "PLANO INTERNET FIBRA 500MB",
              "cClass": "0100101",
              "CFOP": "5307",
              "uMed": "4",
              "qFaturada": "1.00",
              "vItem": "99.90",
              "vProd": "99.90",
              "icms": {
                "cst": "00",
                "vBC": "99.90",
                "pICMS": "25.00",
                "vICMS": "24.98"
              }
            }
          ],
          "total": {
            "vProd": "99.90",
            "vBC": "99.90",
            "vICMS": "24.98",
            "vNF": "99.90"
          },
          "gFat": {
            "CompetFat": "202607",
            "dVencFat": "2026-08-15",
            "codBarras": "12345678901234567890"
          }
        }

        {
          "success": true,
          "message": "NFCom autorizada",
          "data": {
            "chave": "35260712345678000199620010000000011012345675",
            "serie": 1,
            "number": 1,
            "cStat": "100",
            "xMotivo": "Autorizado o uso da NFCom",
            "nProt": "353260000123456",
            "xml": "https://storage.../nfcom/35260712345678000199620010000000011012345675.xml",
            "danfcom": "https://storage.../nfcom/35260712345678000199620010000000011012345675.pdf"
          }
        }

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

POST/api/nfcom/consult

查询 NFCom 状态

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

必需请求头

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

Body

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

* 必填字段。

POST/api/nfcom/cancel

取消 NFCom

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

必需请求头

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

Body

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

* 必填字段。

POST/api/nfcom/pdf

获取 NFCom PDF

返回 DANFE-COM 的 URL——NFCom 的 PDF 表现形式（订户账单），符合 MOC 附件 II。PDF 在授权时自动生成；当存储中尚不存在时，会根据 XML 按需生成。

必需请求头

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

Body

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

* 必填字段。

GET/api/nfcom/get_list

NFCom 列表（分页）

分页列出公司的 NFCom。参数通过 查询字符串（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/nfcom/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN"

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

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260712345678000199620010000000011012345675",
                "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
          }
        }