> ## 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.
# Dados e relatórios
> Consulte os campos e ciclos de status disponíveis para transferências TED — reconciliação, trilhas de auditoria e relatórios de conformidade.
Cada transferência gera uma trilha de auditoria completa. Esta página descreve os dados disponíveis para relatórios, reconciliação e conformidade.
## Quais dados são registrados por transferência
***
| Campo | O que significa |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transferId` | Sua referência interna para esta transferência |
| `confirmationNumber` | Referência legível pelo usuário (ex: 20260205001) — exiba isso aos clientes |
| `controlNumber` | Referência JD SPB — use para reconciliação bancária |
| `type` | TED OUT, TED IN ou P2P |
| `status` | Estado atual da transferência |
| `amount` | Valor da transferência antes da tarifa |
| `feeAmount` | Tarifa cobrada |
| `totalAmount` | Total debitado (valor + tarifa) |
| `senderAccountId` | Conta de envio no seu sistema. Sempre presente; para TED IN — quando o remetente é um banco externo sem conta local — é um identificador sintético derivado de forma determinística a partir do documento do remetente |
| `recipientAccountId` | Conta destinatária no Midaz, quando o destinatário é representado internamente |
| `recipientDetails` | Banco, agência, número de conta e nome do titular do destinatário |
| `originalTransferId` | A transferência TED OUT original que uma devolução (retorno) TED IN compensa |
| `devolutionCode` | Código BACEN do motivo da devolução, quando aplicável |
| `createdAt` | Quando a transferência foi iniciada |
| `completedAt` | Quando a liquidação foi confirmada |
## Ciclo de vida do status da transferência
***
### TED OUT
* **Cliente confirmou** (`CREATED`) — transferência confirmada pelo cliente, aguardando envio
* **Enviada à rede bancária** (`PENDING`) — mensagem enviada à JD Consultores, aguardando reconhecimento
* **Processamento bancário** (`PROCESSING`) — JD aceitou a transferência e está roteando
* **Liquidada** (`COMPLETED`) — transferência liquidada com sucesso no banco de destino
* **Rejeitada** (`REJECTED`) — JD retornou um erro de negócio (ex: dados de conta inválidos)
* **Falhou** (`FAILED`) — falha técnica (timeout ou indisponibilidade do serviço)
* **Cancelada** (`CANCELLED`) — cliente cancelou antes de a transferência ser enviada
### TED IN
* **Transferência detectada** (`RECEIVED`) — mensagem recebida persistida, aguardando processamento interno
* **Destinatário validado** (`PROCESSING`) — sistema está creditando a conta destinatária
* **Valor creditado** (`COMPLETED`) — conta destinatária creditada com sucesso
O TED IN suporta uma transição de `COMPLETED` para `FAILED` para tratar chargebacks — casos em que uma transferência foi inicialmente liquidada mas posteriormente revertida pelo banco remetente.
### P2P
* **Confirmada** (`CREATED`) — transferência iniciada entre contas internas
* **Processando** (`PROCESSING`) — transação Midaz em andamento
* **Liquidada** (`COMPLETED`) — ambas as contas atualizadas com sucesso
* **Falhou** (`FAILED`) — erro de processamento
* **Cancelada** (`CANCELLED`) — cancelada antes do início do processamento
## Revisão da tarifa antes da confirmação (somente TED OUT)
***
Para TED OUT, os clientes passam por um fluxo de duas etapas:
* **Aguardando confirmação** — a tarifa foi calculada e apresentada; o cliente ainda não confirmou
* **Processada** — o cliente confirmou e a transferência foi criada
* **Expirada** — 24 horas se passaram sem confirmação
Isso permite que os clientes revisem o custo total (valor + tarifa) antes de confirmar a transferência.
## Histórico de status
***
Cada transição de status é registrada com um timestamp, o estado anterior, o novo estado e um motivo (para erros e cancelamentos). Isso fornece uma trilha de auditoria completa para cada transferência — quem alterou o quê e quando.
O campo `changedBy` registra se a transição foi acionada pelo sistema, pelo cliente ou por um administrador.
## Campos de reconciliação
***
Use estes campos para conciliar registros de transferência com seus extratos bancários:
| Campo | Uso para |
| -------------------- | ---------------------------------------------------------------------------- |
| `controlNumber` | Conciliar com registros do JD SPB |
| `confirmationNumber` | Referência para o cliente |
| `transferId` | Consultas internas no sistema |
| `originalTransferId` | Vincular uma devolução (retorno) TED IN ao TED OUT original que ela compensa |
| `devolutionCode` | Classificar o motivo BACEN de uma devolução (retorno) |
| `createdAt` | Filtrar por data de iniciação |
| `completedAt` | Filtrar por data de liquidação |
## Retenção de dados
***
Os registros de transferência são retidos por 5 anos conforme requisitos regulatórios do BACEN (Resolução 4.753/2019). Não exclua registros de transferência.
## Consultando seus dados
***
Use [Listar Transferências](/pt/reference/midaz/plugins/ted/list-transfers) para consultar transferências com os seguintes filtros:
* **Por intervalo de datas** — filtre por `createdAt` ou `completedAt`
* **Por tipo** — TED OUT, TED IN ou P2P
* **Por status** — ex: apenas transferências `COMPLETED` para reconciliação, ou `FAILED` para investigação
## Para desenvolvedores
***
### Armazenamento
Os dados de transferência são armazenados em PostgreSQL. O campo `recipientDetails` usa JSONB para suportar as diferentes estruturas de dados exigidas pelos destinatários de TED OUT, TED IN e P2P, enquanto `recipientAccountId` referencia uma conta Midaz quando o destinatário é interno.
Para suportar os padrões de consulta comuns, o plugin mantém os seguintes índices:
* `(tenant_id, created_at)` para listagens paginadas.
* `(tenant_id, status, created_at)` para filtros baseados em status.
* `(control_number)` para consultas na JD Consultores.
A tabela de auditoria `transfer_status_history` é otimizada para fluxos de auditoria e investigação por meio dos seguintes índices:
* `(transfer_id, changed_at DESC)` para o histórico em nível de transferência.
* `(tenant_id, changed_at DESC)` para consultas de auditoria de todo o tenant dentro de um intervalo de tempo.
### Deduplicação de TED IN recebido
Antes de uma transferência TED IN ser processada, o plugin armazena a mensagem bruta da JD na tabela `JDIncomingMessage`. Isso garante que as transferências recebidas ainda possam ser recuperadas se o serviço falhar durante o processamento.
Para evitar o processamento duplicado, a tabela aplica uma restrição única em `sequenceNumber` (o `NumCabSeq` da JD). Se a JD reentregar a mesma mensagem, o plugin a identifica automaticamente como duplicada e a ignora.
### Relacionamentos entre entidades
O modelo de domínio de TED segue estes relacionamentos:
* Cada `Transfer` pertence a uma única organização e pode ter múltiplos registros de `TransferStatusHistory`.
* Transferências TED OUT podem se originar de uma `PaymentInitiation` ao usar o fluxo de transferência de duas etapas.
* Cada `JDIncomingMessage` pode criar no máximo um `Transfer` do tipo `TED_IN`.
