NFS-e 服务发票 · TF Fiscal API

说明

NFS-e - 电子服务发票

NFS-e API 允许开具、取消和查询电子服务发票。系统自动检测公司所在城市并路由到正确的 API：

圣保罗 (SP) - 通过 Nota Fiscal Paulistana (SOAP) 开具
其他城市 - 通过国家 API (ADN/SEFIN) 开具

集成方无需担心使用哪个 API - 只需发送数据，系统会根据公司注册的城市 IBGE 代码自动路由。

端点	方法	描述
`/api/nfse/create`	POST	开具 NFS-e
`/api/nfse/cancel`	POST	取消 NFS-e
`/api/nfse/get_danfse`	POST	获取 DANFSE (PDF)
`/api/nfse/get_xml`	POST	下载 XML

POST/api/nfs/company/create

注册 NFS-e 公司

注册(或更新)用于 NFS-e 开具的企业。如果该 CNPJ 已存在于用户下,则仅更新 NFS-e 字段和证书;否则创建新企业并返回专用 token。注意路径:/api/nfs/...(无 "e"),与其他 NFS-e 端点不同。

必需请求头

请求头	类型	说明
token	string	集成商 B2B token
sign	string	MD5 签名
timestamp	string	Unix 时间戳(秒)

Body

字段	类型	说明
cnpj *	string	企业 CNPJ(仅数字)
name *	string	法人名称
cep *	string	邮政编码(仅数字)
address *	string	街道
house_number *	string	地址号
town *	string	街区
city *	string	城市
state *	string	州(2 位,如 "SP")
cert_content *	string	A1 数字证书文件内容（.pfx/.p12 的 Base64）
cert_file	string	已废弃，2026-09-01 起拒绝。证书 HTTPS URL
cert_pwd *	string	数字证书密码
im *	string	市政登记号(Inscrição Municipal)
codigo_municipio_nfse *	string	开具市政的 IBGE 代码
codigo_servico_nfse *	string	默认服务代码(LC 116)
alias	string	商号
ie	string	州登记号
invoice_type	string	税务体制
unit	string	单位 / 分支
email	string	联系邮箱
telefone	string	电话
complemento	string	地址补充
cnae_nfse	string	默认活动 CNAE
serie_nfse	int	NFS-e 初始序列
number_nfse	int	NFS-e 初始编号
regime_especial_tributacao	int	特殊税制代码
optante_simples_nacional	bool	是否加入 Simples Nacional

* 必填字段。

注意: 返回的 token 必须在其他 NFS-e 调用(/api/nfse/create、/cancel、/get_danfse、/get_xml)中使用。如果企业已存在,消息将为 "Empresa atualizada para NFS-e",返回的 token 是现有 token。

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

        {
          "cnpj": "43649380000100",
          "name": "EMPRESA EXEMPLO LTDA",
          "alias": "Exemplo",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contato@empresa.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "Rua Exemplo",
          "house_number": "86",
          "complemento": "Andar 2",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_content": "MIIOkAIBAzCC...(Base64)",
          "cert_pwd": "senha-do-certificado",
          "im": "12345678",
          "codigo_municipio_nfse": "3550308",
          "codigo_servico_nfse": "07498",
          "cnae_nfse": "6201501",
          "serie_nfse": 1,
          "number_nfse": 1,
          "regime_especial_tributacao": 0,
          "optante_simples_nacional": true
        }

        {
          "success": true,
          "message": "Empresa cadastrada para NFS-e",
          "data": {
            "company_id": 12345,
            "token": "token-dedicado-da-empresa"
          }
        }

POST/api/nfse/create

开具 NFS-e

必需请求头

请求头	类型	描述
token	string	公司令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）（5分钟窗口）

主要字段

字段	类型	描述
ambiente	string	`"1"` = 生产环境, `"2"` = 测试环境
id	string	外部参考 ID（可选）
descricao_servico	string	服务描述（必填）
valor_servico	decimal	服务总金额（R$）（必填）
aliquota_iss	decimal	ISS 税率（%）（例：2.90）
iss_retido	boolean	`false` = 未代扣, `true` = 由付款方代扣
valor_iss	decimal	ISS 值覆盖。如果大于 0,覆盖自动计算 (base_calculo × aliquota_iss ÷ 100)。默认:自动计算
codigo_servico	string	服务代码。留空则使用公司默认值
cnae	string	CNAE。留空则使用公司默认值
tomador	object	服务接受方数据（必填）

付款方字段

字段	类型	描述
cnpj	string	付款方 CNPJ（仅数字）
cpf	string	付款方 CPF（使用 cnpj 或 cpf）
name	string	名称/公司名（必填）
email	string	付款方邮箱
telefone	string	电话
cep	string	邮编（必填）
endereco	string	地址（必填）
numero	string	门牌号（必填）
complemento	string	补充地址
bairro	string	街区（必填）
city	string	城市
uf	string	州（2位）
codigo_municipio	string	IBGE 城市代码

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

        {
          "ambiente": "1",
          "id": "REF-001",
          "descricao_servico": "Desenvolvimento de sistemas",
          "valor_servico": 10000.00,
          "aliquota_iss": 2.90,
          "iss_retido": false,
          "codigo_servico": "",
          "cnae": "",
          "valor_deducoes": 0,
          "desconto_incondicionado": 0,
          "desconto_condicionado": 0,
          "valor_iss": 0,
          "valor_pis": 0,
          "valor_cofins": 0,
          "valor_inss": 0,
          "valor_ir": 0,
          "valor_csll": 0,
          "tomador": {
            "cnpj": "43649380000100",
            "cpf": "",
            "name": "EMPRESA TOMADORA LTDA",
            "email": "contato@empresa.com",
            "telefone": "11999999999",
            "inscricao_municipal": "",
            "cep": "03027020",
            "endereco": "Rua Exemplo",
            "numero": "86",
            "complemento": "Andar 2",
            "bairro": "Centro",
            "city": "Sao Paulo",
            "uf": "SP",
            "codigo_municipio": "3550308"
          }
        }

        {
          "success": true,
          "data": {
            "_id": "661234abcdef...",
            "uuid": "guid-unico",
            "status": "autorizada",
            "nfse": "48",
            "serie": 1,
            "chave": "Z685RI9C",
            "codigoVerificacao": "Z685RI9C",
            "modelo": "nfse",
            "tipoEmissao": "paulistana",
            "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
          }
        }

POST/api/nfse/cancel

取消 NFS-e

必需请求头

请求头	类型	描述
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

字段

字段	类型	描述
chave	string	NFS-e 验证码（必填）
motivo	string	取消原因（必填，全国标准要求15～255个字符）
c_motivo	string	取消理由代码（选填，全国标准）："1" = 开票错误（默认），"2" = 服务未提供，"9" = 其他

POST/api/nfse/get_danfse

获取 NFS-e PDF

必需请求头

请求头	类型	描述
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

字段

字段	类型	描述
chave	string	NFS-e 验证码（必填）

注意： 对于 Paulistana (SP)，返回市政厅的 PDF 直接 URL。对于国家 API，返回 base64 格式的 PDF。

POST/api/nfse/get_xml

下载 NFS-e XML

必需请求头

请求头	类型	描述
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

字段

字段	类型	描述
chave	string	NFS-e 验证码（必填）

dpsXml: 发送到市政厅/ADN 的 XML 链接（OSS URL）。 nfseXml: 包含开具结果的返回 XML 链接。XML 在首次请求时上传到 OSS，URL 会被缓存。

GET/api/nfse/get_list

NFS-e 列表（分页）

分页列出公司的 NFS-e。参数通过 查询字符串（query string）传递（不在 body 中）。时间过滤可选，但若使用则需同时传入 start_create_time 和 end_create_time。

必需请求头

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

查询字符串

参数	类型	说明
page *	int	页码（≥ 1）
page_size *	int	每页大小（1–50）
start_create_time	long	Unix 时间戳（毫秒） — 起始（需要 `end_create_time`）
end_create_time	long	Unix 时间戳（毫秒） — 结束
status	string	按状态过滤。值: `"autorizada"`、`"cancelada"`、`"pendente"`、`"rejeitada"`

* 必填字段。

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

GET /api/nfse/get_list?page=1&page_size=20&status=autorizada

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "31250112345678000190000000000012345678901234",
                "codigo_verificacao": "ABCD-1234",
                "serie": 1,
                "number": 1,
                "status": "autorizada",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }