REST API v2.5 系统运行正常

REST API 文档

欢迎来到TF API文档中心。在这里您可以找到完整的API参考，包括 TF ERP、TF商店、TF通信、TF软件 和其他集团解决方案。查阅端点、HTTP方法、认证参数和单一通道的完全互连。

account_balance

TF 财务API

巴西电子发票 (NF-e)

用于巴西电子发票 (NF-e) 的签发、查询和取消的完整API。支持自动税务计算（ICMS、IPI、PIS/COFINS）、XML生成、SEFAZ授权以及与管理系统的集成。目前支持为整个巴西领土的产品开具发票。

基础URL (生产环境)

https://api.tffiscal.com/v1

认证

Headers: sign, timestamp, token

要求

有效的A1数字证书

sync_alt 系统流程

input 输入数据

客户信息
产品数据
财务信息
运输数据

settings 处理

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

download 输出

发票XML
发票PDF
DANFE（辅助文件）
授权状态

主要端点

POST /api/company/create

创建新公司

使用分销商令牌 (b2b_token) 创建公司。

GET /api/company/get_list

列出所有公司

返回已注册公司的分页列表。

GET /api/company/get_detail

查询公司详情

参数 (查询)

字段	类型	描述
company_id	string	公司唯一ID

GET /api/category/get_list

列出产品类别

返回所有可用于财务分类的类别。

POST /api/invoice/create

签发新发票

主要载荷

{
  "company_id": "comp_123456",
  "customer": {
    "document": "123.456.789-09",
    "name": "示例客户",
    "address": {...}
  },
  "products": [
    {
      "code": "PROD001",
      "description": "示例产品",
      "quantity": 2,
      "unit_price": 150.00,
      "ncm": "85176277"
    }
  ],
  "tax_parameters": {...},
  "payment_parameters": {...}
}

GET /api/invoice/get_list

列出发票

参数 (查询)

字段	类型	描述
start_date	date	开始日期 (YYYY-MM-DD)
end_date	date	结束日期 (YYYY-MM-DD)
status	string	按状态筛选

GET /api/invoice/get_detail

查询发票详情

参数 (查询)

字段	类型	描述
invoice_id	string	发票唯一ID

响应示例

{
  "invoice_id": "nf_789012",
  "access_key": "35210112345678901234567890123456789012345678",
  "status": "AUTHORIZED",
  "issue_date": "2024-01-10T10:30:00Z",
  "xml_url": "https://storage.tffiscal.com/xml/nf_789012.xml",
  "pdf_url": "https://storage.tffiscal.com/pdf/nf_789012.pdf"
}

POST /api/invoice/refresh

更新发票状态

在SEFAZ查询当前状态并本地更新。

POST /api/invoice/cancel

取消发票

请求载荷

{
  "invoice_id": "nf_789012",
  "reason": "订单错误"
}

POST /api/invoice/invalid

使发票无效

用于处理错误或重复的发票。

vpn_key 认证

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

头部	类型	必需	描述
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();
    }
}

percent 税务参数

scale_balance ICMS参数

税收场景

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado

税收状况

00: 有信用回收的输入

01: 零税率的输入

02: 免税输入

49: 其他输入

pie_chart PIS/COFINS参数

税收场景

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado

税收状况

71: 免税的采购操作

72: 暂停的采购操作

73: 零税率的采购操作

98: 其他输入操作

credit_card 支付参数

支付指示器

`0`	现金
`1`	分期付款

支付方式

`01`	现金
`03`	信用卡
`04`	借记卡

卡品牌

`01`	Visa
`02`	Mastercard
`06`	Elo

bug_report XML问题解决

warning 拒绝 225 - XML模式失败

当尝试取消、下载XML、使号码无效或对未在SEFAZ数据库中成功注册的NF-e进行声明时发生。

验证NF-e是否已授权（状态为"已授权"）

如果未授权，重新签发NF-e

如果未使用，使号码无效

lightbulb SEFAZ在线验证

使用官方验证器识别XML中的问题：


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

常见问题： 地址不完整，NCM无效，数值格式不正确，必填字段缺失。

business_center

TF ERP API

企业资源计划

集成财务、会计和管理模块。TF ERP API允许主数据同步、会计记录和集中现金流管理。

基础URL (生产环境)

https://api.tferp.com/v3

认证

OAuth2 Bearer Token

GET /financial/cash-flow

查询现金流

参数 (查询)

字段	类型	描述
start_date	date	期间开始
end_date	date	期间结束

响应示例

{
  "balance": 150000.00,
  "entries": [
    { "date": "2023-11-01", "amount": 5000.00, "type": "credit" },
    { "date": "2023-11-02", "amount": -1200.00, "type": "debit" }
  ]
}

payments

TF 支付API

支付处理和金融交易

通过多种方法（信用卡、PIX、票据、转账）处理支付，并安全地管理金融交易。TF Pay API提供完全支持授权、捕获、退款和与TF生态系统自动对账。

基础URL (生产环境)

https://api.tfpay.com/v2

认证

JWT Bearer Token

主要端点

POST /payments/create

创建新的支付交易

需要具有 payments:write 范围的JWT认证。

请求载荷

JSON

{
  "order_id": "ord_8x92nm",
  "amount": 299.90,
  "currency": "BRL",
  "payment_method": "credit_card",
  "card": {
    "number": "4111111111111111",
    "exp_month": "12",
    "exp_year": "2025",
    "cvc": "123",
    "holder_name": "张三"
  },
  "customer": {
    "id": "cus_99aa88",
    "email": "[email protected]"
  }
}

响应示例

JSON

{
  "payment_id": "pay_7d9f2a1b",
  "status": "authorized",
  "authorization_code": "AUTH123456",
  "amount": 299.90,
  "currency": "BRL",
  "created_at": "2023-11-01T10:30:00Z"
}

GET /payments/{payment_id}

查询支付状态

参数 (路径)

字段	类型	描述
payment_id	string	支付唯一ID

响应示例

{
  "payment_id": "pay_7d9f2a1b",
  "order_id": "ord_8x92nm",
  "status": "captured",
  "amount": 299.90,
  "currency": "BRL",
  "payment_method": "credit_card",
  "card_last_four": "1111",
  "created_at": "2023-11-01T10:30:00Z",
  "captured_at": "2023-11-01T10:31:00Z",
  "customer": {
    "id": "cus_99aa88",
    "email": "[email protected]"
  }
}

POST /payments/{payment_id}/refund

退款支付

需要具有 payments:refund 范围的JWT认证。

Payload JSON

{
  "amount": 299.90,
  "reason": "devolucao_do_produto"
}

状态响应: 200 OK 400 Bad Request

GET /transactions

按期间列出交易

参数 (查询)

字段	类型	描述
start_date	date	开始日期 (YYYY-MM-DD)
end_date	date	结束日期 (YYYY-MM-DD)
status	string	按状态筛选

响应示例

{
  "data": [
    {
      "payment_id": "pay_7d9f2a1b",
      "order_id": "ord_8x92nm",
      "amount": 299.90,
      "status": "captured",
      "payment_method": "credit_card",
      "created_at": "2023-11-01T10:30:00Z"
    }
  ],
  "summary": {
    "total_amount": 299.90,
    "total_transactions": 1,
    "successful": 1,
    "failed": 0
  }
}

storefront

TF 商店API

电子商务和数字店面

管理目录，实时控制库存并安全处理订单。TF商店API是生态系统零售运营的核心。

基础URL (生产环境)

https://api.tfloja.com/v1

限制 (频率限制)

1000 请求/分钟 (标准)

主要端点

GET /products

列出目录产品

参数 (查询)

字段	类型	描述
page	int	分页
category	string	类别ID筛选

响应示例

{
  "data": [
    {
      "id": "prod_8x92nm",
      "name": "TF智能手表",
      "price": 299.90,
      "stock": 45
    }
  ]
}

POST /orders

创建新订单

需要具有 orders:write 范围的OAuth2认证。

Payload JSON

{
  "customer_id": "cus_99aa88",
  "items": [
    { "product_id": "prod_8x92nm", "quantity": 1 }
  ],
  "payment_method": "credit_card"
}

chat_bubble

TF 通信API

通信和聊天机器人

统一的通信平台。通过WhatsApp、SMS或电子邮件发送消息，并将智能聊天机器人集成到您的客户服务中。

基础URL

https://api.tftalk.com/v2

Webhooks

支持 (签名验证)

POST /messages/send

发送消息

请求载荷

{
  "channel": "whatsapp",
  "recipient": "+5511999998888",
  "content": {
    "type": "text",
    "body": "您好！您的订单已确认。"
  }
}

响应 (200 OK)

{
  "message_id": "msg_9921828",
  "status": "queued"
}

local_shipping

TF OMS API

订单管理系统

完整的订单管理系统。编排来自多个渠道（全渠道）的订单，管理物流和逆向物流。

基础URL

https://api.tfoms.com/v1

头部信息

X-Tenant-ID 必需

PUT /orders/{id}/status

更新订单状态

更新履行流程中特定订单的处理状态。

参数 (路径)

string

订单UUID

请求载荷

{
  "status": "shipped",
  "tracking_code": "BR123456789TR",
  "carrier": "Correios"
}

dns

TF 软件API

SaaS管理和许可

专用于集团SaaS产品软件许可管理、版本控制和更新分发的API。

基础URL

https://api.tfsoftwares.com/v2

认证

API密钥 (头部: X-TF-Key)

POST /licenses/verify

验证许可证有效性

必需头部信息

Content-Type application/json
X-TF-Key sua_api_key

请求载荷

{
  "license_key": "XXXX-YYYY-ZZZZ",
  "machine_id": "hw_82738273",
  "product_code": "tf_crm_v1"
}

storefront

TF 商城API

电子商务和订单管理

专用于虚拟商店管理、订单、支付和产品的API。允许创建订单、查询购买状态以及将外部系统集成到TF商城生态系统。

基础URL

https://api.tfshop.com/v1

认证

API密钥 (头部: X-TF-Key)

POST /orders/create

创建新订单

必需头部信息

Content-Type application/json
X-TF-Key sua_api_key

请求载荷

{
  "customer_id": "cus_392018",
  "items": [
    {
      "product_id": "prd_001",
      "quantity": 2
    }
  ],
  "payment_method": "card",
  "currency": "AOA"
}

warehouse

TF WMS API

仓库和库存管理

专注于仓库管理和库存控制的API。允许登记产品出入库、实时跟踪库存以及查询详细的物流报告。

基础URL

https://api.tfwms.com/v1

沙箱环境

https://sandbox.api.tfwms.com/v1

POST /inventory/entries

登记产品入库

状态响应: 201 Created 400 Bad Request

{
  "message": "产品入库登记成功。",
  "entry_id": "ent_98451234",
  "warehouse_id": "wh_0021",
  "created_at": "2025-01-12T10:45:00Z"
}