Como funciona
- Um cliente em outro banco inicia uma transferência TED para uma das contas da sua instituição
- A cada 60 segundos (padrão
JD_POLL_INTERVAL_SECONDS), o plugin consulta a rede JD SPB em busca de novas transferências recebidas - O plugin busca a conta do destinatário no seu CRM pelo número de documento presente na mensagem de transferência
- O plugin credita a conta do destinatário automaticamente, menos a tarifa de recebimento se você configurou uma
Prazo de detecção e processamento
As etapas a seguir mostram o que acontece após o banco de origem enviar a transferência:
Tempo típico: O crédito se completa dentro de um ciclo de polling. Com o intervalo de polling padrão de 60 segundos, os fundos chegam em cerca de um minuto.
Estados da transferência
Tarifa de recebimento (cashin)
Sua organização pode cobrar uma tarifa sobre transferências recebidas. Quando você a habilita, o plugin deduz 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 por meio do Fees Engine. Fórmula:
valor creditado = valor da transferência − tarifa
Exemplo: uma transferência de R 2,50 credita R$ 997,50 na conta do destinatário. Isso é o oposto do TED OUT, onde o plugin adiciona a tarifa ao valor e o remetente paga mais.
O que acontece quando o destinatário não é encontrado
Se o plugin não consegue associar o número de documento da transferência recebida a uma conta no seu CRM, ele devolve a transferência ao banco de origem automaticamente. O cliente remetente recebe seu dinheiro de volta. Sua equipe não realiza nenhuma ação, e nenhum fundo fica sem contabilização. O plugin registra a mensagem de entrada como uma transferência recebida não-entregável no armazenamento
undeliverable_incoming_transfers. Em seguida, ele despacha uma devolução (devolução STR0010) 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 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):
Endpoints operacionais
Três endpoints de operador controlam o loop de polling do TED IN. São voltados para scripts e runbooks, não para tráfego de usuário final.
Para o body da requisição, resposta, códigos de status e códigos de erro, consulte a especificação OpenAPI do TED (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:
- JD parse failures — o plugin as armazena em
jd_incoming_parse_failures. A mensagem chegou do JD, mas o plugin não pôde interpretá-la (XML malformado, tipo de mensagem desconhecido). Este armazenamento requer triagem manual. - Transferências de entrada não-entregáveis — o plugin as armazena em
undeliverable_incoming_transfers. O parsing foi bem-sucedido, mas o plugin não pôde aplicar o crédito (por exemplo, não encontrou a conta do destinatário). Esse caminho pode disparar uma devolução automática ao banco de origem. - Webhook DLQ — a fila de retry para entregas de webhook de saída que falharam, em
/v1/webhooks/dlq. Não se relaciona com a 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 o plugin credita uma transferência. Consulte Webhooks para detalhes de configuração e da estrutura do payload.
Reconciliação
Para reconciliação contábil e financeira, cada registro de transferência inclui estes campos:
O plugin mantém os registros de transferência para reconciliação e auditoria.
Garantias de processamento
O plugin se assegura de nunca perder uma transferência e de nunca creditar uma 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.
- Retry automático em caso de falha — o plugin tenta novamente os erros transitórios (como uma interrupção momentânea do serviço) com backoff exponencial antes de registrar qualquer estado de falha.
- Dead-letter queue para problemas irresolvíveis — se o plugin não puder processar uma transferência após todas as tentativas, ele move a transferência para uma dead-letter queue para revisão manual. O plugin nunca descarta uma transferência de forma silenciosa.