> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Guia de TED

Este guia explica como enviar e receber TED (Transferência Eletrônica Disponível) através da CorpX API. TED é uma modalidade de transferência interbancária do BACEN que opera em janela específica e é **assíncrona por design** — diferente do PIX (instantâneo) e da transferência interna (mesmo banco).

## Visão Geral

**TED** é uma transferência entre bancos diferentes processada pelo SPB (Sistema de Pagamentos Brasileiro), com janela de envio em dias úteis (06:30–17:00) e liquidação no mesmo dia útil quando enviada dentro da janela.

| Característica | PIX                        | TED                        | Internal Transfer |
| -------------- | -------------------------- | -------------------------- | ----------------- |
| Janela         | 24/7                       | Dias úteis 06:30–17:00     | 24/7              |
| Liquidação     | Instantânea (menos de 10s) | \~30min após envio         | Instantânea       |
| Bancos         | Qualquer (rede PIX)        | Qualquer (rede SPB)        | Mesmo banco       |
| Custo          | Variável                   | Variável (maior que PIX)   | Tipicamente zero  |
| Limite mínimo  | R\$ 0,01                   | R\$ 0,01                   | R\$ 0,01          |
| Limite máximo  | Configurável               | R\$ 14.999,99 por operação | Configurável      |

### Quando usar TED em vez de PIX?

* **Compatibilidade bancária** quando a contraparte exige a rede SPB
* **Compatibilidade** com sistemas legados que ainda exigem TED
* **Contraparte** que aceita apenas TED (ex.: alguns convênios públicos)
* **Boleto interbancário** ou folha de pagamento corporativa em alguns ERPs

Para o dia-a-dia (pagamentos rápidos, menores que R\$ 1MM, dentro/fora de horário comercial), **PIX é sempre preferível** — instantâneo, 24/7, tipicamente mais barato.

## Banco liquidante (para receber TED)

Quando alguém quiser enviar TED **para você**, instrua a contraparte a usar os dados abaixo:

| Campo               | Valor                                      |
| ------------------- | ------------------------------------------ |
| Banco               | **banco liquidante**                       |
| Código Compe        | **681**                                    |
| ISPB                | **50871921**                               |
| Tipo de conta       | Conta de pagamento (informe à contraparte) |
| Agência             | (a agência da sua conta)                   |
| Número da conta     | (o número da sua conta)                    |
| CPF/CNPJ do titular | (o documento titular da conta)             |

> O código **681** é o que a contraparte vai digitar no campo "Banco" do app/internet banking dela. Não confunda com o ISPB (8 dígitos) — bancos pedem o **3 dígitos do código Compe**.

Quando uma TED chega na sua conta, você recebe o webhook **`ted.in.received`** (ver [Webhooks](#webhooks-ted)).

## Janela e tempos

A TED segue a janela do BACEN — fora dela, a transação fica **agendada** para o próximo dia útil.

| Janela                               | Comportamento                                                                            |
| ------------------------------------ | ---------------------------------------------------------------------------------------- |
| **Dias úteis, 06:30–17:00**          | TED enviada dentro da janela liquida no mesmo dia útil (\~30min após envio bem-sucedido) |
| **Dias úteis, 17:00–17:30**          | Janela interbancária direta — **não vale para contas deste liquidante** (rejeitada)      |
| **Após 17:30 em dia útil**           | Agendada para D+1 útil. Status fica `PROCESSING` no nosso lado até liquidar              |
| **Fim de semana / feriado nacional** | Agendada para o próximo dia útil. Polling defensivo continua até 48h                     |

### Polling defensivo do servidor

Para garantir que nenhuma TED fique "presa" mesmo se o webhook do liquidante falhar, a API consulta o extrato do liquidante a cada **1 minuto por até 48 horas**. Se nesse período a TED não aparece como liquidada, é marcada como `FAILED` (timeout). Você sempre tem o estado final consistente via `GET /v1/accounts/{accountId}/ted/{tedId}` ou via webhook `ted.out.failed`.

## Custos e limites

* **TED OUT (enviar):** tarifa fixa por operação — consulte no Backoffice → Extrato com filtro `operation=FEE` (`GET /v1/accounts/{accountId}/statement?operation=FEE`)
* **TED IN (receber):** tarifa de recepção quando aplicável
* **Mínimo:** R\$ 0,01
* **Máximo por operação:** R\$ 14.999,99. Um teto menor da conta em `ted_out` continua prevalecendo ([guia de limites](/baas/guias/pagar/limites))

> Tarifas exatas variam por contrato — consulte o seu acordo comercial.

## 1. Enviar TED

**Endpoint:** `POST /v1/accounts/{accountId}/ted/out`

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/ted/out" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -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": "Pagamento de fornecedor NF 12345",
    "identifier": "fornecedor-acme-2026-05"
  }'
```

### Campos

| Campo         | Tipo   | Obrigatório | Descrição                                                                                                                                                                                                                                                                                           |
| ------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`       | number | Sim         | Valor em reais (positivo, máx. 2 casas decimais)                                                                                                                                                                                                                                                    |
| `bankCode`    | string | Sim         | Código Compe do banco destino — **3 dígitos** (ex.: `001` Banco do Brasil, `237` Bradesco, `341` Itaú). TED **não aceita ISPB**: um valor de 8 dígitos é recusado com `400 invalid_bank_code`. O par COMPE/ISPB está em [Catálogo de bancos](/baas/guias/apis-adicionais/bancos) (`GET /v1/banks`). |
| `branch`      | string | Sim         | Agência destino (só dígitos)                                                                                                                                                                                                                                                                        |
| `account`     | string | Sim         | Conta destino (só dígitos, sem o dígito verificador final)                                                                                                                                                                                                                                          |
| `accountType` | string | Não         | `CHECKING` (default), `SAVINGS`, `PAYMENT` ou `SALARY`                                                                                                                                                                                                                                              |
| `taxNumber`   | string | Sim         | CPF (11 dígitos) ou CNPJ (14 dígitos) do titular destinatário                                                                                                                                                                                                                                       |
| `holderName`  | string | Sim         | Nome completo do titular destinatário                                                                                                                                                                                                                                                               |
| `description` | string | Não         | Mensagem livre (ex.: número da NF)                                                                                                                                                                                                                                                                  |
| `identifier`  | string | Não         | Chave de correlação do integrador (máx. 38 chars `[A-Za-z0-9._-]`), ecoada nos webhooks `ted.out.*`. Diferente do header `Idempotency-Key`. Gerado automaticamente se omitido                                                                                                                       |

### Resposta (202 Accepted)

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

O `tedId` é único da CorpX (`ted-{identifier}`) e é a chave para consultar status e correlacionar com webhooks.

## 2. Consultar status

**Endpoint:** `GET /v1/accounts/{accountId}/ted/{tedId}`

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

> **Caminho legado**
>
> O caminho anterior `GET /v1/accounts/{accountId}/transfers/ted/{tedId}` continua funcionando
> por retrocompatibilidade, mas está **deprecated** desde a v2.22.0 e será removido em uma próxima
> major. Migre para `/ted/{tedId}` quando puder.

### Resposta (200)

```json
{
  "tedId": "ted-fornecedor-acme-2026-05",
  "accountId": "773107de-...",
  "status": "COMPLETED",
  "amount": 5000.00,
  "identifier": "fornecedor-acme-2026-05",
  "description": "Pagamento de fornecedor NF 12345",
  "partnerId": "fornecedor-acme-2026-05",
  "createdAt": "2026-05-23T09:00:00Z",
  "updatedAt": "2026-05-23T09:32:15Z"
}
```

### Estados

| Status       | Significado                                             |
| ------------ | ------------------------------------------------------- |
| `PROCESSING` | TED aceita pelo liquidante; aguardando liquidação BACEN |
| `COMPLETED`  | TED liquidada no banco destino (terminal)               |
| `FAILED`     | TED rejeitada, expirada ou timeout 48h (terminal)       |

## Webhooks TED

A forma recomendada de acompanhar TEDs é assinando os webhooks — você é notificado em tempo real sem precisar fazer polling.

### Eventos disponíveis

| Evento              | Quando                                                                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ted.out.requested` | Imediatamente após o POST ser aceito (status `PROCESSING`)                                                                                                                                                         |
| `ted.out.confirmed` | Liquidação confirmada pelo liquidante (terminal — sucesso)                                                                                                                                                         |
| `ted.out.failed`    | Liquidação rejeitada/expirada ou timeout 48h (terminal — falha). Inclui `data.errorReason` quando o liquidante informar o motivo.                                                                                  |
| `ted.in.received`   | TED recebida na sua conta (originada por terceiro). Inclui `data.payer` (nome, documento, banco, ISPB, agência e conta do originador) e `data.payee` com a conta que recebeu (banco 681, agência, conta, titular). |
| `ted.payment`       | **DEPRECATED** — alias de `ted.out.confirmed`. Será removido em v3.0                                                                                                                                               |

Todos os eventos usam o envelope canônico de webhooks (`id`, `type`,
`occurredAt`, `schemaVersion`, `environment`, `tenantId`, `accountId`,
`data`) — o mesmo de PIX, boleto e transferências internas. Veja
[Webhooks](/baas/guias/conta/webhooks).

### Payload `ted.out.requested`

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

### Payload `ted.out.confirmed`

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

### Payload `ted.out.failed`

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

### Payload `ted.in.received`

```json
{
  "id": "ted-in-abc123def",
  "type": "ted.in.received",
  "occurredAt": "2026-05-23T14:15:22.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "773107de-...",
  "data": {
    "transactionId": "abc123def",
    "identifier": "TED-9876",
    "partnerTxId": "abc123def",
    "accountId": "773107de-...",
    "tenantId": "tenant-suaempresa",
    "amount": 1200.00,
    "description": "Pagamento recebido",
    "receivedAt": "2026-05-23T14:15:22Z",
    "payer": {
      "name": "EMPRESA XYZ LTDA",
      "document": "98765432000110",
      "bankCode": "237",
      "bankIspb": "60746948",
      "bankName": "BANCO BRADESCO S.A.",
      "branch": "0001",
      "account": "123456",
      "accountNumber": "123456"
    },
    "payee": {
      "name": "SUA EMPRESA LTDA",
      "document": "12345678000195",
      "bankCode": "681",
      "bankIspb": "50871921",
      "branch": "0001",
      "account": "6371893",
      "accountNumber": "6371893"
    }
  }
}
```

### Dedup

Cada webhook tem `id` único e determinístico (ex.: `ted-{tedId}-confirmed`). Use o `id` na sua base para dedup em caso de re-entrega (acontece em retries do nosso dispatcher quando seu endpoint demora a responder 2xx). O alias legado `ted.payment` reusa o mesmo payload com `id` próprio (`ted-{tedId}-payment`) — diferencie pelo `type` para não descartar o evento canônico.

## Erros comuns

| Código HTTP | `errorCode`            | Quando                                                                                                           |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| 400         | `invalid_bank_code`    | `bankCode` não é um Compe válido de 3 dígitos — inclui o caso de mandar o ISPB (8 dígitos), que a TED não aceita |
| 400         | `invalid_tax_number`   | `taxNumber` não tem 11 (CPF) nem 14 (CNPJ) dígitos                                                               |
| 400         | `invalid_account_type` | `accountType` fora de `CHECKING\|SAVINGS\|PAYMENT\|SALARY`                                                       |
| 400         | `invalid_identifier`   | `identifier` com caracteres não-ASCII ou tamanho inválido                                                        |
| 400         | `missing_fields`       | `value`, `branch`, `account` ou `holderName` ausente                                                             |
| 400         | `invalid_field`        | `description` ou `holderName` fora do formato aceito pelo liquidante                                             |
| 400         | `invalid_payload`      | Corpo JSON malformado                                                                                            |
| 403         | `forbidden`            | Usuário não tem role no tenant da conta                                                                          |
| 503         | `temporal_unavailable` | Orquestrador interno indisponível (raro; aguarde e tente novamente)                                              |
| 503         | `partner_unavailable`  | Banco liquidante indisponível                                                                                    |
| 404         | `not_found`            | `tedId` não encontrado no GET de status                                                                          |

### Erros no workflow (status final `FAILED`)

| `errorReason`                                       | Quando                                                       |
| --------------------------------------------------- | ------------------------------------------------------------ |
| `insufficient_funds`                                | Saldo insuficiente na conta de origem                        |
| `invalid_bank_code`                                 | Banco destino não existe no SPB                              |
| `outside_banking_hours`                             | Tentativa de TED fora da janela aceita pelo banco liquidante |
| `bank_unreachable`                                  | Erro transitório no banco destino                            |
| `limit_exceeded`                                    | Limite operacional atingido                                  |
| `timeout aguardando confirmação do parceiro (>48h)` | Polling defensivo expirou sem liquidação                     |

## Reconciliação

A CorpX faz **polling defensivo** a cada minuto por até 48h após enviar uma TED, mesmo que o webhook do liquidante chegue normalmente. Isso garante que estado interno e estado real do banco estejam sempre alinhados.

Para reconciliar do seu lado:

* **Tempo real:** assine os webhooks `ted.out.{requested,confirmed,failed}` e `ted.in.received`
* **Lookup pontual:** `GET /v1/accounts/{accountId}/ted/{tedId}`
* **Extrato:** `GET /v1/accounts/{accountId}/statement` (TEDs aparecem com `operation=TED`)
* **Timeline detalhada:** `GET /v1/accounts/{accountId}/transactions/timeline?identifier={identifier}`
  — a rota aceita **exatamente um** de `identifier` (o seu, o mesmo enviado na
  criação) ou `endToEndId`. Não existe filtro `tedId` nessa rota: mandar
  `?tedId=` devolve `400 invalid_query`

## Deprecação de `ted.payment`

O evento `ted.payment` (catálogo legado v1) é mantido como **alias** de `ted.out.confirmed` para compatibilidade. Ambos são disparados juntos no mesmo terminal.

* **Novos integradores:** assinem `ted.out.confirmed` (mais descritivo, alinhado com `boleto.paid`, `pix.out.completed`)
* **Integradores legados:** podem continuar com `ted.payment` até a v3.0 (data a ser anunciada)
* **Migração:** desassinar `ted.payment` + assinar `ted.out.confirmed` — payloads são idênticos