# TED e transferências

TED para outras instituições e transferência interna entre contas do parceiro, com favoritos. Valores em **centavos**. Toda conta de origem precisa pertencer ao parceiro do token.

::: tip Como acompanhar o desfecho
A TED emite os webhooks `ted.confirmed` (liquidada) e `ted.failed` (rejeitada ou expirada). A transferência interna emite `transfer.confirmed` e `transfer.failed`. Você também pode consultar o status a qualquer momento em `GET /transfers/:id`, cujo campo `status` passa por `processing`, `accepted`, `settled`, `confirmed`, `completed`, `rejected`, `timeout`, `cancelled` ou `refunded`.
:::

## Enviar TED

```http
POST /api/partner/v1/transfers/ted
Authorization: Bearer {{access_token}}
Content-Type: application/json
Idempotency-Key: {{uuid}}

{
  "account_id": 1042,
  "amount": 25000,
  "recipientName": "João Pereira",
  "recipientDocument": "98765432100",
  "recipientBankCode": "12345678",
  "recipientBranch": "0001",
  "recipientAccount": "123456",
  "purposeCode": "10",
  "description": "Pagamento fornecedor"
}
```

- **Escopo:** `transfer:write`
- **Obrigatórios:** `account_id`, `amount`, `recipientName`, `recipientDocument`, `recipientBankCode` (ISPB da instituição de destino), `recipientAccount`.
- **Opcionais:** `recipientBranch`, `purposeCode` (default `"10"`), `description`.

Os dados do remetente (nome, documento, agência e conta) vêm da conta de origem, você não precisa enviá-los.

Resposta `202`:

```json
{
  "status": "accepted",
  "transactionId": "TED20260711d8a3695bc594e2577c23",
  "amount": 25000,
  "message": "TED enviado para processamento via SPB/BACEN"
}
```

Faltando um campo obrigatório, a resposta é `422` com a mensagem `Campos obrigatórios SPB ausentes: ...`. Uma conta bloqueada ou encerrada responde `422` com `code: "account_blocked"`.

## Transferência interna

Move dinheiro entre duas contas do próprio parceiro. Origem e destino são validados antes de a transferência ocorrer, e não é possível transferir para a mesma conta.

```http
POST /api/partner/v1/transfers/internal
Authorization: Bearer {{access_token}}
Content-Type: application/json
Idempotency-Key: {{uuid}}

{
  "account_id": 1042,
  "destination_account_id": 1043,
  "amount": 5000,
  "description": "Aporte"
}
```

- **Escopo:** `transfer:write` · **Obrigatórios:** `account_id`, `destination_account_id`, `amount`

Resposta `202`:

```json
{ "status": "accepted", "transactionId": "TEF...", "amount": 5000, "message": "Transferência interna aceita para processamento" }
```

Sem `destination_account_id` responde `422`; origem igual ao destino responde `422`; destino de outro parceiro responde `403`.

## Consultar transferência

```http
GET /api/partner/v1/transfers/{id}
Authorization: Bearer {{access_token}}
```

- **Escopo:** `transfer:read`

```json
{
  "data": {
    "transactionId": "TED20260711d8a3...",
    "type": "ted",
    "status": "settled",
    "amount": 25000,
    "recipientKey": "123456",
    "direction": "outbound",
    "createdAt": "2026-07-11T10:00:00Z",
    "completedAt": "2026-07-11T10:00:02Z"
  }
}
```

Uma transação de outro parceiro responde `403`; um id desconhecido responde `404`.

## TED recebida (créditos)

Créditos de TED recebidos de outras instituições, com devolução ao remetente comandada pelo cliente.

### Listar TED recebidas

```http
GET /api/partner/v1/ted/credits?account_id=1042
Authorization: Bearer {{access_token}}
```

- **Escopo:** `transfer:read` · Filtro opcional `status`.

```json
{
  "data": {
    "credits": [
      { "id": "9d4f2c1a-7b3e-4c91-8a52-0f1e2d3c4b5a", "numCtrlStr": "STR20260714000000123", "amount": 150075, "senderName": "JOAO PEREIRA", "senderDocument": "12345678901", "senderIspb": "60746948", "status": "credited_member", "refundable": true, "settlementDate": "2026-07-14", "receivedAt": "2026-07-14T21:00:00Z" }
    ],
    "total": 1
  }
}
```

Valores em **centavos**, os mais recentes primeiro (até 50). `refundable` fica `true` enquanto o crédito pode ser devolvido pelo cliente.

### Devolver TED recebida

Comanda a devolução **integral** do crédito ao remetente, pela mensagem STR0010. Não há devolução parcial: o motor devolve o valor original da operação.

```http
POST /api/partner/v1/ted/credits/{id}/refund
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 1042, "reason": "70" }
```

- **Escopo:** `transfer:write` · `reason` é opcional (padrão `70`) e restrito aos códigos abaixo:

| `reason` | Motivo |
|---|---|
| `1` | Conta encerrada |
| `2` | Agência ou conta inválida |
| `3` | CPF/CNPJ ausente ou divergente |
| `4` | Mensagem inválida para o tipo de transferência |
| `5` | Divergência de titularidade |
| `9` | Fraude |
| `31` | CPF/CNPJ inapto na Receita Federal |
| `70` | Por solicitação do cliente da IF Recebedora (padrão) |
| `72` | Não conformidade no pagamento |
| `84` | Conta inválida para o tipo ou finalidade da transferência |

Resposta `202` (aceite, não o desfecho):

```json
{ "data": { "refundId": "9d4f2c1a-7b3e-4c91-8a52-0f1e2d3c4b5a", "numCtrlStr": "STR20260714000000123", "amount": 150075, "status": "processing" } }
```

O valor fica reservado na conta até o desfecho, que chega pelos webhooks `ted.refund.requested`, `ted.refund.completed` e `ted.refund.failed`, descritos em [Webhooks](/endpoints/webhooks). Um crédito de outra conta ou inexistente responde `404`; devolução já em andamento, crédito já devolvido, motivo inválido ou saldo insuficiente respondem `422`.

## Favoritos

Beneficiários salvos para reutilizar em transferências. O `account_id` é obrigatório em todas as chamadas.

```http
POST   /api/partner/v1/transfers/favorites                        # criar (transfer:write)
GET    /api/partner/v1/transfers/favorites?account_id=1042        # listar (transfer:read)
DELETE /api/partner/v1/transfers/favorites/{id}?account_id=1042   # remover (transfer:write)
Authorization: Bearer {{access_token}}
```

Corpo do POST: `name`, `document`, `bankCode`, `branch`, `accountNumber` são obrigatórios; `accountType` (default `checking`), `pixKey` e `pixKeyType` são opcionais. A resposta `201` traz `{ id, name, document, bankCode, branch, accountNumber, accountType, pixKey, pixKeyType, createdAt }`.