> ## 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. O plugin consulta o SPB, valida as contas dos destinatários, credita os fundos e retém para um operador o que não consegue creditar nem devolver. O TED IN deixa a sua instituição receber transferências de qualquer banco brasileiro. 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. Uma transferência que o plugin não consegue creditar nem devolver sozinho aguarda um operador. ## Como funciona *** 1. Um cliente de outro banco começa uma transferência TED para uma das contas da sua instituição 2. Quando o polling do TED IN está ligado (`JD_POLLING_ENABLED`), o plugin consulta a rede do JD SPB em busca de novas transferências de entrada a cada 60 segundos (padrão `JD_POLL_INTERVAL_SECONDS`) 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, menos a tarifa de cashin, se você configurou uma. O plugin lança o crédito no ledger do destinatário no Midaz, conforme o [roteamento do ledger](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-configuration.md#ledger-routing) daquela organização, daquele ledger e do tipo de transferência ![Diagrama do fluxo de TED IN](https://mintcdn.com/lerian-49cb71fc/acz_224gNiM7aYvL/images/pt/d2/ted-how-it-works-ted-in.svg?fit=max\&auto=format\&n=acz_224gNiM7aYvL\&q=85\&s=f66cdaaf59dface4ad5595244998301b) ## Créditos ao cliente *** O plugin também credita o destinatário em sete créditos ao cliente que o banco pagador envia como outras mensagens STR. Cada um tem o próprio tipo de transferência: | Mensagem STR | Tipo de transferência | | - | - | | STR0005R2 | `TED_IN_STR0005` | | STR0007R2 | `TED_IN_STR0007` | | STR0029R2 | `TED_IN_STR0029` | | STR0034R2 | `TED_IN_STR0034` | | STR0037R2 | `TED_IN_STR0037` | | STR0041R2 (crédito consignado do INSS) | `TED_IN_STR0041` | | STR0051R2 | `TED_IN_STR0051` | Cada um desses tipos precisa do próprio vínculo no [roteamento do ledger](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-configuration.md#ledger-routing). O plugin nunca os lança no vínculo de `TED_IN`. Um STR0041R2 cuja tarifa bancária não é zero não é creditado: o plugin o retém com o motivo `CLASSIFICATION_FAILED`. No modo de tarifa `legacy`, o plugin-fees calcula a tarifa de cada tipo pelo pacote de tarifas do próprio tipo, nunca pelo de `TED_IN`. Sem pacote para o tipo, o plugin credita o valor inteiro. ## 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. No modo de tarifa `legacy`, o plugin desconta a tarifa do valor antes de creditar o destinatário, e o destinatário recebe o valor líquido. No modo de tarifa `native`, ele desconta apenas uma tarifa que o pacote de tarifas tira do valor. Você define o valor e a configuração da tarifa por organização pelo Fees Engine. Fórmula, para uma tarifa descontada: `credited amount = transfer amount − fee` Exemplo: uma transferência de R$ 1.000,00 com uma tarifa descontada 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. > [!WARNING] > > No modo de tarifa legado, uma resposta de tarifa inválida, inclusive uma tarifa igual ou superior ao valor bruto, segue `fees.fail_closed_default`. Com `false` (padrão), o plugin credita o valor bruto com tarifa zero e registra a falha da tarifa. Com `true`, recusa o crédito e devolve os fundos por STR0010. O caminho de tarifa nativa do ledger é separado; veja [Configuração do TED](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-configuration.md). ## 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, a política de tenant `jd_polling.auto_return_authorized` decide o que acontece. Nos dois casos, o plugin não credita nada e não cria nenhum registro de transferência. * **`false` (padrão)**: o plugin não devolve nada. Ele retém a mensagem com o motivo `RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED`. Um operador liquida os fundos fora do plugin e depois registra o resultado com [Fechar o crédito não liquidado do TED IN](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/close-unsettled-ted-in-credit.md). O fechamento não move dinheiro. * **`true`**: o plugin devolve a transferência ao banco de origem (devolução STR0010), e o cliente que enviou recebe o dinheiro de volta. O plugin devolve a transferência ao banco de origem, independentemente do que essa política diga, nestes casos: * A conta do destinatário não existe no ledger ou corresponde a mais de uma conta no seu CRM. * O ledger recusa o crédito. * A tarifa não pode ser resolvida e `fees.fail_closed_default` é `true`. ## Consultar as transferências recebidas *** Use o endpoint [List Transfers](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-transfers.md) para recuperar todas as transferências de entrada. Filtre por `type=TED_IN` para ver os TEDs recebidos, por um tipo `TED_IN_STR` para ver um tipo de [crédito ao cliente](#customer-credits), e por `ledgerId` para ver as transferências de um ledger. **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-21T13:15:00Z", "updatedAt": "2026-01-21T13:15:30Z" } ], "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](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-transfers.md). ## Endpoints operacionais *** Estes 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. | | `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 poller 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](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-ted-in-reconciliation-gaps.md) 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. | | `GET /v1/transfers/ted-in/poller` | Lê o estado do poller: habilitado, em execução, desatualizado e o motivo da parada. | 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](https://docs.lerian.studio/pt/openapi/v3-current/ted.yaml). ## Devolver uma transferência recebida *** Você pode devolver um TED IN concluído ao banco pagador com [Return a Transfer](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/return-transfer.md). A requisição precisa da permissão `transfers:return`. 1. O plugin coloca uma retenção do valor creditado na conta do destinatário. 2. O plugin envia um STR0010 voluntário (código de motivo de devolução `70`), que devolve o valor bruto do TED IN ao banco pagador. 3. Quando o STR liquida o STR0010, o plugin estorna o crédito original no ledger. A devolução passa a `COMPLETED`. Se a devolução é recusada, o plugin cancela a retenção, e a devolução passa a `REJECTED`. A devolução é uma nova transferência `TED_OUT` sem tarifa, e o `originalTransferId` dela nomeia o TED IN. Observe estas regras: * Apenas um TED recebido como STR0008R2 pode ser devolvido. Um [crédito ao cliente](#customer-credits) não pode, e um [crédito entre cores](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-cross-core.md#receive-cross-core-credits) também não (`422 BTF-0118`). * Um TED IN tem no máximo uma devolução ativa. * A devolução roda apenas dentro da [janela de funcionamento](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-configuration.md#operating-hours). Em 24 de dezembro e no último dia útil do ano, a janela das devoluções fecha no máximo às 13:00. * A devolução é lançada no vínculo de `TED_OUT` do ledger do TED IN. * Você não pode cancelar uma devolução. Um chargeback (STR0010R2) de um TED IN cuja devolução ainda está em andamento aguarda até a devolução terminar. Um chargeback que chega depois que a devolução saiu aguarda um operador. ## Mensagens que aguardam um operador *** Monitore cada uma destas filas separadamente. Elas não são intercambiáveis: | Fila | O que ela guarda | Como consultar | | - | - | - | | Mensagens retidas | Mensagens que o plugin não creditou nem devolveu. O motivo diz o porquê: por exemplo `UNRECOGNIZED_TYPE`, `ACCOUNT_NOT_OWNED`, `RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED` ou `LEDGER_ROUTE_UNRESOLVED`. Uma mensagem retida por `LEDGER_ROUTE_UNRESOLVED` ou `RECIPIENT_AMBIGUOUS_ORGANIZATIONS` é liberada quando a configuração a cobre. Depois de um reparo no CRM, chame `POST /v1/transfers/ted-in/replay`. Feche as outras com [Fechar o crédito não liquidado do TED IN](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/close-unsettled-ted-in-credit.md) | [Listar as mensagens retidas do TED IN](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-retained-ted-in-messages.md) | | Créditos não entregáveis | Créditos que o plugin não conseguiu aplicar, com o estado da devolução deles ao banco de origem | [Listar os créditos não entregáveis do TED IN](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-undeliverable-ted-in-credits.md) | | Transferências retidas pela conciliação | Créditos TED IN que o ledger não conseguiu confirmar, reembolsos de chargeback que o plugin não conseguiu concluir e devoluções cujo resultado não está comprovado. O plugin tenta de novo um chargeback em `REVERSING` a cada ciclo. Feche um reembolso de chargeback em `MANUAL_REVIEW` com [Resolver a conciliação da transferência](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/resolve-transfer-reconciliation.md), ação `RE_POST` ou `SETTLED_BY_HAND`. Para uma devolução, o código de motivo na transferência decide qual ação a fecha | [Listar as transferências pendentes de conciliação](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-pending-reconciliation.md) | | Lacunas de conciliação | Ciclos de polling cujo resultado de recebimento é desconhecido | [Listar as lacunas de conciliação do TED IN](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-ted-in-reconciliation-gaps.md) | | Falhas de parsing da JD | Mensagens que o plugin não conseguiu interpretar (XML malformado ou schema divergente). Nenhuma API as lê: o operador do deploy faz a triagem delas | Nenhuma | A DLQ de webhooks é um caminho diferente: ela guarda as entregas de webhook de saída que falharam, não as transferências de entrada. Veja [Webhooks](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-webhooks.md). ## 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](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-webhooks.md) 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 *** * **Sem créditos duplicados**: o plugin guarda cada mensagem da JD uma vez, pelo número de sequência dela (`NumCabSeq`). Ele também deduplica os créditos por número de controle, ISPB do remetente e valor. * **Mensagem primeiro**: o plugin guarda cada mensagem antes de processá-la. Uma mensagem que ele não consegue terminar continua não processada, e o próximo ciclo de polling a processa de novo. * **Filas de operador**: uma mensagem que o plugin não consegue creditar nem devolver aguarda nas filas acima. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.