> ## 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.
# Recibir (TED IN)
> Recibe transferencias TED automáticamente — el plugin consulta SPB, valida las Cuentas destinatarias y acredita los fondos sin intervención manual.
TED IN permite a tu institución recibir transferencias de cualquier banco brasileño de forma automática. No se requiere ninguna acción de tu equipo — el plugin se encarga de la detección, validación y acreditación. Cuando un cliente de otro banco envía un TED a tu institución, los fondos aparecen en la cuenta del destinatario en minutos.
## Cómo funciona
***
1. Un cliente de otro banco inicia una transferencia TED dirigida a una de las cuentas de tu institución
2. Cada 60 segundos (valor por defecto `JD_POLL_INTERVAL_SECONDS`), el plugin consulta la red JD SPB en busca de transferencias entrantes nuevas
3. La cuenta del destinatario se valida contra tu CRM usando el número de documento incluido en el mensaje de transferencia
4. El monto se acredita automáticamente en la cuenta del destinatario (menos la tarifa de cashin, si está configurada)
## Cronograma de detección y procesamiento
***
Lo que experimenta tu cliente después de que el banco de origen envía la transferencia:
| Tiempo | Qué ocurre |
| ------ | -------------------------------------------------------------------------------- |
| T+0s | El banco de origen envía la transferencia a la red BACEN |
| T+60s | El plugin detecta la transferencia; el estado pasa a `RECEIVED` |
| T+32s | Se busca y confirma la cuenta del destinatario; el estado pasa a `PROCESSING` |
| T+35s | El monto se acredita en la cuenta del destinatario; el estado pasa a `COMPLETED` |
| T+36s | Se envía la notificación webhook a tu sistema |
**SLA típico:** Menos de 1 minuto desde el momento en que el banco de origen envía la transferencia.
## Estados de transferencia
***
| Estado | Qué significa para el destinatario |
| ------------ | ----------------------------------------------------------------------------------------------------------- |
| `RECEIVED` | Transferencia detectada en la red; en proceso |
| `PROCESSING` | Cuenta del destinatario confirmada; se está aplicando el crédito |
| `COMPLETED` | Los fondos han llegado a la cuenta del destinatario |
| `FAILED` | No se pudo aplicar el crédito (p. ej., rechazo de Midaz), o un chargeback revirtió un crédito ya completado |
## Tarifa de recepción (cashin)
***
Tu organización puede opcionalmente cobrar una tarifa sobre las transferencias entrantes. Cuando está habilitada, la tarifa se deduce del monto antes de que se acredite — el destinatario recibe el monto neto. El monto de la tarifa y su configuración se establecen por organización a través del Fees Engine.
Fórmula: `monto acreditado = monto de transferencia − tarifa`
Ejemplo: una transferencia de R$1.000,00 con una tarifa de R$2,50 resulta en R\$997,50 acreditados en la cuenta del destinatario. Esto es lo opuesto a TED OUT, donde la tarifa se suma al monto y el remitente paga más.
## Qué ocurre cuando no se encuentra un destinatario
***
Si el número de documento en la transferencia entrante no puede asociarse a una cuenta en tu CRM, la transferencia se devuelve automáticamente al banco de origen. El cliente remitente recupera su dinero. No se requiere intervención manual y no quedan fondos sin contabilizar.
El mensaje entrante se registra como una transferencia entrante no entregable (en el almacén `undeliverable_incoming_transfers`) y se despacha una devolução (devolución STR0010) al banco de origen. Esta ruta no crea un registro de transferencia acreditada con estado `FAILED`.
## Consultar transferencias recibidas
***
Usa el endpoint [List Transfers](/es/reference/midaz/plugins/ted/list-transfers) para recuperar todas las transferencias entrantes. Filtra por `type=TED_IN` para ver solo las transferencias recibidas.
**Endpoint:** GET /v1/transfers
**Respuesta (campos clave):**
```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 opciones completas de parámetros de consulta, consulta la referencia [List Transfers](/es/reference/midaz/plugins/ted/list-transfers).
## Endpoints operativos
***
Dos endpoints de operador controlan el bucle de polling de TED IN. Están diseñados para scripts y runbooks, no para tráfico de usuario final.
| Endpoint | Propósito |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /v1/transfers/ted-in/poll` | Dispara manualmente el poller de JD que normalmente se ejecuta en un cron de 60s. Útil tras una ventana de incidente o para validar la conectividad con JD. Es tenant-scoped, pero no requiere `X-Organization-Id` porque el tenant se resuelve desde el contexto autenticado. La ruta requiere `X-Idempotency` para reintentos seguros; los reintentos con la misma clave reproducen la respuesta en caché en lugar de leer nuevamente la cola destructiva de JD. |
| `POST /v1/transfers/ted-in/replay` | Reprocesa filas de backlog TED IN persistidas y no procesadas que ya fueron obtenidas de JD. Esto no lee JD nuevamente. La ruta requiere `X-Organization-Id` para el alcance de organización Midaz y `X-Idempotency` para reintentos seguros; el tenant se sigue resolviendo desde el contexto autenticado. |
Para el body de la solicitud, la respuesta, los códigos de estado y los códigos de error, consulta la [especificación OpenAPI de TED](/es/openapi/v3-current/ted.yaml) (operaciones `triggerTEDInPoller` y `replayTEDInPoller`).
## Tres caminos distintos de dead-letter
***
El plugin utiliza tres almacenes de fallas separados. No son intercambiables y deben monitorearse de forma independiente:
* **JD parse failures** — almacenadas en `jd_incoming_parse_failures`. El mensaje llegó desde JD pero no pudo ser interpretado (XML mal formado, tipo de mensaje desconocido). Requiere triaje manual.
* **Transferencias entrantes no entregables** — almacenadas en `undeliverable_incoming_transfers`. El parseo fue exitoso, pero el crédito no pudo aplicarse (p. ej., cuenta del destinatario no encontrada). Puede generar una devolución automática al banco de origen.
* **Webhook DLQ** — la cola de reintentos para entregas de webhook salientes fallidas, expuesta vía `/v1/webhooks/dlq`. No relacionada con la ingesta de TED IN; este es el canal de eventos saliente hacia los clientes integradores.
## Webhooks
***
Configura un webhook para recibir notificaciones en tiempo real cuando lleguen transferencias. El evento `transfer_incoming.completed` se activa en cuanto se acredita una transferencia. Consulta [Webhooks](/es/rails/ted/jd/ted-webhooks) para detalles de configuración y del payload del evento.
## Conciliación
***
Para la conciliación contable y financiera, cada registro de transferencia incluye los siguientes campos:
| Campo | Uso |
| --------------- | -------------------------------------------------------------------------------------------- |
| `controlNumber` | Número de control JD SPB — único por transferencia, usado para la conciliación interbancaria |
| `transferId` | Identificador interno de Lerian |
| `createdAt` | Marca de tiempo de cuando se detectó la transferencia |
| `completedAt` | Marca de tiempo de cuando se acreditaron los fondos |
El historial de transferencias se conserva durante **5 años**, según lo exigen las regulaciones de BACEN.
## Garantías de procesamiento
***
El plugin está diseñado para que ninguna transferencia se pierda y ninguna se acredite dos veces:
* **Sin créditos duplicados** — cada mensaje de transferencia lleva un número de secuencia único; el plugin rechaza cualquier intento de procesar el mismo mensaje más de una vez
* **Reintento automático en caso de falla** — los errores transitorios (como una interrupción momentánea del servicio) se reintentan con retroceso exponencial antes de registrar cualquier estado de falla
* **Cola de mensajes no procesables** — si una transferencia no puede procesarse después de todos los reintentos, se mueve a una cola de mensajes no procesables para revisión manual, asegurando que nada se descarte silenciosamente