TED 指南
本指南介绍如何通过 CorpX API 发送和接收 TED（Transferência Eletrônica Disponível，巴西银行间转账）。TED 是 BACEN（巴西央行）的银行间转账方式，在特定时段运行，本质上是异步的 — 不同于 PIX（即时）和内部转账（同行）。
概述
TED 是通过 SPB（巴西支付系统）处理的银行间转账，工作日 06:30–17:00 为发送窗口，窗口内发送当日完成结算。
| 特性 | PIX | TED | 内部转账 |
|---|---|---|---|
| 时段 | 24/7 | 工作日 06:30–17:00 | 24/7 |
| 结算 | 即时（少于10秒） | 发送后约30分钟 | 即时 |
| 银行 | 任意（PIX 网络） | 任意（SPB 网络） | 同一银行 |
| 费用 | 可变 | 可变（高于 PIX） | 通常免费 |
| 最低金额 | R$ 0.01 | R$ 0.01 | R$ 0.01 |
| 最高金额 | 可配置 | 无 BACEN 上限 | 可配置 |
什么时候用 TED 而不是 PIX？
- 大额转账，超过账户配置的 PIX 限额
- 遗留系统仍然要求 TED
- 对手方只接受 TED（例如某些公共合约）
- 某些 ERP 中的银行间票据或公司发薪单
对于日常（快速付款，少于 R$ 1MM，在/外营业时间），PIX 始终是首选 — 即时、24/7、通常更便宜。
结算银行 MT Bank（接收 TED）
当有人想向您发送 TED 时，请通知对方使用以下信息：
| 字段 | 值 |
|---|---|
| 银行 | MT Instituição de Pagamentos S.A. |
| Compe 代码 | 681 |
| ISPB | 50871921 |
| 账户类型 | 支付账户（通知对方） |
| 分行 | （您在 MT 的分行） |
| 账号 | （您在 MT 的账号） |
| 持有人 CPF/CNPJ | （账户持有人的证件号） |
代码 681 是对方在他们的应用/网银的"银行"字段中输入的内容。不要与 ISPB（8 位）混淆 — 银行要求的是 3 位的 Compe 代码。
当 TED 到达您的账户时，您会收到 ted.in.received webhook（参见 Webhooks）。
时段和时效
TED 遵循 BACEN 时段 — 时段外的交易会安排到下一个工作日。
| 时段 | 行为 |
|---|---|
| 工作日 06:30–17:00 | 窗口内发送的 TED 同一工作日结算（成功发送后约 30 分钟） |
| 工作日 17:00–17:30 | 银行直接互换窗口 — 不适用于通过 PSP/MT 的客户（拒绝） |
| 工作日 17:30 之后 | 安排到 D+1 工作日。状态在我们这边保持 PROCESSING 直到结算 |
| 周末/节假日 | 安排到下一个工作日。防御性轮询继续最多 48 小时 |
服务器端防御性轮询
为确保即使结算银行的 webhook 失败也不会有 TED 被"卡住"，TEDOut.Workflow 每1 分钟轮询 MT 流水，最多 48 小时。如果该期间内 TED 没有结算，则标记为 FAILED（超时）。您始终可以通过 GET /v1/accounts/{accountId}/transfers/ted/{tedId} 或 ted.out.failed webhook 获取最终一致状态。
费用和限额
- TED OUT（发送）： 每笔操作固定费用 — 在 Backoffice → 流水 中使用
operation=FEE筛选（GET /v1/accounts/{accountId}/statement?operation=FEE） - TED IN（接收）： 接收费用（适用时）
- 最低： R$ 0.01
- 最高： 无 BACEN 上限；CorpX 允许账户的运营限额（通过 Policies 可配置）
具体费率因合同而异 — 请查看您的商业协议。
1. 发送 TED
端点： POST /v1/accounts/{accountId}/ted/out
curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/ted/out" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-yourcompany" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ted-001" \
-d '{
"value": 5000.00,
"bankCode": "001",
"branch": "1234",
"account": "56789",
"accountType": "CHECKING",
"taxNumber": "12345678900",
"holderName": "JOAO DA SILVA",
"description": "Supplier payment Invoice 12345",
"identifier": "supplier-acme-2026-05"
}'
字段
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
value | number | 是 | 金额（BRL，正数，最多 2 位小数） |
bankCode | string | 是 | 目标银行 Compe 代码（3 位，例如 001 巴西银行、237 Bradesco、341 Itaú）。也接受 8 位 ISPB |
branch | string | 是 | 目标分行（仅数字） |
account | string | 是 | 目标账号（仅数字，不含最后的校验位） |
accountType | string | 否 | CHECKING（默认）、SAVINGS、PAYMENT 或 SALARY |
taxNumber | string | 是 | 收款人 CPF（11 位）或 CNPJ（14 位） |
holderName | string | 是 | 收款人法定全名 |
description | string | 否 | 自由格式消息（例如发票号） |
identifier | string | 否 | 集成方关联键。如果省略则自动生成 |
响应 (202 Accepted)
参见英文版示例，相同格式。
2. 查询状态
端点： GET /v1/accounts/{accountId}/transfers/ted/{tedId}
状态
| 状态 | 含义 |
|---|---|
PROCESSING | TED 已被结算银行接受；等待 BACEN 结算 |
COMPLETED | TED 在目标银行结算（终态） |
FAILED | TED 被拒绝、过期或 48 小时超时（终态） |
TED Webhooks
订阅 webhook 是跟踪 TED 的推荐方式 — 您可以实时获得通知，无需轮询。
可用事件
| 事件 | 何时 |
|---|---|
ted.out.requested | POST 被接受后立即触发（PROCESSING 状态） |
ted.out.confirmed | 结算银行确认结算（终态 — 成功） |
ted.out.failed | 结算被拒绝/过期或 48 小时超时（终态 — 失败） |
ted.in.received | 您的账户收到 TED（由第三方发起） |
ted.payment | 已弃用 — ted.out.confirmed 的别名。将在 v3.0 中移除 |
负载示例
完整的 webhook 负载示例参见英文版指南。
常见错误
| HTTP 代码 | errorCode | 何时 |
|---|---|---|
| 400 | invalid_bank_code | bankCode 不是有效的 Compe（3 位）或 ISPB（8 位） |
| 400 | invalid_tax_number | taxNumber 既不是 11 位（CPF）也不是 14 位（CNPJ） |
| 400 | invalid_account_type | accountType 不在 CHECKING|SAVINGS|PAYMENT|SALARY 中 |
| 400 | missing_fields | value、branch、account、holderName 或 taxNumber 缺失 |
| 403 | forbidden | 用户在账户的租户上没有角色 |
| 503 | temporal_unavailable | 内部编排器不可用（罕见；请等待重试） |
| 503 | partner_unavailable | 结算银行不可用 |
| 404 | not_found | GET 状态调用中未找到 tedId |
对账
CorpX 在发送 TED 后每分钟运行防御性轮询，最多 48 小时，即使结算银行的 webhook 正常到达。这保证了内部状态与银行真实状态始终一致。
您方对账方式：
- 实时： 订阅
ted.out.{requested,confirmed,failed}和ted.in.receivedwebhook - 点查询：
GET /v1/accounts/{accountId}/transfers/ted/{tedId} - 流水：
GET /v1/accounts/{accountId}/statement（TED 出现时operation=TED） - 详细时间线：
GET /v1/accounts/{accountId}/transactions/timeline?tedId={tedId}
ted.payment 弃用
ted.payment 事件（v1 遗留目录）保留作为 ted.out.confirmed 的别名以保持兼容性。两者在同一终态一起发送。
- 新集成方： 订阅
ted.out.confirmed（更具描述性，与boleto.paid、pix.out.completed对齐） - 遗留集成方： 可保留
ted.payment直到 v3.0（日期待定） - 迁移： 取消订阅
ted.payment+ 订阅ted.out.confirmed— 负载相同