O TED IN permite que sua instituição receba transferências originadas em outros bancos. O plugin detecta automaticamente as transferências recebidas, valida o destinatário e credita o valor na conta correspondente.
Como funciona
O recebimento de uma TED é um processo automático detectado pelo worker de polling a cada 30 segundos.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Banco origem │────▶│ JD SPB │────▶│ Plugin TED │
│ envia TED │ │ (polling 30s) │ │ processa │
└─────────────────┘ └─────────────────┘ └────────┬────────┘
│
┌─────────────────┐ │
│ Webhook │◀─────────────┤
│ (opcional) │ │
└─────────────────┘ │
▼
┌─────────────────┐
│ Conta do │
│ destinatário │
│ creditada │
└─────────────────┘
Fluxo de detecção
- A cada 30 segundos, o worker consulta o serviço
RecebeMensagem da JD
- Ao encontrar uma nova mensagem
STR0008R2 que não corresponde a uma transferência enviada pelo sistema, ela é identificada como TED de entrada
- A mensagem XML bruta é imediatamente salva na tabela
JDIncomingMessage (garantia at-most-once)
Processamento
- Cria uma nova entidade
Transfer com tipo TED_IN e status RECEIVED
- Valida se a conta do destinatário existe no CRM
- Se o destinatário for válido, calcula a taxa de cashin (se habilitada)
- Credita a conta no Midaz através de
CreateCashinTransaction
- Atualiza o status para
COMPLETED
- Envia notificação de webhook
Timeline
T+0: Banco externo envia TED
T+30s: Polling detecta mensagem (RecebeMensagem)
├─ Persistir em JDIncomingMessage
└─ Status: RECEIVED
T+32s: Validar destinatário no CRM
└─ Status: PROCESSING
T+35s: Creditar conta (Midaz CreateCashinTransaction)
└─ Status: COMPLETED
T+36s: Webhook notification enviado
Estados do TED IN
RECEIVED → PROCESSING → COMPLETED
→ REJECTED (destinatário não encontrado)
| Estado | Descrição |
|---|
RECEIVED | Transferência detectada, aguardando processamento |
PROCESSING | Validando destinatário e preparando crédito |
COMPLETED | Valor creditado na conta do destinatário |
REJECTED | Destinatário não encontrado ou conta inválida |
Consultar transferências recebidas
Endpoint: GET /v1/transfers?type=TED_IN
Query parameters
| Parâmetro | Tipo | Descrição |
|---|
type | String | Filtrar por tipo (TED_IN) |
status | String | Filtrar por status (COMPLETED, REJECTED) |
startDate | ISO8601 | Data inicial do período |
endDate | ISO8601 | Data final do período |
page | Integer | Número da página (padrão: 1) |
pageSize | Integer | Itens por página (padrão: 20, máx: 100) |
Response
{
"transfers": [
{
"transferId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"type": "TED_IN",
"status": "COMPLETED",
"amount": 5000.00,
"feeAmount": 0.00,
"createdAt": "2026-01-21T10:15:00-03:00"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"totalItems": 150,
"totalPages": 8
}
}
Detalhes de uma transferência
Endpoint: GET /v1/transfers/{transferId}
Response
{
"transferId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"type": "TED_IN",
"status": "COMPLETED",
"sender": {
"ispb": "60746948",
"branch": "1234",
"account": "567890",
"name": "Carlos Oliveira",
"taxId": "98765432100"
},
"recipient": {
"accountId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Empresa ABC Ltda",
"taxId": "12345678000199"
},
"amount": 5000.00,
"feeAmount": 0.00,
"netAmount": 5000.00,
"controlNumber": "JD20260121000042",
"createdAt": "2026-01-21T10:15:00-03:00",
"completedAt": "2026-01-21T10:15:05-03:00",
"statusHistory": [
{"status": "RECEIVED", "timestamp": "2026-01-21T10:15:00-03:00"},
{"status": "PROCESSING", "timestamp": "2026-01-21T10:15:02-03:00"},
{"status": "COMPLETED", "timestamp": "2026-01-21T10:15:05-03:00"}
]
}
Tarifa de recebimento (cashin)
O plugin pode cobrar tarifa sobre transferências recebidas. A configuração é feita por organização.
Quando habilitada, a tarifa é calculada via plugin-fees e deduzida do valor creditado:
netAmount = amount - feeAmount
{
"amount": 1000.00,
"feeAmount": 2.50,
"netAmount": 997.50
}
Validação do destinatário
O plugin valida o destinatário usando o documento (CPF/CNPJ) informado na mensagem STR0008R2:
- Consulta o CRM pelo documento
- Se encontrado, identifica a conta correspondente
- Se não encontrado, inicia devolução (chargeback)
Transferência rejeitada
Quando o destinatário não é encontrado, uma devolução é automaticamente enviada ao banco de origem:
{
"transferId": "d4e5f6a7-b8c9-0123-defg-456789012345",
"type": "TED_IN",
"status": "REJECTED",
"amount": 3000.00,
"sender": {
"ispb": "60701190",
"branch": "0001",
"account": "123456",
"name": "Ana Costa"
},
"rejectionReason": "Recipient not found: document 11122233344 not registered",
"createdAt": "2026-01-21T11:00:00-03:00",
"rejectedAt": "2026-01-21T11:00:03-03:00"
}
Tratamento de erros
Erros críticos e suas ações:
- Destinatário não encontrado: Enviar chargeback para JD (STR0010R2), status=REJECTED
- Midaz indisponível: Retry 3x → DLQ (intervenção manual)
- Duplicado: Constraint unique
sequenceNumber previne créditos duplicados
Webhook de recebimento
Configure um webhook para ser notificado em tempo real sobre transferências recebidas.
Evento: transfer.incoming
{
"event": "transfer.incoming",
"timestamp": "2026-01-21T10:15:05-03:00",
"data": {
"transferId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"type": "TED_IN",
"status": "COMPLETED",
"amount": 5000.00,
"feeAmount": 0.00,
"netAmount": 5000.00,
"sender": {
"ispb": "60746948",
"name": "Carlos Oliveira"
},
"recipient": {
"accountId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Empresa ABC Ltda"
}
}
}
Reconciliação
Para reconciliação contábil, utilize os seguintes campos:
| Campo | Uso |
|---|
controlNumber | Número de controle do JD SPB (único por transferência) |
transferId | Identificador interno da Lerian |
createdAt | Timestamp de detecção |
completedAt | Timestamp de crédito |
Garantias de processamento
O plugin implementa garantias para evitar duplicatas e perdas:
| Garantia | Implementação |
|---|
| At-most-once | Mensagens persistidas ANTES do processamento |
| Idempotência | Mesmo sequenceNumber não é processado duas vezes |
| Retry | Falhas transitórias retentadas com backoff exponencial |
| DLQ | Falhas permanentes vão para dead-letter queue |
CRÍTICO: A mensagem é persistida na tabela JDIncomingMessage ANTES do processamento, garantindo que nenhuma transferência seja perdida em caso de falha.
