> ## 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 e informes
> Consulta los campos de datos y los ciclos de vida de estado disponibles para las transferencias TED, usados en conciliación, registros de auditoría e informes de cumplimiento.
Cada transferencia genera un registro de auditoría completo. Esta página describe los datos disponibles para informes, conciliación y cumplimiento.
## Qué datos se registran por transferencia
***
| Campo | Qué significa |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transferId` | Tu referencia interna para esta transferencia |
| `confirmationNumber` | Referencia legible por personas (p. ej. 20260205001) — muéstrasela a los clientes |
| `controlNumber` | Referencia de JD SPB — úsala para la conciliación bancaria |
| `type` | TED OUT, TED IN o P2P |
| `status` | Estado actual de la transferencia |
| `amount` | Monto de la transferencia antes de la comisión |
| `feeAmount` | Comisión cobrada |
| `totalAmount` | Total debitado (monto + comisión) |
| `senderAccountId` | Cuenta emisora en tu sistema. Siempre está presente; para TED IN — donde el emisor es un banco externo sin cuenta local — es un identificador sintético derivado de forma determinista del documento del emisor |
| `recipientAccountId` | Cuenta receptora en Midaz, cuando el receptor está representado internamente |
| `recipientDetails` | Banco, sucursal, número de cuenta y nombre del titular del receptor |
| `originalTransferId` | La transferencia TED OUT original que compensa una TED IN de devolución |
| `devolutionCode` | Código de motivo de devolución de BACEN, cuando corresponde |
| `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 confirmó** (`CREATED`): el cliente confirmó la transferencia, ahora en cola para el envío
* **Enviada a la red bancaria** (`PENDING`): mensaje enviado a JD Consultores, a la espera del acuse de recibo
* **Procesamiento bancario** (`PROCESSING`): JD aceptó la transferencia y la enruta
* **Liquidada** (`COMPLETED`): la transferencia se liquidó con éxito en el banco de destino
* **Rechazada** (`REJECTED`): JD devolvió un error de negocio (p. ej., datos de cuenta inválidos)
* **Fallida** (`FAILED`): falla técnica (timeout o indisponibilidad del servicio)
* **Cancelada** (`CANCELLED`): el cliente canceló antes de que la transferencia se enviara
### TED IN
* **Transferencia detectada** (`RECEIVED`): mensaje entrante persistido, pendiente de procesamiento interno
* **Receptor validado** (`PROCESSING`): el sistema acredita la cuenta receptora
* **Monto acreditado** (`COMPLETED`): la cuenta receptora se acreditó con éxito
El banco emisor puede revertir una transferencia entrante ya liquidada. Para manejar estos chargebacks, TED IN admite una transición de `COMPLETED` a `FAILED`.
### P2P
* **Confirmada** (`CREATED`): transferencia iniciada entre cuentas internas
* **Procesando** (`PROCESSING`): transacción de Midaz en curso
* **Liquidada** (`COMPLETED`): ambas cuentas se actualizaron con éxito
* **Fallida** (`FAILED`): error de procesamiento
* **Cancelada** (`CANCELLED`): cancelada antes de que empezara el procesamiento
## Revisión de la comisión 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 comisión. El cliente todavía no la confirmó
* **Procesada**: el cliente confirmó y el plugin creó la transferencia
* **Expirada**: pasaron 24 horas sin confirmación
Los clientes pueden revisar el costo completo (monto + comisión) 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 estado nuevo y un motivo para los errores y las 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 conciliación. Puede estar vacío.
## Campos de conciliación
***
Usa estos campos para hacer coincidir los registros de transferencia con tus extractos bancarios:
| Campo | Sirve para |
| -------------------- | ---------------------------------------------------------------------- |
| `controlNumber` | Hacer coincidir con los registros de JD SPB |
| `confirmationNumber` | Referencia de cara al cliente |
| `transferId` | Consultas internas del sistema |
| `originalTransferId` | Vincular una TED IN de devolución con la TED OUT original que compensa |
| `devolutionCode` | Clasificar el motivo de BACEN de una devolución |
| `createdAt` | Filtrar por fecha de inicio |
| `completedAt` | Filtrar por fecha de liquidación |
## Retención de datos
***
No borres los registros de transferencia. El plugin nunca los borra ni los hace expirar, así que su retención es tuya. Conserva los registros de transferencias y de auditoría durante al menos 5 años, según los requisitos de conservación de registros de BACEN.
## Consulta de tus datos
***
Usa [List Transfers](/es/reference/interfaces/ted-jd/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**: p. ej., solo transferencias `COMPLETED` para la conciliación, o `FAILED` para investigación
## Para desarrolladores
***
### Almacenamiento
El plugin guarda los datos de transferencia en PostgreSQL. El campo `recipientDetails` usa JSONB. Este campo contiene las distintas estructuras de datos de los receptores de TED OUT, TED IN y P2P. El campo `recipientAccountId` referencia una cuenta de Midaz cuando el receptor 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 el filtrado por estado.
* `(control_number, date)` (único) para las búsquedas de conciliación de JD.
La tabla de auditoría `transfer_status_history` usa un índice para los flujos de auditoría e investigación:
* `(transfer_id, changed_at DESC)` para el historial por transferencia.
### Deduplicación de TED entrantes
Antes de procesar una transferencia TED IN, el plugin guarda 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 evitar el procesamiento duplicado, la tabla aplica una restricción de unicidad sobre `sequenceNumber` (el `NumCabSeq` de JD). Si JD vuelve a entregar el mismo mensaje, el plugin lo identifica de forma automática como duplicado y lo ignora.
### Qué envía el plugin a Midaz
El plugin registra cada movimiento liquidado en Midaz como una transacción del ledger, pero Midaz guarda el asiento contable, no los datos bancarios de la transferencia. La identidad de la contraparte (banco, sucursal, cuenta, nombre del titular y documento) y las referencias de 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 emisor no se codifica en la transacción de Midaz.
Lo que lleva la transacción de Midaz son metadatos de correlación:
| Clave de metadatos | Valor |
| ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `transferId` | El identificador de transferencia del plugin — el pivote de vuelta al registro completo |
| `transferType` | `TED_OUT`, `TED_IN` o `P2P` |
| `initiationId` | El identificador de `PaymentInitiation` (solo TED OUT y P2P — TED IN no tiene paso de inicio) |
| `jdMessageId`, `jdSequence`, `messageCode` | El mensaje de JD que produjo un crédito de TED IN |
Un crédito de devolución lleva además `refundKind`, `originalTransferId`, `devolutionCode` y los números de control originales.
La correlación funciona en ambas direcciones:
* El registro de la transferencia guarda `midazTransactionId`, así que [Get Transfer](/es/reference/interfaces/ted-jd/retrieve-transfer) devuelve el detalle bancario completo de cualquier asiento del ledger.
* La transacción de Midaz guarda `transferId` en sus metadatos, así que puedes listar transacciones de Midaz filtradas por `metadata.transferId` para encontrar el asiento del ledger de una transferencia.
Los metadatos personalizados que envías al iniciar una transferencia TED OUT o P2P se combinan tal cual en la transacción de Midaz. Las claves `transferId`, `transferType` e `initiationId` están reservadas. Los valores del plugin siempre ganan.
### Relaciones entre entidades
El modelo de dominio de TED sigue estas relaciones:
* Cada `Transfer` pertenece a una sola organización y puede tener varios registros `TransferStatusHistory`.
* Las transferencias TED OUT pueden originarse en una `PaymentInitiation` en el flujo de transferencia de dos pasos.
* Cada `JDIncomingMessage` puede crear como máximo una `Transfer` de tipo `TED_IN`.
