公司管理 · TF Fiscal API

POST/api/company/create

注册新的开票公司

在分销商（b2b）账户下注册开票公司。当公司数据已有时使用此端点。要从数字证书自动提取数据，请使用 /api/company/v2/create。

必需请求头

请求头	类型	说明
token	string	分销商令牌（b2b — 账户必须具有 `isb2b=true`）
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
标识
cnpj *	string	开票公司 CNPJ
name *	string	公司名称
ie *	string	州注册号（Inscrição Estadual）
invoice_type *	string	税务制度（例如：`"simples_nacional"`、`"normal"`）
unit *	string	单位类型
email	string	公司电子邮件
地址
cep *	string	邮政编码
address *	string	街道地址
house_number *	string	地址门牌号
town *	string	街区
city *	string	城市
state *	string	UF（州缩写）
数字证书
cert_content *	string	A1 数字证书文件内容（.pfx/.p12 的 Base64）
cert_file	string	已废弃，2026-09-01 起拒绝。证书 HTTPS URL
cert_pwd *	string	证书密码
编号和设置
serie *	int	NF-e 系列
number *	int	编号的初始值
运输 (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e 系列
number_mdfe	int	MDF-e 起始编号（编号从此处开始）
serie_cte	int	CT-e 系列
number_cte	int	CT-e 起始编号（编号从此处开始）
serie_dce	int	DC-e 系列
number_dce	int	DC-e 起始编号（编号从此处开始）
通信 (NFCom)
serie_nfcom	int	NFCom 系列
number_nfcom	int	NFCom 起始编号（编号从此处开始）
能源 (NF3e)
serie_nf3e	int	NF3e 系列
number_nf3e	int	NF3e 起始编号（编号从此处开始）
is_create_category_template	boolean	自动创建默认税务类别。默认值：`true`

* 必填字段。

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

        {
          "cnpj": "12345678000199",
          "name": "Empresa Exemplo LTDA",
          "ie": "123456789",
          "invoice_type": "simples_nacional",
          "unit": "matriz",
          "email": "contato@empresa.com",
          "cep": "01001000",
          "address": "Rua Exemplo",
          "house_number": "100",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_content": "MIIOkAIBAzCC...(Base64)",
          "cert_pwd": "senha_do_certificado",
          "serie": 1,
          "number": 1,
          "serie_mdfe": 2,
          "number_mdfe": 1,
          "serie_cte": 3,
          "number_cte": 1,
          "serie_dce": 4,
          "number_dce": 1,
          "serie_nfcom": 5,
          "number_nfcom": 1,
          "serie_nf3e": 6,
          "number_nf3e": 1
        }

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST/api/company/v2/create

凭证书注册公司

/api/company/create 的简化版本：API 验证数字证书并通过内部查询自动提取公司名称、IE、地址等数据。只有 cnpj、cert_content 和 cert_pwd 是必填的。

必需请求头

请求头	类型	说明
token	string	分销商令牌（b2b — 账户必须具有 `isb2b=true`）
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
cnpj *	string	开票公司 CNPJ
cert_content *	string	A1 数字证书文件内容（.pfx/.p12 的 Base64）
cert_file	string	已废弃，2026-09-01 起拒绝。证书 HTTPS URL
cert_pwd *	string	证书密码
is_create_category_template	boolean	自动创建默认税务类别。默认值：`true`

* 必填字段。

POST/api/company/edit

编辑公司数据

更新开票公司数据。只发送要更改的字段 — 除 company_id 外，所有字段都是可选的。CNPJ 不可修改：发送会返回错误。更新 cep 时，系统自动解析 stateCode 和 ibge。当 cert_content 和 cert_pwd 一起发送时，证书在保存前会经过验证。

公司是以 NF-e 配置创建的（通过 /api/company/create）。要启用其他单证，请在此处完善登记：本接口还接受 NFC-e、NFS-e、MDF-e、CT-e 和 DC-e 字段（见下方各节）。只需发送公司将要开具的单证所对应的字段。

必需请求头

请求头	类型	说明
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
company_id *	string	要编辑的公司 ID
name	string	公司名称
invoice_type	string	税务制度
ie	string	州注册号
unit	string	单位类型
email	string	电子邮件
cep	string	邮政编码（自动更新 `stateCode` 和 `ibge`）
address	string	街道地址
house_number	string	门牌号
town	string	街区
city	string	城市
state	string	UF
cert_content	string	A1 数字证书文件内容（.pfx/.p12 的 Base64）
cert_file	string	已废弃，2026-09-01 起拒绝。证书 HTTPS URL
cert_pwd	string	新证书密码
serie	int	新 NF-e 系列
number	int	新初始编号
alias	string	商号
telefone	string	电话
complemento	string	地址补充
NFC-e
csc_id	string	税务局的 CSC（纳税人安全代码）ID
csc	string	CSC 令牌（与税务局共享的密钥）
serie_nfce	int	NFC-e 系列
number_nfce	int	NFC-e 下一个编号
NFS-e
im	string	市政登记号(Inscrição Municipal)
codigo_municipio_nfse	string	开具市政的 IBGE 代码
codigo_servico_nfse	string	默认服务代码(LC 116)
cnae_nfse	string	默认活动 CNAE
serie_nfse	int	NFS-e 系列
number_nfse	int	NFS-e 下一个编号
regime_especial_tributacao	int	特殊税制代码
optante_simples_nacional	bool	是否加入 Simples Nacional
运输 (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e 系列
number_mdfe	int	MDF-e 起始编号（编号从此处开始）
serie_cte	int	CT-e 系列
number_cte	int	CT-e 起始编号（编号从此处开始）
serie_dce	int	DC-e 系列
number_dce	int	DC-e 起始编号（编号从此处开始）
通信 (NFCom)
serie_nfcom	int	NFCom 系列
number_nfcom	int	NFCom 起始编号（编号从此处开始）
能源 (NF3e)
serie_nf3e	int	NF3e 系列
number_nf3e	int	NF3e 起始编号（编号从此处开始）

* 必填字段。发送 cnpj 会返回错误。其他所有字段均为可选 — 只需发送您想要更改的字段。

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

        {
          "company_id": "comp_789012",
          "name": "Nova Razão Social LTDA",
          "email": "novo@empresa.com",
          "cep": "01310100"
        }

        {
          "company_id": "comp_789012",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "serie_cte": 1,
          "number_cte": 1
        }

        {
          "success": true
        }

GET/api/company/get_list

获取公司列表

分页列出分销商（b2b）账户下的开票公司。参数通过 查询字符串 传递。

必需请求头

请求头	类型	说明
token	string	分销商令牌（b2b — 账户必须具有 `isb2b=true`）
sign	string	MD5 签名（path 包含查询字符串）
timestamp	string	秒级 Unix 时间戳

查询字符串

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

* 必填字段。

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

GET /api/company/get_list?page=1&page_size=10

        {
          "success": true,
          "data": {
            "companys": [
              {
                "company_id": "comp_789012",
                "invoice_type": "simples_nacional",
                "token": "eyJhbGciOiJIUzI1NiIs...",
                "cnpj": "12345678000199",
                "name": "Empresa Exemplo LTDA",
                "ie": "123456789",
                "unit": "matriz",
                "email": "contato@empresa.com",
                "cep": "01001000",
                "address": "Rua Exemplo",
                "house_number": "100",
                "town": "Centro",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://exemplo.com/cert.pfx",
                "cert_pwd": "***",
                "serie": 1,
                "number": 142
              }
            ],
            "page": 1,
            "total": 8,
            "total_pages": 1
          }
        }

GET/api/company/get_detail

获取公司详情

返回由 token 请求头标识的公司的完整数据，包括已注册的税务类别列表。不接受 body 或查询字符串。

必需请求头

请求头	类型	说明
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

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

GET /api/company/get_detail

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "name": "Empresa Exemplo LTDA",
            "token": "eyJhbGciOiJIUzI1NiIs...",
            "invoice_type": "simples_nacional",
            "cnpj": "12345678000199",
            "ie": "123456789",
            "unit": "matriz",
            "email": "contato@empresa.com",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://exemplo.com/cert.pfx",
            "cert_pwd": "***",
            "serie": 1,
            "number": 142,
            "categorys": [
              {
                "category_id": "cat_001",
                "descricao": "Venda de mercadoria",
                "disable_difal": false,
                "desconta_icms_pis_cofins": false
              }
            ]
          }
        }

GET/api/company/get_cep_detail

通过 CEP 查询地址

解析巴西 CEP（邮政编码），返回 UF、IBGE 自治市代码和地址数据。用于填写公司和客户地址。需要分销商（b2b）账户。

必需请求头

请求头	类型	说明
token	string	分销商令牌（b2b — 账户必须具有 `isb2b=true`）
sign	string	MD5 签名（path 包含查询字符串）
timestamp	string	秒级 Unix 时间戳

查询字符串

参数	类型	说明
cep *	string	巴西 CEP（8 位，可带或不带连字符）

* 必填字段。

GET/api/company/get_export_invoice_month_files

月度导出文件列表

返回当前年度（时区 America/Sao_Paulo）该公司已生成的每月导出文件列表。每个月最多可以有 4 个文件：1 个 Excel 电子表格（仅 Success 状态）+ 3 个 XML（按 Success、Canceled、Voided 状态各一个）。仅显示实际已导出的文件 — 使用 /api/invoice/get_xml 生成新文件。

必需请求头

请求头	类型	说明
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

响应

字段	类型	说明
files[]	array	可用文件列表
files[].url	string	OSS 上的文件 URL
files[].year	int	期间年份
files[].month	string	月份（1–12）
files[].type	string	文件类型：`"xlsx"` 或 `"xml"`
files[].status	string	文件中发票的状态：`"Success"`、`"Canceled"` 或 `"Voided"`
files[].create	datetime	文件生成时间

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

GET /api/company/get_export_invoice_month_files

        {
          "success": true,
          "data": {
            "files": [
              {
                "url": "https://oss.example.com/.../2024_01_success.xlsx",
                "year": 2024,
                "month": "1",
                "type": "xlsx",
                "status": "Success",
                "create": "2024-02-01T03:15:00Z"
              },
              {
                "url": "https://oss.example.com/.../2024_01_success.zip",
                "year": 2024,
                "month": "1",
                "type": "xml",
                "status": "Success",
                "create": "2024-02-01T03:15:30Z"
              }
            ]
          }
        }