> ## 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.
# Datos y reportes
> Consulta los campos y ciclos de estado disponibles para Bank Transfer — reconciliación, trazas de auditoría y reportes de cumplimiento.
Cada transferencia genera un registro de auditoría completo. Esta página describe los datos disponibles para reportes, reconciliación y cumplimiento.
## 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`) — el cliente confirmó la transferencia, ahora 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 enruta
* **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 acredita la cuenta del destinatario
* **Monto acreditado** (`COMPLETED`) — cuenta del destinatario acreditada con éxito
El banco remitente puede revertir una transferencia entrante ya liquidada. Para gestionar estos chargebacks, TED IN admite una transición `COMPLETED` → `FAILED`.
### 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** — el plugin calculó y presentó la tarifa. El cliente aún no la ha confirmado
* **Procesada** — el cliente confirmó y el plugin creó la transferencia
* **Expirada** — transcurrieron 24 horas sin confirmación
Los clientes pueden revisar el costo total (monto + tarifa) antes de confirmar la transferencia.
## Historial de estados
***
El plugin registra cada transición de estado con una marca de tiempo, el estado anterior, el nuevo estado y un motivo para errores y cancelaciones. Esto te da un registro de auditoría completo de cada transferencia — quién cambió qué y cuándo.
El campo `changedBy` registra el actor que hizo la transición — por ejemplo, un proceso del sistema o un worker de reconciliación. Puede estar vacío.
## Campos de reconciliación
***
Usa estos campos para relacionar los registros de transferencia con tus 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
***
No elimines los registros de transferencia. El plugin nunca los elimina ni los caduca, así que tú controlas su retención. Consérvalos, junto con los de auditoría, durante al menos 5 años, conforme a los requisitos de conservación de registros del BACEN.
## Consulta de tus datos
***
Usa [Listar Transferencias](/es/reference/midaz/plugins/ted/list-transfers) para consultar transferencias con los siguientes filtros:
* **Por rango de fechas** — filtra por `createdAt` o `completedAt`
* **Por tipo** — TED OUT, TED IN o P2P
* **Por estado** — por ejemplo, solo transferencias `COMPLETED` para reconciliación, o `FAILED` para investigación
## Para desarrolladores
***
### Almacenamiento
El plugin almacena los datos de transferencia en PostgreSQL. El campo `recipientDetails` usa JSONB. Este campo contiene las diferentes estructuras de datos para los destinatarios de TED OUT, TED IN y P2P. El campo `recipientAccountId` referencia una cuenta de Midaz cuando el destinatario es interno.
Cada tenant tiene su propia base de datos, y la organización es el filtro principal dentro de un tenant. El plugin mantiene los siguientes índices para los patrones de consulta comunes:
* `(midaz_organization_id, created_at)` para listados paginados.
* `(midaz_organization_id, status, created_at)` para filtros basados en estado.
* `(control_number, date)` (único) para búsquedas de reconciliación de JD.
La tabla de auditoría `transfer_status_history` usa un índice para flujos de auditoría e investigación:
* `(transfer_id, changed_at DESC)` para el historial a nivel de transferencia.
### Deduplicación de TED IN entrante
Antes de procesar una transferencia TED IN, el plugin almacena el mensaje JD sin procesar en la tabla `JDIncomingMessage`. Esto permite que el plugin recupere las transferencias entrantes 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.
### Qué envía el plugin a Midaz
El plugin registra cada movimiento liquidado en Midaz como una transacción de ledger, pero Midaz guarda el asiento contable — no los detalles bancarios de la transferencia. La identidad de la contraparte (banco, sucursal, cuenta, nombre y documento del titular) y las referencias BACEN (`controlNumber`, `clearingControlNumber`) viven solo en el registro `Transfer` del plugin. En una TED IN, el crédito entra al ledger desde la cuenta `@external/BRL`; la identidad del remitente no se codifica en la transacción de Midaz.
Lo que la transacción de Midaz lleva son metadatos de correlación:
| Clave de metadatos | Valor |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `transferId` | El identificador de la transferencia en el plugin — el pivote de vuelta al registro completo |
| `transferType` | `TED_OUT`, `TED_IN` o `P2P` |
| `initiationId` | El identificador de la `PaymentInitiation` (solo TED OUT y P2P — TED IN no tiene paso de initiate) |
| `jdMessageId`, `jdSequence`, `messageCode` | El mensaje de JD que produjo un crédito de TED IN |
Un crédito de devolución lleva adicionalmente `refundKind`, `originalTransferId`, `devolutionCode` y los números de control originales.
La correlación funciona en ambos sentidos:
* El registro de la transferencia almacena el `midazTransactionId`, así que [Consultar Transferencia](/es/reference/midaz/plugins/ted/retrieve-transfer) devuelve el detalle bancario completo de cualquier asiento del ledger.
* La transacción de Midaz almacena el `transferId` en sus metadatos, así que puedes listar transacciones de Midaz filtrando por `metadata.transferId` para encontrar el asiento de una transferencia.
Los metadatos personalizados que envías al iniciar una transferencia TED OUT o P2P se fusionan en la transacción de Midaz tal cual. Las claves `transferId`, `transferType` e `initiationId` son reservadas — los valores del plugin siempre prevalecen.
### Relaciones entre entidades
El modelo de dominio de TED sigue estas relaciones:
* Cada `Transfer` pertenece a una única organización y puede tener múltiples registros de `TransferStatusHistory`.
* Las transferencias TED OUT pueden originarse desde una `PaymentInitiation` en el flujo de transferencia de dos pasos.
* Cada `JDIncomingMessage` puede crear como máximo un `Transfer` de tipo `TED_IN`.
