Recibir (TED IN)

TED IN permite que tu institución reciba transferencias de cualquier banco brasileño de forma automática. Tu equipo no hace nada. El plugin detecta, valida y acredita cada transferencia. Cuando un cliente de otro banco envía una TED a tu institución, los fondos llegan a la cuenta del destinatario en minutos.

Cómo funciona

Un cliente de otro banco inicia una transferencia TED hacia una de las cuentas de tu institución
Cada 60 segundos (valor predeterminado de JD_POLL_INTERVAL_SECONDS), el plugin sondea la red de JD SPB en busca de nuevas transferencias entrantes
El plugin busca la cuenta del destinatario en tu CRM por el número de documento del mensaje de la transferencia
El plugin acredita la cuenta del destinatario de forma automática, menos la comisión de cashin si configuraste una

Cronología de detección y procesamiento

Las etapas de abajo muestran qué pasa después de que el banco de origen envía la transferencia:

Etapa	Qué pasa
Envío	El banco de origen envía la transferencia a la red del SPB
Detección	El plugin obtiene la transferencia en su siguiente ciclo de sondeo. El estado pasa a `RECEIVED`
Validación	El plugin confirma la cuenta del destinatario. El estado pasa a `PROCESSING`
Crédito	El plugin acredita la cuenta del destinatario. El estado pasa a `COMPLETED`
Notificación	El plugin envía el webhook a tu sistema

Tiempo típico: el crédito se completa dentro de un ciclo de sondeo. Con el intervalo de sondeo predeterminado de 60 segundos, los fondos llegan en cerca de un minuto.

Estados de la transferencia

Estado	Qué significa para el destinatario
`RECEIVED`	El plugin detectó la transferencia en la red y empezó a procesarla
`PROCESSING`	El plugin confirmó la cuenta del destinatario y aplica el crédito
`COMPLETED`	Los fondos llegaron a la cuenta del destinatario
`FAILED`	El plugin no pudo aplicar el crédito (por ejemplo, un rechazo de Midaz), o un chargeback revirtió un crédito completado

Comisión de recepción (cashin)

Tu organización puede cobrar una comisión sobre las transferencias entrantes. Cuando la habilitas, el plugin descuenta la comisión del monto antes de acreditar al destinatario. El destinatario recibe el monto neto. Defines el monto y la configuración de la comisión por organización mediante el Fees Engine. Fórmula: credited amount = transfer amount − fee Ejemplo: una transferencia de R

1,000.00 con una comisión de R

2.50 acredita R$997.50 a la cuenta del destinatario. Es lo contrario de TED OUT, donde el plugin suma la comisión encima y el remitente paga más.

Qué pasa cuando no se encuentra al destinatario

Si el plugin no puede asociar el número de documento de la transferencia entrante con una cuenta de tu CRM, devuelve la transferencia al banco de origen de forma automática. El cliente que envió recupera su dinero. Tu equipo no hace nada y ningún fondo queda sin registrar. El plugin registra el mensaje entrante como transferencia entrante no entregable en el almacén undeliverable_incoming_transfers. Luego despacha una devolução (retorno STR0010) al banco de origen. Este camino no crea un registro de transferencia acreditada con estado FAILED.

Consultar las transferencias recibidas

Usa el endpoint List Transfers para obtener todas las transferencias entrantes. Filtra por type=TED_IN para ver solo las transferencias recibidas. Endpoint: GET /v1/transfers Respuesta (campos clave):

{
  "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 conocer todas las opciones de parámetros de consulta, consulta la referencia List Transfers.

Endpoints operativos

Tres endpoints de operador controlan el bucle de sondeo de TED IN. Están pensados 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 corre en un cron de 60s. Úsalo después de una ventana de incidente o para validar la conectividad con JD. La ruta tiene ámbito de tenant pero no requiere `X-Organization-Id`, porque resuelve el tenant desde el contexto autenticado. Requiere `X-Idempotency` para reintentos seguros. Un reintento con la misma clave reproduce la respuesta cacheada en lugar de leer otra vez la cola destructiva de JD.
`POST /v1/transfers/ted-in/replay`	Reprocesa las filas de backlog de TED IN persistidas y sin procesar que el plugin ya obtuvo de JD. Esta ruta no vuelve a leer JD. Requiere `X-Organization-Id` para el ámbito de organización de Midaz y `X-Idempotency` para reintentos seguros. Sigue resolviendo el tenant desde el contexto autenticado.
`POST /v1/transfers/ted-in/resume`	Libera el latch de recepción fail-closed y rearma un poller que la recuperación automática no puede revivir — un hijo multi-tenant en pánico o un poller de un solo tenant que superó el tope duro de pánico. Tiene más privilegio que `/poll` porque reabre el consumo de lectura destructiva de JD. Resume nunca omite la compuerta de la ruta del dinero: si el latch actual todavía no tiene una brecha de conciliación durable, la solicitud se rechaza con `409`. Verifica primero las brechas pendientes con List TED IN Reconciliation Gaps y luego, de forma opcional, pasa `{ "acknowledge": true, "note": "..." }` para marcar la brecha como resuelta en la misma llamada. Un poller sano y sin latch devuelve `resumed: false` — la ruta es un no-op idempotente y seguro.

Para el cuerpo de la solicitud, la respuesta, los códigos de estado y los códigos de error, consulta la especificación OpenAPI de TED (operaciones triggerTEDInPoller, replayTEDInPoller y resumeTEDInPoller).

Tres caminos dead-letter distintos

El plugin usa tres almacenes de fallos separados. No son intercambiables y debes monitorear cada uno de forma independiente:

Fallos de parseo de JD: el plugin los guarda en jd_incoming_parse_failures. El mensaje llegó de JD, pero el plugin no pudo interpretarlo (XML mal formado, tipo de mensaje desconocido). Este almacén necesita triage manual.
Transferencias entrantes no entregables: el plugin las guarda en undeliverable_incoming_transfers. El parseo funcionó, pero el plugin no pudo aplicar el crédito (por ejemplo, no encontró la cuenta del destinatario). Este camino puede disparar una devolução automática al banco de origen.
DLQ de webhooks: la cola de reintentos de las entregas de webhook salientes que fallaron, en /v1/webhooks/dlq. No tiene relación con la ingesta de TED IN. Es el canal de eventos salientes hacia los clientes integrados.

Webhooks

Configura un webhook para recibir notificaciones en tiempo real cuando lleguen transferencias. El evento transfer_incoming.completed se dispara apenas el plugin acredita una transferencia. Consulta Webhooks para ver la configuración y los detalles del payload del evento.

Conciliación

Para la conciliación contable y financiera, cada registro de transferencia incluye estos campos:

Campo	Uso
`controlNumber`	Número de control de JD SPB — único por transferencia, se usa para la conciliación interbancaria
`transferId`	Identificador interno de Lerian
`createdAt`	Marca de tiempo de cuando el plugin detectó la transferencia
`completedAt`	Marca de tiempo de cuando el plugin acreditó los fondos

El plugin persiste los registros de transferencia para conciliación y auditoría.

Garantías de procesamiento

El plugin se asegura de nunca perder una transferencia y de nunca acreditarla 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 dos veces.
Reintento automático ante fallos: el plugin reintenta los errores transitorios (como una interrupción momentánea del servicio) con backoff exponencial antes de registrar cualquier estado de fallo.
Cola dead-letter para problemas sin solución: si el plugin no puede procesar una transferencia después de todos los reintentos, mueve la transferencia a una cola dead-letter para revisión manual. El plugin nunca descarta una transferencia en silencio.

Resumen

Integración

Console

Recibir (TED IN)

Cómo funciona

Cronología de detección y procesamiento

Estados de la transferencia

Comisión de recepción (cashin)

Qué pasa cuando no se encuentra al destinatario

Consultar las transferencias recibidas

Endpoints operativos

Tres caminos dead-letter distintos

Webhooks

Conciliación

Garantías de procesamiento

​Cómo funciona

​Cronología de detección y procesamiento

​Estados de la transferencia

​Comisión de recepción (cashin)

​Qué pasa cuando no se encuentra al destinatario

​Consultar las transferencias recibidas

​Endpoints operativos

​Tres caminos dead-letter distintos

​Webhooks

​Conciliación

​Garantías de procesamiento

Cómo funciona

Cronología de detección y procesamiento

Estados de la transferencia

Comisión de recepción (cashin)

Qué pasa cuando no se encuentra al destinatario

Consultar las transferencias recibidas

Endpoints operativos

Tres caminos dead-letter distintos

Webhooks

Conciliación

Garantías de procesamiento