TF FISCAL - 巴西发票API

基础URL: https://api.tffiscal.com

TF FISCAL API允许与巴西电子发票(NF-e)系统集成。目前支持在巴西全国范围内为产品开具发票。

系统流程

输入数据

客户信息(购买者)
产品信息
税务信息
运输信息

处理

数据验证
税务计算
NF-e XML生成
SEFAZ授权

输出

发票XML
发票PDF
DANFE(辅助文件)
授权状态

身份验证

所有请求必须包含以下头部信息:

参数	类型	必需	描述
Content-Type	string	是	application/json;charset=utf-8
sign	string	是	请求的数字签名
timestamp	string	是	请求的UTC时间戳
token	string	是	身份验证令牌

注意: 创建公司和获取公司列表时，请使用分销商令牌(b2b_token)。

签名算法 (SIGN)

static string GetSign(string AppKey, string Path, string bodyString, string timestamp)
{
    string input = AppKey + Path + bodyString + timestamp;
    using (MD5 md5 = MD5.Create())
    {
        byte[] inputBytes = Encoding.UTF8.GetBytes(input);
        byte[] hashBytes = md5.ComputeHash(inputBytes);
        
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < hashBytes.Length; i++)
        {
            sb.Append(hashBytes[i].ToString("x2"));
        }
        return sb.ToString();
    }
}

可用端点

端点	方法	功能
`/api/company/create`	POST	创建公司
`/api/company/get_detail`	GET	查询公司
`/api/company/edit`	POST	编辑公司
`/api/company/get_list`	GET	列出公司
`/api/category/get_list`	GET	列出类别
`/api/invoice/create`	POST	创建发票
`/api/invoice/get_list`	GET	列出发票
`/api/invoice/get_detail`	GET	查询发票
`/api/invoice/refresh`	POST	更新发票状态
`/api/invoice/cancel`	POST	取消发票
`/api/invoice/invalid`	POST	作废发票

税务参数

税务参数对于操作的正确税收分类至关重要。

ICMS参数

11.1 税收情景

padrao 标准(适用于所有情景，ICMS除外)

saida_fora_estado 州外销售(州际)

saida_dentro_estado 州内销售(州内)

entrada_fora_estado 从州外购买

entrada_dentro_estado 州内购买

11.2 税收状况

值	描述
00	有信贷回收的进项
01	零税率进项
02	免税进项
03	非应税进项
04	豁免进项
05	暂停进项
49	其他进项
01	应税操作 - 计税基础 = 操作价值正常税率
02	应税操作 - 计税基础 = 操作价值 (差异化税率)
03	应税操作 - 计税基础 = 销售数量 X 每产品单位税率
04	应税操作 - 单一阶段税收 - (零税率)
05	应税操作 - (税收替代)
06	应税操作 (零税率)
07	贡献免税操作

11.3 人员类型

fisica 个人

juridica 法人实体

PIS/COFINS参数

12.1 税收情景

padrao 标准(适用于所有情景)

saida_fora_estado 州外销售

saida_dentro_estado 州内销售

entrada_fora_estado 从州外购买

entrada_dentro_estado 州内购买

12.2 税收状况 - PIS/COFINS

值	描述
71	豁免获取操作
72	暂停获取操作
73	零税率获取操作
74	无贡献发生的获取操作
75	通过税收替代获取操作
98	其他进项操作
99	其他操作

12.3 人员类型

fisica 个人

juridica 法人实体

支付参数

发票支付方式和卡片信息的配置。

13. 支付指示器

值	描述
0	现金
1	分期付款

14. 支付方式

值	描述
01	现金
02	支票
03	信用卡
04	借记卡
05	商店卡
10	食品券
11	餐饮券
12	礼品券

15. 卡片信息

注意: 仅在payment_method为03(信用卡)或04(借记卡)时填写。

15.1 集成类型

值	描述	说明
1	与公司自动化系统集成的支付	如TEF或集成支付网关
2	与公司自动化系统未集成的支付	独立POS，无自动同步

15.2 品牌代码

值	品牌
01	Visa
02	Mastercard
03	American Express
04	Sorocred
05	Diners Club
06	Elo
07	Hipercard
08	Aura
09	Cabal
10	Alelo
11	Banes Card
12	CalCard
13	Credz
14	Discover
15	GoodCard
16	GreenCard
17	Hiper
18	JCB
19	Mais
20	MaxVan
21	Policard
22	RedeCompras
23	Sodexo
24	ValeCard
25	Vercoheque
26	VR
27	Ticket
99	其他

XML故障排除

拒绝225 - XML模式失败

情景: 当您尝试取消、下载XML、无效化号码或对未在SEFAZ数据库中成功注册的NF-e进行收件人声明时。

1

检查NF-e状态

使用状态查询功能确认NF-e是否已成功授权(状态"已授权")。

2

重新签发NF-e

如果未授权，请尝试重新签发NF-e(重新进行签发)。

3

无效化号码

如果发票号码未使用且后续发票已授权，请考虑无效化发票号码。

如何识别具体错误

当错误为"模式失败"时，意味着XML中的某些信息不符合SEFAZ有效布局。在红色指示的路径中，它将始终指示哪个XML标签无效。

错误示例

模式和业务规则验证结果:
- XML意见: 未发现错误
- 消息类型: NF-e文档
- XML模式: The http://www.portalfiscal.inf.br/nfe element is invalid
  The value '$86.300' is invalid according to its datatype 'String'
  The Pattern constraint failed
  路径: NF-e[1]/infNFe[1]/det[1]/prod[1]/NCM

验证工具

SEFAZ在线验证

使用SEFAZ官方验证器识别XML问题:

URL: https://www.sefaz.rs.gov.br/nfe/nfe-val.aspx

1

复制XML内容

访问系统并复制所有XML文件内容。

2

粘贴到验证器

将XML内容粘贴到验证器的适当字段中。

3

分析结果

检查验证器指出的具体错误。

常见问题

收件人地址不完整 或包含异常数据(特殊符号)
产品税务信息不正确 (无效NCM，错误的税收分类)
数值格式不正确 (点号, 逗号, 小数位)
缺少必填字段

证书信息

证书剩余天数

监控数字证书的有效性至关重要。过期的证书会导致NF-e被拒绝。

建议

至少在到期前30天更新证书
将证书和密码备份保存在安全的地方
在当前证书到期前测试新证书
配置证书到期提醒

有效性验证

验证证书剩余天数:

Windows

1. 打开Internet Explorer
2. 转到工具 → Internet选项 → 内容 → 证书
3. 选择您的证书并点击"查看"
4. 在"常规"选项卡中检查有效期

选择语言