> ## 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 dos destinatários e credita os fundos sem intervenção manual. O TED IN deixa a sua instituição receber transferências de qualquer banco brasileiro automaticamente. O seu time não faz nada. O plugin detecta, valida e credita cada transferência. Quando um cliente de outro banco envia um TED para a sua instituição, os fundos chegam à conta do destinatário em minutos. ## Como funciona *** 1. Um cliente de outro banco começa uma transferência TED para uma das contas da sua instituição 2. A cada 60 segundos (padrão `JD_POLL_INTERVAL_SECONDS`), o plugin consulta a rede do JD SPB em busca de novas transferências de entrada 3. O plugin procura a conta do destinatário no seu CRM pelo número do documento que vem na mensagem da transferência 4. O plugin credita a conta do destinatário automaticamente, menos a tarifa de cashin, se você configurou uma Diagrama do fluxo de TED IN ## Linha do tempo de detecção e processamento *** As etapas abaixo mostram o que acontece depois que o banco de origem envia a transferência: | Etapa | O que acontece | | ----------- | --------------------------------------------------------------------------------------- | | Envio | O banco de origem envia a transferência para a rede do SPB | | Detecção | O plugin busca a transferência no próximo ciclo de polling. O status passa a `RECEIVED` | | Validação | O plugin confirma a conta do destinatário. O status passa a `PROCESSING` | | Crédito | O plugin credita a conta do destinatário. O status passa a `COMPLETED` | | Notificação | O plugin envia o webhook para o seu sistema | **Tempo típico:** o crédito é concluído dentro de um ciclo de polling. Com o intervalo padrão de 60 segundos, os fundos chegam em cerca de um minuto. ## Estados da transferência *** | Estado | O que significa para o destinatário | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `RECEIVED` | O plugin detectou a transferência na rede e começou a processar | | `PROCESSING` | O plugin confirmou a conta do destinatário e aplica o crédito | | `COMPLETED` | Os fundos chegaram à conta do destinatário | | `FAILED` | O plugin não conseguiu aplicar o crédito (por exemplo, uma rejeição do Midaz), ou um chargeback estornou um crédito concluído | ## Tarifa de recebimento (cashin) *** A sua organização pode cobrar uma tarifa nas transferências de entrada. Quando você habilita a cobrança, o plugin desconta a tarifa do valor antes de creditar o destinatário. O destinatário recebe o valor líquido. Você define o valor e a configuração da tarifa por organização pelo Fees Engine. Fórmula: `credited amount = transfer amount − fee` Exemplo: uma transferência de R$ 1.000,00 com uma tarifa de R$ 2,50 credita R\$ 997,50 na conta do destinatário. É o oposto do TED OUT, onde o plugin soma a tarifa por cima e o remetente paga mais. ## O que acontece quando o destinatário não é encontrado *** Se o plugin não consegue casar o número do documento da transferência recebida com uma conta no seu CRM, ele devolve a transferência ao banco de origem automaticamente. O cliente que enviou recebe o dinheiro de volta. O seu time não faz nada, e nenhum fundo fica sem contabilização. O plugin registra a mensagem recebida como uma transferência de entrada não entregável no armazenamento `undeliverable_incoming_transfers`. Depois, despacha uma devolução (retorno STR0010) ao banco de origem. Esse caminho não cria um registro de transferência creditada com status `FAILED`. ## Consultar as transferências recebidas *** Use o endpoint [List Transfers](/pt/reference/interfaces/ted-jd/list-transfers) para recuperar todas as transferências de entrada. Filtre por `type=TED_IN` para ver 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 todas as opções de parâmetros de consulta, veja a referência [List Transfers](/pt/reference/interfaces/ted-jd/list-transfers). ## Endpoints operacionais *** Três endpoints de operador controlam o laço de polling do TED IN. Eles servem a scripts e runbooks, não ao tráfego de usuário final. | Endpoint | Finalidade | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST /v1/transfers/ted-in/poll` | Dispara manualmente o poller da JD que normalmente roda em um cron de 60s. Use depois de uma janela de incidente ou para validar a conectividade com a JD. A rota tem escopo de tenant, mas não exige `X-Organization-Id`, porque resolve o tenant a partir do contexto autenticado. Ela exige `X-Idempotency` para novas tentativas seguras. Uma nova tentativa com a mesma chave repete a resposta em cache em vez de ler de novo a fila destrutiva da JD. | | `POST /v1/transfers/ted-in/replay` | Reprocessa as linhas de backlog de TED IN persistidas e não processadas que o plugin já buscou na JD. Essa rota não lê a JD de novo. Ela exige `X-Organization-Id` para o escopo de organização do Midaz e `X-Idempotency` para novas tentativas seguras. Ela ainda resolve o tenant a partir do contexto autenticado. | | `POST /v1/transfers/ted-in/resume` | Limpa a trava fail-closed de recebimento e rearma um poller que a recuperação automática não consegue reviver — um filho multi-tenant em pânico ou um poller single-tenant que ultrapassou o teto rígido de pânico. Tem privilégio maior que o `/poll` porque reabre o consumo de leitura destrutiva da JD. O resume nunca contorna a barreira do caminho do dinheiro: se a trava atual ainda não tem uma lacuna de conciliação durável, a requisição é recusada com `409`. Verifique antes as lacunas pendentes com [Listar as lacunas de conciliação do TED IN](/pt/reference/interfaces/ted-jd/list-ted-in-reconciliation-gaps) e, se quiser, passe `{ "acknowledge": true, "note": "..." }` para marcar a lacuna como resolvida na mesma chamada. Um poller saudável e sem trava retorna `resumed: false`, e a rota é um no-op idempotente e seguro. | Para o corpo da requisição, a resposta, os códigos de status e os códigos de erro, veja a [especificação OpenAPI do TED](/pt/openapi/v3-current/ted.yaml) (operações `triggerTEDInPoller`, `replayTEDInPoller` e `resumeTEDInPoller`). ## Três caminhos distintos de dead-letter *** O plugin usa três armazenamentos de falha separados. Eles não são intercambiáveis, e você deve monitorar cada um de forma independente: * **Falhas de parsing da JD**: o plugin as guarda em `jd_incoming_parse_failures`. A mensagem chegou da JD, mas o plugin não conseguiu interpretá-la (XML malformado, tipo de mensagem desconhecido). Esse armazenamento precisa de triagem manual. * **Transferências de entrada não entregáveis**: o plugin as guarda em `undeliverable_incoming_transfers`. O parsing funcionou, mas o plugin não conseguiu aplicar o crédito (por exemplo, não achou a conta do destinatário). Esse caminho pode disparar uma devolução automática ao banco de origem. * **DLQ de webhooks**: a fila de novas tentativas das entregas de webhook de saída que falharam, em `/v1/webhooks/dlq`. Não tem relação com a ingestão do TED IN. É o canal de eventos de saída para os clientes que integram. ## Webhooks *** Configure um webhook para receber notificações em tempo real quando as transferências chegam. O evento `transfer_incoming.completed` dispara assim que o plugin credita uma transferência. Veja [Webhooks](/pt/interfaces/ted-jd/ted-webhooks) para a configuração e os detalhes do payload de cada evento. ## Conciliação *** Para a conciliação contábil e financeira, cada registro de transferência traz estes campos: | Campo | Uso | | --------------- | ------------------------------------------------------------------------------------------ | | `controlNumber` | Número de controle do JD SPB — único por transferência, usado na conciliação interbancária | | `transferId` | Identificador interno da Lerian | | `createdAt` | Timestamp de quando o plugin detectou a transferência | | `completedAt` | Timestamp de quando o plugin creditou os fundos | O plugin persiste os registros de transferência para conciliação e auditoria. ## Garantias de processamento *** O plugin garante que nunca perde uma transferência e nunca credita a mesma 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 duas vezes. * **Nova tentativa automática em caso de falha**: o plugin repete os erros transitórios (como uma interrupção momentânea de serviço) com backoff exponencial antes de registrar qualquer estado de falha. * **Fila de dead-letter para problemas sem solução**: se o plugin não consegue processar uma transferência depois de todas as novas tentativas, ele move a transferência para uma fila de dead-letter, para revisão manual. O plugin nunca descarta uma transferência silenciosamente.