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}/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ú）。TED 不接受 ISPB：8 位数值将以 `400 invalid_bank_code` 被拒绝。ISPB 仅适用于按银行账户发起的 PIX（`bankIspb`）
`branch`	string	是	目标分行（仅数字）
`account`	string	是	目标账号（仅数字，不含最后的校验位）
`accountType`	string	否	`CHECKING`（默认）、`SAVINGS`、`PAYMENT` 或 `SALARY`
`taxNumber`	string	是	收款人 CPF（11 位）或 CNPJ（14 位）
`holderName`	string	是	收款人法定全名
`description`	string	否	自由格式消息（例如发票号）
`identifier`	string	否	集成方关联键（最多 38 字符 `[A-Za-z0-9._-]`），会在 `ted.out.*` webhooks 中回传。与 `Idempotency-Key` 请求头不同。如果省略则自动生成

响应 (202 Accepted)

{
  "tedId": "ted-supplier-acme-2026-05",
  "workflowId": "ted-out-ted-supplier-acme-2026-05",
  "runId": "019e1234-...",
  "idempotencyKey": "ted-001",
  "identifier": "supplier-acme-2026-05",
  "status": "PROCESSING",
  "amount": 5000.00,
  "destination": {
    "bankCode": "001",
    "branch": "1234",
    "account": "56789",
    "accountType": "CHECKING",
    "taxNumber": "12345678900",
    "holderName": "JOAO DA SILVA"
  },
  "description": "Supplier payment Invoice 12345",
  "info": "TED é assíncrona — status final converge via webhook ou polling defensivo (48h max)."
}

tedId 是 CorpX 内部唯一标识（ted-{identifier}），用于查询状态并与 webhook 关联。

2. 查询状态

端点： GET /v1/accounts/{accountId}/ted/{tedId}

curl "https://tenant.api.corpx.com/v1/accounts/{accountId}/ted/ted-supplier-acme-2026-05" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany"

旧路径

之前的路径 GET /v1/accounts/{accountId}/transfers/ted/{tedId} 仍可使用（向后兼容），但自 v2.22.0 起已废弃，将在未来主版本中移除。请尽早迁移到 /ted/{tedId}。

响应 (200)

{
  "tedId": "ted-supplier-acme-2026-05",
  "accountId": "773107de-...",
  "status": "COMPLETED",
  "amount": 5000.00,
  "identifier": "supplier-acme-2026-05",
  "description": "Supplier payment Invoice 12345",
  "partnerId": "supplier-acme-2026-05",
  "createdAt": "2026-05-23T09:00:00Z",
  "updatedAt": "2026-05-23T09:32:15Z"
}

状态

状态	含义
`PROCESSING`	TED 已被结算银行接受；等待 BACEN 结算
`COMPLETED`	TED 在目标银行结算（终态）
`FAILED`	TED 被拒绝、过期或 48 小时超时（终态）

TED Webhooks

订阅 webhook 是跟踪 TED 的推荐方式 — 您可以实时获得通知，无需轮询。

可用事件

事件	何时
`ted.out.requested`	POST 被接受后立即触发（`PROCESSING` 状态）
`ted.out.confirmed`	结算银行确认结算（终态 — 成功）
`ted.out.failed`	结算被拒绝/过期或 48 小时超时（终态 — 失败）。若清算行提供原因，包含 `data.errorReason`。
`ted.in.received`	您的账户收到 TED（由第三方发起）。若清算行提供发起方信息，包含 `data.payer`。
`ted.payment`	已弃用 — `ted.out.confirmed` 的别名。将在 v3.0 中移除

所有事件都使用规范的 webhook 信封（id、type、occurredAt、 schemaVersion、environment、tenantId、accountId、data）——与 PIX、 boleto 和内部转账一致。参见 Webhooks。

`ted.out.requested` 负载

{
  "id": "ted-ted-supplier-acme-2026-05-requested",
  "type": "ted.out.requested",
  "occurredAt": "2026-05-23T09:00:00.123456789Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "tedId": "ted-supplier-acme-2026-05",
    "tenantId": "tenant-yourcompany",
    "accountId": "773107de-...",
    "identifier": "supplier-acme-2026-05",
    "partnerId": "",
    "amount": 5000.00,
    "destination": {
      "bankCode": "001",
      "branch": "1234",
      "account": "56789",
      "accountType": "CHECKING",
      "taxNumber": "12345678900",
      "holderName": "JOAO DA SILVA"
    },
    "description": "Supplier payment Invoice 12345"
  }
}

`ted.out.confirmed` 负载

{
  "id": "ted-ted-supplier-acme-2026-05-confirmed",
  "type": "ted.out.confirmed",
  "occurredAt": "2026-05-23T09:32:15.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "tedId": "ted-supplier-acme-2026-05",
    "tenantId": "tenant-yourcompany",
    "accountId": "773107de-...",
    "identifier": "supplier-acme-2026-05",
    "partnerId": "supplier-acme-2026-05",
    "amount": 5000.00,
    "destination": { "bankCode": "001", "branch": "1234", "account": "56789", "accountType": "CHECKING", "taxNumber": "12345678900", "holderName": "JOAO DA SILVA" },
    "description": "Supplier payment Invoice 12345"
  }
}

`ted.out.failed` 负载

{
  "id": "ted-ted-supplier-acme-2026-05-failed",
  "type": "ted.out.failed",
  "occurredAt": "2026-05-23T09:32:15.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "tedId": "ted-supplier-acme-2026-05",
    "tenantId": "tenant-yourcompany",
    "accountId": "773107de-...",
    "identifier": "supplier-acme-2026-05",
    "partnerId": "supplier-acme-2026-05",
    "amount": 5000.00,
    "destination": { "bankCode": "001", "branch": "1234", "account": "56789", "accountType": "CHECKING", "taxNumber": "12345678900", "holderName": "JOAO DA SILVA" },
    "description": "Supplier payment Invoice 12345",
    "errorCode": "invalid_bank_code",
    "errorReason": "banco destino não existe no SPB",
    "error": "banco destino não existe no SPB"
  }
}

（API 返回的清算行原因为葡萄牙语；上例的含义是"目标银行在 SPB 中不存在"。）

`ted.in.received` 负载

{
  "id": "ted-in-abc123def",
  "type": "ted.in.received",
  "occurredAt": "2026-05-23T14:15:22.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "transactionId": "abc123def",
    "identifier": "TED-MT-9876",
    "partnerTxId": "abc123def",
    "accountId": "773107de-...",
    "tenantId": "tenant-yourcompany",
    "amount": 1200.00,
    "description": "Payment received",
    "receivedAt": "2026-05-23T14:15:22Z",
    "payer": {
      "name": "EMPRESA XYZ LTDA",
      "document": "98765432000110",
      "bankCode": "237",
      "bankIspb": "60746948",
      "branch": "0001",
      "account": "123456",
      "accountNumber": "123456"
    }
  }
}

去重

每个 webhook 都有唯一且确定的 id（例如 ted-{tedId}-confirmed）。请在您的系统中用 id 做去重，以应对重复投递（当您的端点迟迟未返回 2xx 时，我们的分发器会重试）。旧别名 ted.payment 复用相同的负载，但有自己的 id（ted-{tedId}-payment）——请通过 type 区分，以免丢弃规范事件。

常见错误

HTTP 代码	`errorCode`	何时
400	`invalid_bank_code`	`bankCode` 不是有效的 3 位 Compe 代码 — 包括发送 8 位 ISPB 的情况，TED 不接受 ISPB
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` 缺失
400	`invalid_identifier`	`identifier` 含非 ASCII 字符或长度无效
400	`invalid_field`	`description` 或 `holderName` 不符合清算行接受的格式
400	`invalid_payload`	JSON 请求体格式错误
403	`forbidden`	用户在账户的租户上没有角色
503	`temporal_unavailable`	内部编排器不可用（罕见；请等待重试）
503	`partner_unavailable`	结算银行不可用
404	`not_found`	GET 状态调用中未找到 `tedId`

工作流中的错误（终态 `FAILED`）

`errorReason`	何时
`insufficient_funds`	源账户余额不足
`invalid_bank_code`	目标银行在 SPB 中不存在
`outside_banking_hours`	在清算行接受的时段之外发起 TED
`bank_unreachable`	目标银行的临时性错误
`limit_exceeded`	达到运营限额
`timeout aguardando confirmação do parceiro (>48h)`	防御性轮询到期仍未结算（葡萄牙语原文，含义为"等待合作方确认超时（>48 小时）"）

对账

CorpX 在发送 TED 后每分钟运行防御性轮询，最多 48 小时，即使结算银行的 webhook 正常到达。这保证了内部状态与银行真实状态始终一致。

您方对账方式：

实时： 订阅 ted.out.{requested,confirmed,failed} 和 ted.in.received webhook
点查询： GET /v1/accounts/{accountId}/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 — 负载相同

概述​

什么时候用 TED 而不是 PIX？​

结算银行 MT Bank（接收 TED）​

时段和时效​

服务器端防御性轮询​

费用和限额​

1. 发送 TED​

字段​

响应 (202 Accepted)​

2. 查询状态​

响应 (200)​

状态​

TED Webhooks​

可用事件​

ted.out.requested 负载​

ted.out.confirmed 负载​

ted.out.failed 负载​

ted.in.received 负载​

去重​

常见错误​

工作流中的错误（终态 FAILED）​

对账​

ted.payment 弃用​

概述