> ## 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 de dados e os ciclos de vida de status disponíveis para transferências TED, usados em conciliaçã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, conciliaçã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 por humanos (por exemplo 20260205001) — mostre isso aos clientes |
| `controlNumber` | Referência do JD SPB — use para a conciliaçã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 origem no seu sistema. Sempre presente; para TED IN — em que o remetente é um banco externo sem conta local — é um identificador sintético derivado de forma determinística do documento do remetente |
| `recipientAccountId` | Conta do destinatário no Midaz, quando o destinatário é representado internamente |
| `recipientDetails` | Banco, agência, número da conta e nome do titular do destinatário |
| `originalTransferId` | A transferência TED OUT original que uma TED IN de devolução compensa |
| `devolutionCode` | Código de motivo de devolução do BACEN, 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`): o cliente confirmou a transferência, agora na fila para envio
* **Enviada à rede bancária** (`PENDING`): mensagem enviada à JD Consultores, aguardando confirmação de recebimento
* **Processamento bancário** (`PROCESSING`): a JD aceitou a transferência e a roteia
* **Liquidada** (`COMPLETED`): transferência liquidada com sucesso no banco de destino
* **Rejeitada** (`REJECTED`): a JD retornou um erro de negócio (por exemplo, dados de conta inválidos)
* **Falhou** (`FAILED`): falha técnica (timeout ou indisponibilidade do serviço)
* **Cancelada** (`CANCELLED`): o cliente cancelou antes do envio da transferência
### TED IN
* **Transferência detectada** (`RECEIVED`): mensagem de entrada persistida, pendente de processamento interno
* **Destinatário validado** (`PROCESSING`): o sistema credita a conta do destinatário
* **Valor creditado** (`COMPLETED`): conta do destinatário creditada com sucesso
O banco remetente pode estornar uma transferência de entrada já liquidada. Para tratar esses chargebacks, a TED IN aceita uma transição `COMPLETED` → `FAILED`.
### P2P
* **Confirmada** (`CREATED`): transferência iniciada entre contas internas
* **Processando** (`PROCESSING`): transação Midaz em andamento
* **Liquidada** (`COMPLETED`): as duas contas atualizadas com sucesso
* **Falhou** (`FAILED`): erro de processamento
* **Cancelada** (`CANCELLED`): cancelada antes de o processamento começar
## Revisão da tarifa antes da confirmação (apenas TED OUT)
***
Para TED OUT, os clientes passam por um fluxo de duas etapas:
* **Aguardando confirmação**: o plugin calculou e apresentou a tarifa. O cliente ainda não confirmou
* **Processada**: o cliente confirmou e o plugin criou a transferência
* **Expirada**: 24 horas se passaram sem confirmação
Os clientes podem revisar o custo total (valor + tarifa) antes de confirmar a transferência.
## Histórico de status
***
O plugin registra cada transição de status com data e hora, o estado anterior, o novo estado e um motivo para erros e cancelamentos. Isso dá a você uma trilha de auditoria completa de cada transferência: quem mudou o quê e quando.
O campo `changedBy` registra o ator que fez a transição, por exemplo um processo do sistema ou um worker de conciliação. Ele pode ficar vazio.
## Campos de conciliação
***
Use estes campos para casar os registros de transferência com seus extratos bancários:
| Campo | Usar para |
| -------------------- | ----------------------------------------------------------------- |
| `controlNumber` | Casar com os registros do JD SPB |
| `confirmationNumber` | Referência voltada ao cliente |
| `transferId` | Consultas internas do sistema |
| `originalTransferId` | Ligar uma TED IN de devolução à TED OUT original que ela compensa |
| `devolutionCode` | Classificar o motivo do BACEN para uma devolução |
| `createdAt` | Filtrar por data de início |
| `completedAt` | Filtrar por data de liquidação |
## Retenção de dados
***
Não apague registros de transferência. O plugin nunca os apaga nem os expira, então a retenção é sua responsabilidade. Guarde os registros de transferência e de auditoria por pelo menos 5 anos, conforme os requisitos de guarda de registros do BACEN.
## Consultando seus dados
***
Use [Listar transferências](/pt/reference/interfaces/ted-jd/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**: por exemplo, apenas transferências `COMPLETED` para conciliação, ou `FAILED` para investigação
## Para desenvolvedores
***
### Armazenamento
O plugin armazena os dados de transferência no PostgreSQL. O campo `recipientDetails` usa JSONB. Esse campo guarda as diferentes estruturas de dados dos destinatários de TED OUT, TED IN e P2P. O campo `recipientAccountId` referencia uma conta Midaz quando o destinatário é interno.
Cada tenant tem seu próprio banco de dados, e a organização é o filtro principal dentro de um tenant. O plugin mantém os seguintes índices para padrões de consulta comuns:
* `(midaz_organization_id, created_at)` para listagens paginadas.
* `(midaz_organization_id, status, created_at)` para filtragem por status.
* `(control_number, date)` (único) para consultas de conciliação da JD.
A tabela de auditoria `transfer_status_history` usa um índice para fluxos de auditoria e investigação:
* `(transfer_id, changed_at DESC)` para o histórico no nível da transferência.
### Deduplicação de TED de entrada
Antes de processar uma transferência TED IN, o plugin armazena a mensagem bruta da JD na tabela `JDIncomingMessage`. Isso permite ao plugin recuperar transferências de entrada se o serviço falhar durante o processamento.
Para evitar processamento duplicado, a tabela aplica uma restrição de unicidade em `sequenceNumber` (o `NumCabSeq` da JD). Se a JD reentregar a mesma mensagem, o plugin a identifica automaticamente como duplicata e a ignora.
### O que o plugin envia ao Midaz
O plugin envia cada movimento liquidado ao Midaz como uma transação no ledger, mas o Midaz registra o lançamento contábil, não os detalhes bancários da transferência. A identidade da contraparte (banco, agência, conta, nome e documento do titular) e as referências do BACEN (`controlNumber`, `clearingControlNumber`) ficam apenas no registro `Transfer` do plugin. Para uma TED IN, o crédito entra no ledger a partir da conta `@external/BRL`. A identidade do remetente não é codificada na transação Midaz.
O que a transação Midaz carrega são metadados de correlação:
| Chave de metadado | Valor |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `transferId` | O identificador de transferência do plugin — o ponto de retorno ao registro completo |
| `transferType` | `TED_OUT`, `TED_IN` ou `P2P` |
| `initiationId` | O identificador da `PaymentInitiation` (apenas TED OUT e P2P — a TED IN não tem etapa de início) |
| `jdMessageId`, `jdSequence`, `messageCode` | A mensagem da JD que produziu um crédito de TED IN |
Um crédito de devolução carrega ainda `refundKind`, `originalTransferId`, `devolutionCode` e os números de controle originais.
A correlação funciona nos dois sentidos:
* O registro da transferência armazena `midazTransactionId`, então [Obter transferência](/pt/reference/interfaces/ted-jd/retrieve-transfer) retorna o detalhe bancário completo de qualquer lançamento do ledger.
* A transação Midaz armazena `transferId` nos metadados dela, então você pode listar transações Midaz filtradas por `metadata.transferId` para achar o lançamento do ledger de uma transferência.
Os metadados personalizados que você passa ao iniciar uma transferência TED OUT ou P2P são mesclados na transação Midaz como estão. As chaves `transferId`, `transferType` e `initiationId` são reservadas. Os valores do plugin sempre prevalecem.
### Relacionamentos entre entidades
O modelo de domínio da TED segue estes relacionamentos:
* Cada `Transfer` pertence a uma única organização e pode ter vários registros `TransferStatusHistory`.
* As transferências TED OUT podem se originar de uma `PaymentInitiation` no fluxo de transferência em duas etapas.
* Cada `JDIncomingMessage` pode criar no máximo um `Transfer` do tipo `TED_IN`.
