El TED IN permite que su institución reciba transferencias originadas en otros bancos. El plugin detecta automáticamente las transferencias recibidas, valida al destinatario y acredita el valor en la cuenta correspondiente.
Cómo funciona
La recepción de un TED es un proceso automático detectado por el worker de polling cada 30 segundos.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Banco origen │────▶│ JD SPB │────▶│ Plugin TED │
│ envía TED │ │ (polling 30s) │ │ procesa │
└─────────────────┘ └─────────────────┘ └────────┬────────┘
│
┌─────────────────┐ │
│ Webhook │◀─────────────┤
│ (opcional) │ │
└─────────────────┘ │
▼
┌─────────────────┐
│ Cuenta del │
│ destinatario │
│ acreditada │
└─────────────────┘
Flujo de detección
- Cada 30 segundos, el worker consulta el servicio
RecebeMensagem de JD
- Al encontrar un nuevo mensaje
STR0008R2 que no corresponde a una transferencia enviada por el sistema, se identifica como TED de entrada
- El mensaje XML bruto es inmediatamente guardado en la tabla
JDIncomingMessage (garantía at-least-once con deduplicación)
Procesamiento
- Crea una nueva entidad
Transfer con tipo TED_IN y estado RECEIVED
- Valida si la cuenta del destinatario existe en el CRM
- Si el destinatario es válido, calcula la tasa de cashin (si está habilitada)
- Acredita la cuenta en Midaz a través de
CreateCashinTransaction
- Actualiza el estado a
COMPLETED
- Envía notificación de webhook
Timeline
T+0: Banco externo envía TED
T+30s: Polling detecta mensaje (RecebeMensagem)
├─ Persistir en JDIncomingMessage
└─ Estado: RECEIVED
T+32s: Validar destinatario en CRM
└─ Estado: PROCESSING
T+35s: Acreditar cuenta (Midaz CreateCashinTransaction)
└─ Estado: COMPLETED
T+36s: Notificación webhook enviada
Estados del TED IN
RECEIVED → PROCESSING → COMPLETED
→ REJECTED (destinatario no encontrado)
| Estado | Descripción |
|---|
RECEIVED | Transferencia detectada, esperando procesamiento |
PROCESSING | Validando destinatario y preparando crédito |
COMPLETED | Valor acreditado en la cuenta del destinatario |
REJECTED | Destinatario no encontrado o cuenta inválida |
Consultar transferencias recibidas
Endpoint: GET /v1/transfers
Query parameters
| Parámetro | Tipo | Descripción |
|---|
type | String | Filtrar por tipo (TED_IN) |
status | String | Filtrar por estado (COMPLETED, REJECTED) |
fromDate | ISO8601 | Fecha inicial del período |
toDate | ISO8601 | Fecha final del período |
pageNumber | Integer | Número de página (por defecto: 1) |
pageSize | Integer | Ítems por página (por defecto: 50, máx.: 100) |
Response
{
"data": [
{
"transferId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"type": "TED_IN",
"status": "COMPLETED",
"amount": 5000.00,
"feeAmount": 0.00,
"recipientHolderName": "Empresa ABC Ltda",
"createdAt": "2026-01-21T10:15:00-03:00"
}
],
"pagination": {
"pageNumber": 1,
"pageSize": 50,
"totalCount": 150,
"totalPages": 3
}
}
Detalles de una transferencia
Endpoint: GET /v1/transfers/
Response
{
"transferId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"type": "TED_IN",
"status": "COMPLETED",
"sender": {
"ispb": "60746948",
"branch": "1234",
"account": "567890",
"holderName": "Carlos Oliveira",
"holderDocument": "98765432100"
},
"recipient": {
"accountId": "550e8400-e29b-41d4-a716-446655440000",
"holderName": "Empresa ABC Ltda",
"holderDocument": "12345678000199"
},
"amount": 5000.00,
"feeAmount": 0.00,
"totalAmount": 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 recepción (cashin)
El plugin puede cobrar tarifa sobre transferencias recibidas. La configuración se hace por organización.
Cuando está habilitada, la tarifa es calculada via plugin-fees y deducida del valor acreditado:
totalAmount = amount - feeAmount
Ejemplo con tarifa
{
"amount": 1000.00,
"feeAmount": 2.50,
"totalAmount": 997.50
}
Validación del destinatario
El plugin valida al destinatario usando el documento (CPF/CNPJ) informado en el mensaje STR0008R2:
- Consulta el CRM por el documento
- Si es encontrado, identifica la cuenta correspondiente
- Si no es encontrado, inicia devolución (chargeback)
Transferencia rechazada
Cuando el destinatario no es encontrado, una devolución es automáticamente enviada al banco de origen:
{
"transferId": "d4e5f6a7-b8c9-0123-defg-456789012345",
"type": "TED_IN",
"status": "REJECTED",
"amount": 3000.00,
"sender": {
"ispb": "60701190",
"branch": "0001",
"account": "123456",
"holderName": "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"
}
Tratamiento de errores
Errores críticos y sus acciones:
- Destinatario no encontrado: Enviar chargeback a JD (STR0010R2), estado=REJECTED
- Midaz no disponible: Retry 3x → DLQ (intervención manual)
- Duplicado: Constraint unique
sequenceNumber previene créditos duplicados
Webhook de recepción
Configure un webhook para ser notificado en tiempo real sobre transferencias recibidas.
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,
"totalAmount": 5000.00,
"sender": {
"ispb": "60746948",
"holderName": "Carlos Oliveira"
},
"recipient": {
"accountId": "550e8400-e29b-41d4-a716-446655440000",
"holderName": "Empresa ABC Ltda"
}
}
}
Reconciliación
Para reconciliación contable, utilice los siguientes campos:
| Campo | Uso |
|---|
controlNumber | Número de control de JD SPB (único por transferencia) |
transferId | Identificador interno de Lerian |
createdAt | Timestamp de detección |
completedAt | Timestamp de crédito |
Garantías de procesamiento
El plugin implementa garantías para evitar duplicados y pérdidas:
| Garantía | Implementación |
|---|
| At-least-once | Mensajes persistidos ANTES del procesamiento |
| Idempotencia | El mismo sequenceNumber no es procesado dos veces |
| Retry | Fallas transitorias reintentadas con backoff exponencial |
| DLQ | Fallas permanentes van a dead-letter queue |
CRÍTICO: El mensaje es persistido en la tabla JDIncomingMessage ANTES del procesamiento, garantizando que ninguna transferencia sea perdida en caso de falla.
