> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Receber (TED IN)
> Receba transferências TED automaticamente — o plugin consulta o SPB, valida as Contas destinatárias e credita os fundos sem intervenção manual.
O TED IN permite que sua instituição receba transferências de qualquer banco brasileiro de forma automática. Nenhuma ação da sua equipe é necessária — o plugin cuida da detecção, validação e crédito. Quando um cliente em outro banco envia uma TED para a sua instituição, os fundos aparecem na conta do destinatário em minutos.
## Como funciona
***
1. Um cliente em outro banco inicia uma transferência TED endereçada a uma das contas da sua instituição
2. A cada 60 segundos (padrão `JD_POLL_INTERVAL_SECONDS`), o plugin consulta a rede JD SPB em busca de novas transferências recebidas
3. A conta do destinatário é validada no seu CRM usando o número de documento presente na mensagem de transferência
4. O valor é creditado automaticamente na conta do destinatário (menos a tarifa de recebimento, se configurada)
## Prazo de detecção e processamento
***
O que seu cliente experimenta após o banco de origem enviar a transferência:
| Tempo | O que acontece |
| ----- | ------------------------------------------------------------------------------ |
| T+0s | Banco de origem submete a transferência à rede BACEN |
| T+60s | Plugin detecta a transferência; status muda para `RECEIVED` |
| T+32s | Conta do destinatário é localizada e confirmada; status muda para `PROCESSING` |
| T+35s | Valor é creditado na conta do destinatário; status muda para `COMPLETED` |
| T+36s | Notificação via webhook é enviada ao seu sistema |
**SLA típico:** Menos de 1 minuto a partir do momento em que o banco de origem envia a transferência.
## Estados da transferência
***
| Estado | O que significa para o destinatário |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `RECEIVED` | Transferência detectada na rede; em processamento |
| `PROCESSING` | Conta do destinatário confirmada; crédito sendo aplicado |
| `COMPLETED` | Fundos chegaram na conta do destinatário |
| `FAILED` | O crédito não pôde ser aplicado (ex: rejeição do Midaz), ou um chargeback reverteu um crédito já concluído |
## Tarifa de recebimento (cashin)
***
Sua organização pode cobrar uma tarifa opcional sobre transferências recebidas. Quando habilitada, a tarifa é deduzida do valor antes do crédito — o destinatário recebe o valor líquido. O valor e a configuração da tarifa são definidos por organização por meio do Fees Engine.
Fórmula: `valor creditado = valor da transferência − tarifa`
Exemplo: uma transferência de R$ 1.000,00 com tarifa de R$ 2,50 resulta em R\$ 997,50 creditados na conta do destinatário. Isso é o oposto do TED OUT, onde a tarifa é adicionada ao valor e o remetente paga mais.
## O que acontece quando o destinatário não é encontrado
***
Se o número de documento na transferência recebida não puder ser associado a uma conta no seu CRM, a transferência é automaticamente devolvida ao banco de origem. O cliente remetente recebe seu dinheiro de volta. Nenhuma intervenção manual é necessária e nenhum fundo permanece sem contabilização.
A mensagem de entrada é registrada como uma transferência recebida não-entregável (no armazenamento `undeliverable_incoming_transfers`) e uma devolução (devolução STR0010) é despachada ao banco de origem. Esse caminho não cria um registro de transferência creditada marcado como `FAILED`.
## Consultar transferências recebidas
***
Use o endpoint [Listar Transferências](/pt/reference/midaz/plugins/ted/list-transfers) para recuperar todas as transferências recebidas. Filtre por `type=TED_IN` para visualizar apenas as transferências recebidas.
**Endpoint:** GET /v1/transfers
**Resposta (campos principais):**
```json theme={null}
{
"items": [
{
"transferId": "019c96a0-ab20-7def-a1b2-1f2a3b4c5d6e",
"type": "TED_IN",
"status": "COMPLETED",
"amount": 5000.00,
"feeAmount": 0.00,
"totalAmount": 5000.00,
"createdAt": "2026-01-21T10:15:00-03:00",
"updatedAt": "2026-01-21T10:15:30-03:00"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"returned": 1,
"totalCount": 150,
"hasNextPage": true
}
}
```
Para opções completas de parâmetros de consulta, consulte a referência [Listar Transferências](/pt/reference/midaz/plugins/ted/list-transfers).
## Endpoints operacionais
***
Dois endpoints de operador controlam o loop de polling do TED IN. Foram desenhados para scripts e runbooks, não para tráfego de usuário final.
| Endpoint | Propósito |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /v1/transfers/ted-in/poll` | Dispara manualmente o poller do JD que normalmente roda em um cron de 60s. Útil após uma janela de incidente ou para validar a conectividade com o JD. É tenant-scoped, mas não requer `X-Organization-Id` porque o tenant é resolvido a partir do contexto autenticado. A rota requer `X-Idempotency` para retentativas seguras; retentativas com a mesma chave reproduzem a resposta em cache em vez de ler novamente a fila destrutiva do JD. |
| `POST /v1/transfers/ted-in/replay` | Reprocessa linhas de backlog TED IN persistidas e não processadas que já foram obtidas do JD. Isso não lê o JD novamente. A rota requer `X-Organization-Id` para o escopo de organização Midaz e `X-Idempotency` para retentativas seguras; o tenant continua sendo resolvido a partir do contexto autenticado. |
Para o body da requisição, resposta, códigos de status e códigos de erro, consulte a [especificação OpenAPI do TED](/pt/openapi/v3-current/ted.yaml) (operações `triggerTEDInPoller` e `replayTEDInPoller`).
## Três caminhos distintos de dead-letter
***
O plugin usa três armazenamentos de falha separados. Eles não são intercambiáveis e devem ser monitorados de forma independente:
* **JD parse failures** — armazenadas em `jd_incoming_parse_failures`. A mensagem chegou do JD mas não pôde ser interpretada (XML malformado, tipo de mensagem desconhecido). Requer triagem manual.
* **Transferências de entrada não-entregáveis** — armazenadas em `undeliverable_incoming_transfers`. O parsing foi bem-sucedido, mas o crédito não pôde ser aplicado (ex: conta do destinatário não encontrada). Pode gerar uma devolução automática ao banco de origem.
* **Webhook DLQ** — a fila de retry para entregas de webhook de saída que falharam, exposta via `/v1/webhooks/dlq`. Não está relacionada à ingestão de TED IN; este é o canal de eventos de saída para os clientes integradores.
## Webhooks
***
Configure um webhook para receber notificações em tempo real quando transferências chegarem. O evento `transfer_incoming.completed` é disparado assim que uma transferência é creditada. Consulte [Webhooks](/pt/rails/ted/jd/ted-webhooks) para detalhes de configuração e estrutura do payload.
## Reconciliação
***
Para reconciliação contábil e financeira, cada registro de transferência inclui os seguintes campos:
| Campo | Uso |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `controlNumber` | Número de controle do JD SPB — único por transferência, usado para reconciliação interbancária |
| `transferId` | Identificador interno da Lerian |
| `createdAt` | Timestamp de detecção da transferência |
| `completedAt` | Timestamp de crédito dos fundos |
O histórico de transferências é mantido por **5 anos**, conforme exigido pelas regulamentações do BACEN.
## Garantias de processamento
***
O plugin é projetado para que nenhuma transferência seja perdida e nenhuma seja creditada duas vezes:
* **Sem créditos duplicados** — cada mensagem de transferência carrega um número de sequência único; o plugin rejeita qualquer tentativa de processar a mesma mensagem mais de uma vez
* **Retry automático em caso de falha** — erros transitórios (como uma interrupção momentânea do serviço) são tentados novamente com backoff exponencial antes que qualquer estado de falha seja registrado
* **Dead-letter queue para problemas irresolvíveis** — se uma transferência não puder ser processada após todas as tentativas, ela é movida para uma dead-letter queue para revisão manual, garantindo que nada seja descartado silenciosamente