Qué datos se registran por transferencia
| Campo | Significado |
|---|---|
transferId | Su referencia interna para esta transferencia |
confirmationNumber | Referencia legible para el usuario (por ejemplo, 20260205001) — muéstresela a los clientes |
controlNumber | Referencia JD SPB — úsela para la reconciliación bancaria |
type | TED OUT, TED IN o P2P |
status | Estado actual de la transferencia |
amount | Monto de la transferencia antes de la tarifa |
feeAmount | Tarifa cobrada |
totalAmount | Total debitado (monto + tarifa) |
senderAccountId | Cuenta de envío en su sistema. Siempre presente; para TED IN — donde el remitente es un banco externo sin cuenta local — es un identificador sintético derivado de forma determinista a partir del documento del remitente |
recipientAccountId | Cuenta destinataria en Midaz, cuando el destinatario está representado internamente |
recipientDetails | Banco, sucursal, número de cuenta y nombre del titular del destinatario |
originalTransferId | La transferencia TED OUT original que compensa una devolución (TED IN de retorno) |
devolutionCode | Código BACEN del motivo de devolución, cuando aplica |
createdAt | Cuándo se inició la transferencia |
completedAt | Cuándo se confirmó la liquidación |
Ciclo de vida del estado de la transferencia
TED OUT
- Cliente confirmado (
CREATED) — transferencia confirmada por el cliente, en cola para envío - Enviada a la red bancaria (
PENDING) — mensaje enviado a JD Consultores, esperando reconocimiento - Procesamiento bancario (
PROCESSING) — JD aceptó la transferencia y la está enrutando - Liquidada (
COMPLETED) — transferencia liquidada con éxito en el banco de destino - Rechazada (
REJECTED) — JD devolvió un error de negocio (por ejemplo, datos de cuenta inválidos) - Fallida (
FAILED) — falla técnica (timeout o indisponibilidad del servicio) - Cancelada (
CANCELLED) — el cliente canceló antes de que se enviara la transferencia
TED IN
- Transferencia detectada (
RECEIVED) — mensaje entrante persistido, pendiente de procesamiento interno - Destinatario validado (
PROCESSING) — el sistema está acreditando la cuenta del destinatario - Monto acreditado (
COMPLETED) — cuenta del destinatario acreditada con éxito
TED IN admite una transición de
COMPLETED a FAILED para gestionar devoluciones — casos en los que una transferencia fue inicialmente liquidada pero luego revertida por el banco remitente.P2P
- Confirmada (
CREATED) — transferencia iniciada entre cuentas internas - Procesando (
PROCESSING) — transacción de Midaz en progreso - Liquidada (
COMPLETED) — ambas cuentas actualizadas con éxito - Fallida (
FAILED) — error de procesamiento - Cancelada (
CANCELLED) — cancelada antes de que comenzara el procesamiento
Revisión de tarifa antes de la confirmación (solo TED OUT)
Para TED OUT, los clientes pasan por un flujo de dos pasos:
- Pendiente de confirmación — la tarifa ha sido calculada y presentada; el cliente aún no ha confirmado
- Procesada — el cliente confirmó y se creó la transferencia
- Expirada — transcurrieron 24 horas sin confirmación
Historial de estados
Cada transición de estado se registra con una marca de tiempo, el estado anterior, el nuevo estado y un motivo (para errores y cancelaciones). Esto le proporciona un registro de auditoría completo de cada transferencia — quién cambió qué y cuándo. El campo
changedBy registra si la transición fue desencadenada por el sistema, el cliente o un administrador.
Campos de reconciliación
Use estos campos para relacionar los registros de transferencia con sus extractos bancarios:
| Campo | Uso para |
|---|---|
controlNumber | Relacionar con los registros de JD SPB |
confirmationNumber | Referencia orientada al cliente |
transferId | Búsquedas en el sistema interno |
originalTransferId | Vincular una devolución (TED IN de retorno) con el TED OUT original que compensa |
devolutionCode | Clasificar el motivo BACEN de una devolución (retorno) |
createdAt | Filtrar por fecha de iniciación |
completedAt | Filtrar por fecha de liquidación |
Retención de datos
Consulta de sus datos
Use Listar Transferencias para consultar transferencias con los siguientes filtros:
- Por rango de fechas — filtre por
createdAtocompletedAt - Por tipo — TED OUT, TED IN o P2P
- Por estado — por ejemplo, solo transferencias
COMPLETEDpara reconciliación, oFAILEDpara investigación
Para desarrolladores
Almacenamiento
Los datos de transferencia se almacenan en PostgreSQL. El camporecipientDetails utiliza JSONB para admitir las diferentes estructuras de datos que requieren los destinatarios de TED OUT, TED IN y P2P, mientras que recipientAccountId referencia una cuenta de Midaz cuando el destinatario es interno.
Para admitir los patrones de consulta comunes, el plugin mantiene los siguientes índices:
(tenant_id, created_at)para listados paginados.(tenant_id, status, created_at)para filtros basados en estado.(control_number)para búsquedas en JD Consultores.
transfer_status_history está optimizada para flujos de auditoría e investigación mediante los siguientes índices:
(transfer_id, changed_at DESC)para el historial a nivel de transferencia.(tenant_id, changed_at DESC)para consultas de auditoría de todo el tenant dentro de un rango de tiempo.
Deduplicación de TED IN entrante
Antes de que se procese una transferencia TED IN, el plugin almacena el mensaje JD sin procesar en la tablaJDIncomingMessage. Esto garantiza que las transferencias entrantes aún puedan recuperarse si el servicio falla durante el procesamiento.
Para prevenir el procesamiento duplicado, la tabla aplica una restricción única en sequenceNumber (el NumCabSeq de JD). Si JD reentrega el mismo mensaje, el plugin lo identifica automáticamente como duplicado y lo ignora.
Relaciones entre entidades
El modelo de dominio de TED sigue estas relaciones:- Cada
Transferpertenece a una única organización y puede tener múltiples registros deTransferStatusHistory. - Las transferencias TED OUT pueden originarse desde una
PaymentInitiational usar el flujo de transferencia de dos pasos. - Cada
JDIncomingMessagepuede crear como máximo unTransferde tipoTED_IN.
