# QI Tech — Investment-as-a-Service › Relatórios

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
16 página(s).

Índice:
- Integração via SFTP (/documentation/iaas/integracao_sftp/inicio)
- Razão Contábil (/documentation/iaas/relatorios_dtvm/accounting_ledger)
- Composição de Carteira de Ativos (/documentation/iaas/relatorios_dtvm/assets_wallet_composition)
- Composição de Ativos da Cessão (/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition)
- Lastros da Cessão (/documentation/iaas/relatorios_dtvm/assignment_documents)
- Relatório de Balanço (/documentation/iaas/relatorios_dtvm/balance_report)
- Demonstrativo de Caixa (/documentation/iaas/relatorios_dtvm/cash_account_demonstrative)
- Movimentações de Caixa (/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements)
- Aquisição Consolidada de Direitos Creditórios (/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets)
- Conciliação Consolidada de Direitos Creditórios (/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets)
- Relatórios DTVM (/documentation/iaas/relatorios_dtvm/)
- Cotas MEC (/documentation/iaas/relatorios_dtvm/quota_mec)
- Testando a Captura de Lastro (/documentation/iaas/relatorios_dtvm/testar_captura_lastro)
- Composição da Carteira (/documentation/iaas/relatorios_dtvm/wallet_composition)
- Webhook de Entrega (/documentation/iaas/relatorios_dtvm/webhook_de_entrega)
- XML ANBIMA (tipos 5 e 401) (/documentation/iaas/relatorios_dtvm/xml_anbima)

---

# Integração via SFTP

URL: /documentation/iaas/integracao_sftp/inicio

O SFTP (Secure File Transfer Protocol) é o canal pelo qual a QI DTVM disponibiliza os relatórios dos fundos para download . Os modelos disponíveis, o layout coluna a coluna de cada arquivo e os exemplos para download estão na [documentação de Relatórios DTVM](/documentation/iaas/relatorios_dtvm/).

Para a integração, recomendamos bibliotecas e clientes que implementem o protocolo, como o `paramiko` em Python, o `sftp` da linha de comando ou qualquer cliente SFTP padrão.

:::info Liberação de acesso

Para solicitar o acesso, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). A liberação é feita primeiro em sandbox e depois em produção.

:::

## Como funciona a autenticação

O acesso é autenticado por **chave pública SSH** — não há senha. Você gera o par de chaves, mantém a chave privada sob o seu controle e nos envia apenas a chave pública, que cadastramos no seu usuário do SFTP.

| Quem            | O que fornece                                                                    |
| --------------- | -------------------------------------------------------------------------------- |
| **Você**        | A chave pública (arquivo `.pub`), no formato OpenSSH                              |
| **A QI DTVM**   | `HOSTNAME`, `PORT` (22) e `USERNAME`, além do <em>fingerprint</em> do host        |

:::danger Nunca envie a sua chave privada

Nenhum time da QI Tech vai pedir a sua chave privada. Se alguém pedir — por e-mail, por chamado ou por qualquer outro canal —, não somos nós. O compartilhamento no 1Password descrito no passo 3 é apenas para a chave **pública** (`sftp_qitech.pub`).

Se a chave privada já foi enviada a alguém ou anexada em algum lugar, considere-a comprometida: gere um par novo e nos envie a nova chave pública.

:::

## 1. Gerando o par de chaves

Gere um par **dedicado ao SFTP**. Não reutilize a chave que assina os seus tokens JWT: são credenciais de sistemas diferentes, com ciclos de vida diferentes — rotacionar uma passaria a obrigar a rotação da outra, e um vazamento em um dos lados atingiria os dois.

Troque `nome-da-empresa` pelo nome da sua empresa — por exemplo, `sftp-acme`. Esse texto é apenas um comentário dentro da chave, e serve para nos ajudar a identificá-la.

**Linux / macOS**

```bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f ~/.ssh/sftp_qitech
```

**Windows (PowerShell)**

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.ssh" | Out-Null
ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f "$env:USERPROFILE\.ssh\sftp_qitech"
```

**Windows (cmd)**

```batch
if not exist "%USERPROFILE%\.ssh" mkdir "%USERPROFILE%\.ssh"
ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f "%USERPROFILE%\.ssh\sftp_qitech"
```

**Windows (WSL)**

```bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f ~/.ssh/sftp_qitech
```

Dentro do WSL, use o caminho do Linux (`~/.ssh`). A chave fica no sistema de arquivos do WSL, e não na pasta do usuário do Windows.

:::caution Copie o comando da aba correspondente

Cada aba escreve o caminho da pasta na forma que aquele programa entende, então os comandos não são intercambiáveis. Se você rodar o comando de uma aba em outro programa, aparece `No such file or directory` e nenhuma chave é criada — nesse caso, é só voltar e copiar o comando da aba certa.

No Windows, se você não sabe qual usar, use o **PowerShell**: é o que abre por padrão no Terminal do Windows.

:::

O comando pergunta por uma passphrase e gera dois arquivos:

| Arquivo            | O que é                                                     |
| ------------------ | ----------------------------------------------------------- |
| `sftp_qitech`      | **Chave privada.** Nunca envie e nunca compartilhe.         |
| `sftp_qitech.pub`  | **Chave pública.** É esta que você deve nos enviar.         |

Sobre a passphrase :

- **Integração automatizada** (um serviço seu baixando os relatórios): deixe em branco, apertando Enter nas duas perguntas, e proteja a chave privada onde ela for armazenada, em um gerenciador de segredos com acesso restrito. Uma passphrase que precisa ficar disponível para o processo em tempo de execução não acrescenta proteção real.
- **Uso por uma pessoa**: defina uma passphrase .

O `ssh-keygen` já cria a chave privada com permissão restrita ao seu usuário. Se você copiar o arquivo para outra máquina, restaure a permissão — clientes SSH recusam chaves privadas legíveis por outros usuários:

```bash
chmod 600 ~/.ssh/sftp_qitech
```

## 2. Conferindo o formato da chave pública

O conteúdo do arquivo `.pub` é **uma única linha**, começando pelo tipo da chave e terminando no comentário:

```text
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE1wA3uBEFYG+Yi7zIw7/YUJJ4fBB0MUZsvUVaqyyv6M sftp-acme
```

Confira o arquivo antes de nos enviar:

```bash
ssh-keygen -lf ~/.ssh/sftp_qitech.pub
```

A resposta esperada é o fingerprint da chave, no formato `256 SHA256:... sftp-acme (ED25519)`. Se o comando responder `is not a public key file`, o arquivo está corrompido ou não é uma chave pública OpenSSH.

### Se a sua chave está no formato PEM/X.509

Uma chave que começa com `-----BEGIN PUBLIC KEY-----` está no formato PEM/X.509, o padrão do OpenSSL. Esse formato **não pode ser cadastrado no SFTP**: o servidor espera o formato OpenSSH, de uma única linha.

Se essa chave já é dedicada ao SFTP, você não precisa gerar outra — basta convertê-la:

- **Você ainda tem a chave privada correspondente.** Vale para qualquer tipo de chave:

  ```bash
  ssh-keygen -y -f caminho/para/chave_privada
  ```

- **Você só tem a chave pública em PEM.** Vale para chaves RSA:

  ```bash
  ssh-keygen -i -m PKCS8 -f caminho/para/chave_publica.pem
  ```

Os dois comandos imprimem a chave no formato OpenSSH na saída padrão. A conversão não preserva o comentário original; se quiser, acrescente `sftp-nome-da-empresa` ao final da linha.

## 3. Enviando a chave pública

Envie a chave pública pelo **1Password**, compartilhando o item com o time de integração. É por esse canal que recebemos as chaves: ele preserva o conteúdo exatamente como você o gerou e deixa a origem do envio verificável — quem conseguisse substituir a sua chave pública no caminho passaria a ter acesso ao seu diretório no SFTP.

1. No 1Password, crie um item e cole nele o conteúdo do arquivo `sftp_qitech.pub` **como texto puro, em uma única linha, sem quebras**.
2. Acrescente o fingerprint da chave — a saída do `ssh-keygen -lf` do passo anterior. Comparamos com o fingerprint da chave que recebemos e confirmamos que ela não foi alterada no caminho.
3. Compartilhe o item com o time de integração e avise em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) que o compartilhamento foi feito.

:::caution Não anexe a chave em `.docx` nem em `.pdf`

A formatação automática desses programas substitui caracteres (um `+` por um travessão, aspas retas por tipográficas) e insere quebras de linha. Qualquer uma dessas alterações invalida a chave, e o erro só aparece na hora da conexão.

:::

Com a chave pública cadastrada, confirmamos a liberação e enviamos o `HOSTNAME`, o `USERNAME` e o fingerprint do host.

## 4. Conectando ao SFTP

### Confira o host key na primeira conexão

Na primeira conexão, o seu cliente vai perguntar se você confia no servidor. Não aceite sem conferir: compare o fingerprint apresentado com o que o time de integração enviou. É essa comparação que impede que outro servidor se passe pelo nosso.

```bash
ssh-keyscan -t ed25519 <hostname> > qitech_host_key
ssh-keygen -lf qitech_host_key          # compare com o fingerprint enviado pela QI DTVM
cat qitech_host_key >> ~/.ssh/known_hosts
```

Depois de conferido, o `known_hosts` passa a ser a referência do cliente e conexões com outro host key são recusadas automaticamente.

### Credenciais da conexão

| Credencial          | Origem                                        |
| ------------------- | --------------------------------------------- |
| `HOSTNAME`          | Endereço do servidor, informado pela QI DTVM  |
| `PORT`              | 22                                            |
| `USERNAME`          | Usuário, informado pela QI DTVM               |
| **Chave privada**   | O arquivo `sftp_qitech` que você gerou        |

:::caution Atenção

Essas credenciais dão acesso direto aos relatórios do seu fundo e não devem ser compartilhadas.

:::

### Exemplo de código

**Python**

```python
import paramiko

HOSTNAME = "sftp.exemplo.com"                # informado pela QI DTVM
PORT = 22
USERNAME = "usuario"                         # informado pela QI DTVM
PRIVATE_KEY = "/caminho/para/sftp_qitech"    # a chave privada que você gerou
KNOWN_HOSTS = "/caminho/para/known_hosts"    # com o host key da QI DTVM já conferido

client = paramiko.SSHClient()
client.load_host_keys(KNOWN_HOSTS)

# Recusa a conexão se o host key não for o esperado.
# Não use AutoAddPolicy: ela aceita qualquer servidor sem verificação.
client.set_missing_host_key_policy(paramiko.RejectPolicy())

client.connect(
    hostname=HOSTNAME,
    port=PORT,
    username=USERNAME,
    key_filename=PRIVATE_KEY,  # o paramiko identifica o tipo da chave pelo arquivo
    look_for_keys=False,
    allow_agent=False,
    timeout=30,
)

try:
    with client.open_sftp() as sftp:
        # Lista os arquivos disponíveis
        for name in sftp.listdir("/"):
            print(name)

        # Faz o download de um arquivo
        sftp.get("caminho/remoto/arquivo.csv", "caminho/local/arquivo.csv")
finally:
    client.close()
```

## 5. Baixando os arquivos

Os arquivos são nomeados a partir do nome resumido do fundo , do modelo do relatório e da data de referência no formato YYYY-MM-DD:

- `example_name_assets_wallet_composition_2026-07-29.csv`

Os modelos disponíveis, o layout coluna a coluna de cada arquivo e os exemplos para download estão na [documentação de Relatórios DTVM](/documentation/iaas/relatorios_dtvm/).

:::info Informação

O SFTP de relatórios descrito nesta página é exclusivamente para download de arquivos; não é permitido realizar upload .

:::

## Rotação e revogação da chave

Para trocar a chave, gere um par novo e nos envie a nova chave pública pelo 1Password, seguindo os passos 1 a 3. Cadastramos a nova chave e informamos quando a anterior for removida — assim a troca acontece sem janela de indisponibilidade.

Se houver suspeita de comprometimento da chave privada, avise o time de integração no mesmo contato: revogamos o acesso da chave antiga imediatamente, antes de cadastrar a nova.

---

# Razão Contábil

URL: /documentation/iaas/relatorios_dtvm/accounting_ledger

## Visão Geral

O relatório `accounting_ledger` apresenta o razão contábil do fundo em um intervalo de datas. Para cada conta do plano de contas com movimentações no período, o relatório exibe uma linha de saldo inicial, os lançamentos do período com data, contrapartida, valor e descrição, e uma linha de saldo final com totais de débito e crédito. Auditores, administradores e analistas utilizam este relatório para rastrear a origem de cada lançamento contábil e verificar a evolução dos saldos conta a conta.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `start_date` | sim | Data de início do período, no formato `AAAA-MM-DD`. |
| `end_date` | sim | Data de fim do período, no formato `AAAA-MM-DD`. Precisa ser **posterior** à data de início. |

Os lançamentos listados são os de data contábil **posterior** à Data de Início e até a Data Final, inclusive. Os lançamentos da própria Data de Início já estão no saldo inicial.

:::caution É preciso haver contabilidade fechada nas duas datas

O relatório só é gerado se existir fechamento contábil na data de início **e** na data de fim. Numa solicitação avulsa, sem isso a solicitação é recusada com a mensagem "Não existe contabil na data ...". Numa entrega por rotina essa checagem não acontece na solicitação: a geração falha e o relatório fica com `status` `failed`.

:::

:::caution As duas datas têm de estar no mesmo exercício contábil

Além de existir fechamento nas duas datas, elas precisam pertencer ao **mesmo exercício** (mesmo *ledger*). Um período que atravessa o encerramento de exercício faz a geração falhar.

:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX |
| Nomenclatura | `{nome_resumido_fundo}_accounting_ledger_{YYYY-MM-DD}.xlsx` |

A data do nome é a `reference_date` da solicitação, e não a `end_date`. Se a solicitação não informar `reference_date`, vale a data da geração do arquivo, no horário de Brasília.

## Conteúdo da Planilha

### Cabeçalho do Fundo

Apresentado nas primeiras linhas da planilha:

| Campo | Descrição |
|-------|-----------|
| Fundo | Nome completo da classe de fundo. |
| CNPJ | CNPJ da classe de fundo. |

Em entregas configuradas em inglês, os rótulos, os cabeçalhos da tabela, os nomes das contas e as descrições vêm traduzidos.

:::caution O sinal do saldo aqui é diferente do Relatório de Balanço

Neste relatório o saldo é o valor cru do fechamento (crédito positivo, débito negativo). No [Relatório de Balanço](/documentation/iaas/relatorios_dtvm/balance_report) o mesmo saldo é normalizado pela natureza da conta. A mesma conta pode, portanto, aparecer como `-45000.00` aqui e `45000.00` lá — são a mesma posição, em convenções de sinal diferentes.

:::

### Lançamentos por Conta

Para cada conta com movimentações no período, o relatório exibe:

1. **Linha de saldo inicial** (em negrito) — saldo da conta na Data de Início.
2. **Linhas de lançamento** — lançamentos de mesma data, contrapartida, descrição, tipo e lado (débito ou crédito) vêm somados em uma única linha.
3. **Linha de saldo final** (em negrito) — saldo da conta na Data Final com totais de débito e crédito.

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `Data` | string | `"2026-07-15"` | Data contábil do lançamento. Nas linhas de saldo inicial e final, exibe a Data de Início e a Data Final respectivamente. |
| `Conta` | string | `"1.2.1.10.00.001.001-9"` | Número da conta no plano de contas, com dígito verificador. |
| `Nome da Conta` | string | `"Direitos Creditórios sem Coobrigação"` | Nome descritivo da conta contábil. |
| `Tipo do Lançamento` | string (enum) | `"A"` | Tipo do lançamento: `"A"` para automático; `"M"` para manual; `"I"` para linha de saldo inicial; `"F"` para linha de saldo final. |
| `ContraPartida` | string | `"7.9.1.20.00.001.001-1"` | Número da conta de contrapartida do lançamento. Vazio nas linhas de saldo inicial e final. |
| `Débito` | número | `1500.00` | Valor do lançamento a débito (em reais). Zero quando o lançamento é a crédito. |
| `Crédito` | número | `0.00` | Valor do lançamento a crédito (em reais). Zero quando o lançamento é a débito. |
| `Saldo` | número | `-196500.00` | Saldo acumulado da conta após o lançamento (em reais). Crédito soma e débito subtrai, **sem normalização pela natureza da conta** — por isso uma conta de ativo com saldo devedor aparece negativa aqui. |
| `Descrição` | string | `"ACRUO DE ATIVOS - CCBs"` | Descrição do evento contábil associado ao lançamento. |

---

# Composição de Carteira de Ativos

URL: /documentation/iaas/relatorios_dtvm/assets_wallet_composition

## Visão Geral

O relatório `assets_wallet_composition` apresenta a posição completa de todos os ativos que compõem o estoque do fundo em uma determinada data de referência. Ele é gerado uma vez ao dia e consolida quatro categorias de ativos:

- **operações de crédito** (ex: CCB) — uma linha por **parcela** da operação;
- **direitos creditórios descontados** (ex: duplicatas, CT-e, contratos descontados) — uma linha por título;
- **contratos** (`contract`, `financing_contract`, `debt_acknowledgment`) — uma linha por parcela do contrato;
- **títulos privados** (ex: debêntures, notas comerciais) — uma linha por parcela do título.

Gestores e analistas utilizam este relatório para acompanhar o estoque, avaliar provisões para devedores duvidosos e monitorar a evolução da carteira.

:::info Uma linha por parcela

Para operações de crédito parceladas, a mesma operação aparece em várias linhas — uma por parcela — repetindo os dados cadastrais (`external_id`, `contract_number`, `purchase_value`) e variando `installment_number`, `face_value`, `maturity_date` e `installment_purchase_value`.

:::

:::tip Também em PDF

Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](/downloads/manual_relatorios_qi_tech.pdf) — revisão 3, outubro de 2026. O manual cobre quatro relatórios: este, a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), a [Aquisição Consolidada](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) e a [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets).

Nesta seção do manual os nomes das colunas aparecem em maiúsculas. No arquivo entregue eles vêm sempre em **minúsculas**, conforme a tabela de colunas abaixo.

:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. |

:::info Fundos de cota de abertura

Para os fundos que operam com relatório de cota de abertura, a posição entregue é a do **dia anterior** à data de referência informada.

:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_assets_wallet_composition_{AAAA-MM-DD}.csv` |

Os nomes das colunas são gerados em **minúsculas**. Datas são escritas no formato `AAAA-MM-DD` e valores decimais usam ponto como separador, com até 8 casas decimais.

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `fund_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_document` | string | `"11.222.333/0001-81"` | CNPJ da classe de fundo. |
| `report_date` | data | `2026-07-30` | Data em que o relatório foi gerado. Nas linhas de títulos privados, esta coluna traz a data de referência da carteira. |
| `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora da operação. Para títulos privados, o valor é `-`. |
| `originator_document` | string | `"22.222.222/0001-91"` | CNPJ do originador. Para títulos privados, o valor é `-`. |
| `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente da operação. Para títulos privados, o valor é `-`. |
| `assignor_document` | string | `"33.333.333/0001-91"` | CNPJ do cedente. Para títulos privados, o valor é `-`. |
| `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor. Para direitos creditórios descontados, é o sacado; para títulos privados, é o emissor. Vazio para contratos. |
| `borrower_document` | string | `"969.698.790-03"` | CPF ou CNPJ do devedor / sacado / emissor. |
| `external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo, conforme informado na criação. |
| `contract_number` | string | `"0900112233/EXA"` | Número do contrato ou número do pedido (`order_number`) associado à operação. |
| `asset_type` | string (enum) | `"ccb"` | Tipo do ativo. Exemplos: `ccb`, `duplicata_mercantil`, `duplicata_servicos`, `cte`, `discounted_contract`, `debenture`. |
| `face_value` | número | `1678.90` | Valor de face da parcela (ou do título) na data de referência, em reais. |
| `present_value` | número | `1663.48` | Valor presente da parcela (ou do título) na data de referência, em reais. |
| `purchase_value` | texto numérico | `4690.80` | Valor do **ativo** na data de aquisição, em reais. Repetido em todas as parcelas da mesma operação. Para operações de crédito e contratos, é o valor contábil: a soma das parcelas trazidas a valor presente pela taxa nominal da operação (`nominal_rate`) na data de aquisição. Ele difere do valor pago pelo fundo quando houve ágio ou deságio na aquisição; o valor pago é a soma de `installment_purchase_value` das parcelas. Para direitos creditórios descontados e títulos privados, é o valor pelo qual o ativo foi adquirido. |
| `bad_provision_value` | número | `0.0` | Valor da provisão para devedores duvidosos (PDD) constituída sobre o ativo, em reais. |
| `bad_provision_range` | string | `"AA"` | Faixa de classificação de risco da PDD — as usuais são `AA`, `A`, `B`, `C`, `D`, `E`, `F`, `G` e `H`, e ativos baixados podem trazer `WO`. Quando não há classificação, o relatório traz `AA`. |
| `fund_date` | data | `2026-07-29` | Data de referência da carteira. |
| `maturity_date` | data | `2026-08-28` | Data de vencimento da parcela (ou do título). |
| `business_maturity_date` | data | `2026-08-28` | Data de vencimento ajustada para dia útil. Para títulos privados, repete o `maturity_date`. |
| `issue_date` | texto de data | `2026-07-28` | Data de emissão do contrato. Para direitos creditórios descontados e contratos, corresponde à data de aquisição. |
| `purchase_date` | texto de data | `2026-07-29` | Data de aquisição do ativo pelo fundo. |
| `total_duration` | inteiro | `30` | Prazo total em dias corridos, da aquisição até o vencimento. |
| `present_duration` | inteiro | `30` | Prazo remanescente em dias corridos, da data de referência até o vencimento. Fica negativo quando o ativo está vencido. |
| `asset_maturity_status` | string (enum) | `"on_time"` | Situação do vencimento: `OVERDUE` quando vencido, `on_time` quando dentro do prazo. |
| `assignment_rate_of_return` | número | `0.0312` | Taxa interna de retorno (TIR) da cessão. Vazio para títulos privados. |
| `purchase_rate_of_return` | texto numérico | `0.031874210` | TIR corrente da operação no momento da aquisição. Para títulos privados, o valor é `-`. |
| `has_assignor_coobligation` | string | `"False"` | Indica coobrigação do cedente: `True` ou `False`. Para títulos privados, o valor é `-`. |
| `installment_number` | inteiro | `1` | Número da parcela. Para direitos creditórios descontados, é sempre `1`. |
| `bad_debt_type` | string | `"default"` | Tipo de classificação da PDD aplicada ao ativo. |
| `nominal_rate` | número | `0.0231` | Taxa nominal mensal pré-fixada da operação. Vazio para direitos creditórios descontados e títulos privados. |
| `operation_type` | string | `"ccb"` | Tipo da operação registrado no cadastro do ativo. Vazio para títulos privados. |
| `installment_purchase_value` | texto numérico | `1598.74210000` | Valor pago pelo fundo pela **parcela** específica, em reais. Vazio para direitos creditórios descontados e títulos privados. |
| `asset_key` | string | `"1a2b3c40-0001-4aaa-9111-000000000101"` | Chave interna do ativo gerada pela QI Tech (UUID). |
| `asset_external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo. Em operações de crédito, `external_id` pode trazer o identificador da parcela; `asset_external_id` é sempre o do ativo. |

:::info Colunas adicionais

Quando a entrega é configurada com a opção `benefit_number`, o relatório traz uma coluna extra `benefit_type` ao final, com o tipo de benefício associado à garantia da operação. Com a opção `original_face_value`, traz também a coluna `original_face_value` (valor de face original da parcela; vazia para direitos creditórios descontados e títulos privados).

:::

---

# Composição de Ativos da Cessão

URL: /documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition

## Visão Geral

O relatório `assignment_assets_wallet_composition` detalha os ativos de **uma cessão específica**, no mesmo formato do relatório de [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition). É o relatório usado para conferir o que entrou na carteira imediatamente após uma aquisição, antes de o ativo passar a compor as posições diárias.

- **operações de crédito** — uma linha por **parcela**;
- **direitos creditórios descontados** — uma linha por **ativo**;
- **contratos** — uma linha por **parcela**.

:::tip Também em PDF

Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](/downloads/manual_relatorios_qi_tech.pdf) — revisão 3, outubro de 2026. O manual cobre quatro relatórios: este, a [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition), a [Aquisição Consolidada](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) e a [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets).

Nesta seção do manual os nomes das colunas aparecem em maiúsculas. No arquivo entregue eles vêm sempre em **minúsculas**, conforme a tabela de colunas abaixo.

:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `external_id` | sempre | O "seu número" da cessão a consultar. |
| `asset_type` | sempre | Define qual consulta é executada. Operações de crédito: `ccb`, `structured_ccb`, `cce`, `structured_cce`, `structured_cci`, `structured_nce`. Direitos creditórios descontados: `duplicata_mercantil`, `duplicata_servicos`, `discounted_contract`, `legal_fees`, `cte`, `check`, `promissory_note`. Contratos: `contract`, `financing_contract`, `debt_acknowledgment`. Um tipo fora dessas listas faz o relatório falhar. |
| `fund_class_key` | só para direitos creditórios descontados e contratos | Classe de fundo sobre a qual o relatório é gerado. Para operações de crédito o filtro é feito apenas pela cessão, e o fundo informado é ignorado. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_assignment_assets_wallet_composition_{AAAA-MM-DD}_{external_id}.csv` |

:::info O nome do arquivo termina com o identificador da cessão

Diferente dos relatórios diários, este acrescenta o `external_id` da cessão ao final do nome. Como o `external_id` é obrigatório, o sufixo está sempre presente.

:::

## O que o relatório traz

- Todos os ativos da cessão informada, **exceto** os descartados (`discarded`) e os reprovados (`denied`). Para contratos, saem os contratos com status `failed` ou `canceled`.
- As últimas colunas variam conforme o tipo de ativo — veja `asset_external_id` / `invoice_number` e `monthly_rate` na tabela abaixo.
- Campos sem valor vêm vazios no arquivo.

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `fund_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_document` | string | `"11.222.333/0001-81"` | CNPJ da classe de fundo. |
| `fund_date` | data | `2026-07-29` | Data contábil corrente do fundo. |
| `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome do originador. |
| `originator_document` | string | `"22.222.222/0001-91"` | CNPJ do originador. |
| `name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do **cedente**. Atenção ao cabeçalho genérico: apesar de `name`, o conteúdo é o cedente, não o fundo nem o devedor. |
| `document_number` | string | `"33.333.333/0001-91"` | CNPJ do **cedente**. Mesma observação da coluna anterior. |
| `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor ou do sacado. Vazio para contratos. |
| `borrower_document` | string | `"969.698.790-03"` | CPF ou CNPJ do devedor/sacado. |
| `external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201-1"` | Identificador externo da **parcela** (operação de crédito) ou do **ativo** (direito creditório descontado e contrato). |
| `contract_number` | string | `"0900112233/EXA"` | Número do contrato ou do pedido. |
| `asset_type` | string (enum) | `"ccb"` | Tipo do ativo. |
| `face_value` | número | `1678.90` | Valor de face/nominal (em reais). |
| `present_value` | número | `1598.74210000` | Valor presente. Nesta visão, igual ao valor de compra. |
| `purchase_value` | número | `1598.74210000` | Valor de aquisição (em reais). |
| `bad_provision_value` | número | `0` | Provisão para devedores duvidosos. **Fixo em `0`** nesta visão. |
| `bad_provision_range` | string | `"AA"` | Faixa de PDD. **Fixo em `AA`** (melhor faixa) nesta visão. |
| `report_date` | data | `2026-07-30` | Data de geração do relatório. |
| `maturity_date` | data | `2026-08-28` | Vencimento da parcela ou do ativo. |
| `business_maturity_date` | data | `2026-08-28` | Vencimento ajustado. Nesta visão, repete o `maturity_date`. |
| `issue_date` | data | `2026-07-29` | Data de emissão. Nesta visão, traz a **data da cessão** (para contratos, a data de aquisição da cessão). |
| `purchase_date` | data | `2026-07-29` | Data de aquisição. Nesta visão, traz a **data da cessão** (para contratos, a data de aquisição da cessão). |
| `total_duration` | número | `30` | Prazo total, em dias. |
| `present_duration` | número | `30` | Nesta visão, repete o `total_duration`. |
| `asset_maturity_status` | string (enum) | `"on_time"` | `OVERDUE` quando a data da cessão é posterior ao vencimento; `on_time` nos demais casos. |
| `assignment_irr` | número | `0.0312` | Taxa de cessão. |
| `purchase_irr` | número | `0.03187421` | Taxa de compra do recebível. |
| `has_assignor_coobligation` | string | `"False"` | Coobrigação do cedente, como texto `"True"` ou `"False"`. Para operações de crédito e direitos creditórios descontados, vem da configuração de cessão; para contratos, do cadastro do contrato. |
| `asset_external_id` **ou** `invoice_number` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Operação de crédito e contrato: identificador externo do ativo (`asset_external_id`). Direito creditório descontado: chave de acesso da NF-e (`invoice_number`). |
| `monthly_rate` | string | `"0.0231"` | Taxa mensal pré-fixada. **Só existe nos arquivos de operações de crédito e de contratos** — no de direitos creditórios descontados a coluna não é emitida. |
| `installment_number` | string | `"1"` | Número da parcela. **Só existe no arquivo de contratos**, sempre como última coluna. |

## Colunas opcionais

Podem ser solicitadas na geração do relatório e são acrescentadas **ao final** do arquivo, nesta ordem. Valem apenas para **operações de crédito**.

| Coluna | Descrição |
|--------|-----------|
| `installment_number` | Número da parcela. |
| `disbursement_value` | Valor desembolsado no contrato. |
| `cet` | Custo Efetivo Total do contrato. |
| `issue_value` | Valor de emissão do contrato. |
| `interest_rate_type` | Tipo da taxa de juros da operação. |
| `disbursement_target_document_number` | CPF ou CNPJ do destinatário do desembolso. |
| `disbursement_date` | Data do desembolso. |
| `borrower_birthdate` | Data de nascimento do devedor (pessoa natural). |
| `benefit_type` | Tipo de benefício da primeira garantia da operação. Habilitada pela opção `benefit_number`. |

:::info Como pedir as colunas opcionais

A habilitação é feita pela QI DTVM na configuração da entrega, por relatório. Se você precisar de alguma dessas colunas, informe ao time de integração quais deseja.

:::

---

# Lastros da Cessão

URL: /documentation/iaas/relatorios_dtvm/assignment_documents

## Visão Geral

O relatório `assignment_documents` lista os **documentos comprobatórios** dos ativos de uma cessão específica, com um link de download para cada arquivo. É o relatório usado para arquivar o lastro da operação: uma linha por documento, com a chave do ativo a que ele pertence.

Ele é o complemento da [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition): aquele traz os valores e características dos ativos cedidos, este traz os arquivos que os comprovam.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo da cessão. |
| `external_id` | sim | O "seu número" da cessão a consultar. |

Este relatório **não recebe data de referência** — ele sempre reflete os documentos existentes no momento da geração.

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_assignment_documents_{external_id}_{AAAA-MM-DD}.csv` |

:::caution A nomenclatura deste relatório é diferente

Duas diferenças em relação aos outros relatórios:

1. o identificador da cessão vem **antes** da data, e não no fim do nome — compare com o `assignment_assets_wallet_composition`, que acrescenta o `external_id` no final;
2. a data no nome é a **data de geração do arquivo** (fuso de Brasília), não uma data de referência informada por você. Gerar o mesmo relatório em dois dias diferentes produz dois nomes diferentes para o mesmo conteúdo.

:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `assignment_external_id` | string | `"CESSAO-2026-07-29-001"` | Identificador externo da cessão. Igual em todas as linhas do arquivo. |
| `asset_key` | string | `"1a2b3c40-0001-4aaa-9111-000000000101"` | Chave interna do ativo gerada pela QI Tech (UUID). Repete-se quando o ativo tem mais de um documento. |
| `asset_external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo. |
| `document_key` | string | `"50e60f70-0001-4fff-9666-000000000601"` | Chave interna do documento gerada pela QI Tech (UUID). |
| `document_type` | string (enum) | `"ccb"` | Tipo do documento: `ccb`, `duplicata_mercantil`, `duplicata_servicos`, `discounted_contract`, `cte`, `check`, `promissory_note`, `contract`, `invoice` (nota fiscal do recebível), `legal_fees_contract`, `disbursement_receipt` ou `vehicle_reservation_receipt`. |
| `document_url` | string | `"https://<link-temporario-de-download>"` | Link de download direto do arquivo. O download chega com o nome `{document_type}-{asset_external_id}.pdf` (caracteres fora de `A-Z`, `a-z`, `0-9`, `.`, `_` e `-` viram `_`). Veja o aviso sobre validade abaixo. |

:::danger Os links expiram em 5 dias

`document_url` é uma URL pré-assinada, gerada no momento em que o relatório é produzido e válida por **5 dias (432.000 segundos)**. Depois disso o link retorna erro e é preciso gerar o relatório novamente para obter links novos.

Não armazene as URLs como referência permanente do documento. Se você precisa guardar o lastro, **baixe os arquivos** dentro da janela de validade e use `document_key` como identificador estável do documento.

:::

:::tip Testando a captura dos arquivos

Para exercitar o download em sandbox com links reais — e com documentos de exemplo de cada `document_type` — siga o roteiro em [Testando a Captura de Lastro](/documentation/iaas/relatorios_dtvm/testar_captura_lastro).

:::

## O que o relatório traz

- Os documentos de todos os ativos da cessão informada, **exceto** os dos ativos descartados (`discarded`) e reprovados (`denied`).
- **Uma linha por documento.** Um ativo com contrato e nota fiscal aparece em duas linhas, com o mesmo `asset_key` e `document_type` diferentes.
- Ativos sem documento anexado não aparecem no arquivo.

:::tip Cruzando com a composição da cessão

`asset_external_id` e `asset_key` são as chaves de junção com a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition). Cruzando os dois arquivos você confere se todo ativo cedido tem o lastro correspondente — um ativo presente na composição e ausente aqui é um ativo sem documento anexado.

:::

---

# Relatório de Balanço

URL: /documentation/iaas/relatorios_dtvm/balance_report

## Visão Geral

O relatório `balance_report` apresenta o balanço contábil consolidado do fundo entre duas datas de referência. Ele exibe, para cada conta do plano de contas, o saldo inicial (Data de Início), os movimentos de débito e crédito ocorridos no período e o saldo final (Data Final). O relatório organiza as contas em uma estrutura hierárquica (grupos e subgrupos) e inclui totalizadores para ativo, passivo, patrimônio líquido, receitas, despesas e compensações. Administradores e analistas utilizam este relatório para verificar a consistência contábil e auditar a evolução do balanço do fundo.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `start_date` | sim | Data de início do período, no formato `AAAA-MM-DD`. |
| `end_date` | sim | Data de fim do período, no formato `AAAA-MM-DD`. Precisa ser **posterior** à data de início. |

Os movimentos considerados são os de data contábil **posterior** à Data de Início e até a Data Final, inclusive. Os lançamentos da própria Data de Início já estão no saldo inicial.

:::caution É preciso haver contabilidade fechada nas duas datas

O relatório só é gerado se existir fechamento contábil na data de início **e** na data de fim. Numa solicitação avulsa, sem isso a solicitação é recusada com a mensagem "Não existe contabil na data ...". Numa entrega por rotina essa checagem não acontece na solicitação: a geração falha e o relatório fica com `status` `failed`.

:::

:::caution As duas datas têm de estar no mesmo exercício contábil

Além de existir fechamento nas duas datas, elas precisam pertencer ao **mesmo exercício** (mesmo *ledger*). Um período que atravessa o encerramento de exercício faz a geração falhar.

:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX |
| Nomenclatura | `{nome_resumido_fundo}_balance_report_{YYYY-MM-DD}.xlsx` |

A data do nome é a `reference_date` da solicitação, e não a `end_date`. Se a solicitação não informar `reference_date`, vale a data da geração do arquivo, no horário de Brasília.

## Conteúdo da Planilha

### Cabeçalho do Fundo

Apresentado nas primeiras linhas da planilha, com o rótulo na coluna A e o valor na coluna B. Os rótulos abaixo são os textos literais da planilha, com os dois-pontos:

| Campo | Descrição |
|-------|-----------|
| `Nome do Fundo:` | Nome completo da classe de fundo. |
| `CNPJ do Fundo:` | CNPJ da classe de fundo. |
| `Data de Início:` | Data de início do período no formato `YYYY-MM-DD`. |
| `Data Final:` | Data de fim do período no formato `YYYY-MM-DD`. |
| `Total do Ativo:` | Soma do saldo final das contas de ativo. |
| `Total do Passivo:` | Soma do saldo final das contas de passivo. |
| `Total de PL:` | Saldo final das contas de patrimônio líquido. |
| `Total de Receitas:` | Saldo final das contas de receita. |
| `Total de Despesas:` | Saldo final das contas de despesa. |
| `Total de Compensação Ativa:` | Saldo final das contas de compensação ativa (grupo 3). |
| `Total de Compensação Passiva:` | Saldo final das contas de compensação passiva (grupo 9). |
| `PL por Contas Patrimoniais:` | `Total do Ativo - Total do Passivo` |
| `PL por Contas de Resultado:` | `Total de PL + Total de Receitas + Total de Despesas` |
| `Bate Compensação :` | `Total de Compensação Ativa - Total de Compensação Passiva` |

Em entregas configuradas em inglês, os rótulos, os cabeçalhos da tabela e os nomes das contas vêm traduzidos.

:::info Os totais são fórmulas do Excel

As células do cabeçalho não são valores fixos: elas referenciam as linhas de total da tabela de contas (por exemplo, `Total do Ativo` é `=G20`). Ao abrir o arquivo, o Excel recalcula tudo — e, se você editar a tabela, os totais acompanham.

:::

### Tabela de Contas

Linhas organizadas hierarquicamente por número de conta, sem formatação especial — apenas a linha de cabeçalho da tabela vem em negrito. Além das contas e grupos do plano de contas, a tabela traz duas linhas de total: `TOTAL DO ATIVO` (`3.9.9.99.99-3`, soma dos grupos 1 e 3) e `TOTAL DO PASSIVO` (`9.9.9.99.99-5`, soma dos grupos 4, 6, 7, 8 e 9).

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `Número da Conta` | string | `"1.1.2.80.00.010.001-8"` | Número da conta no plano de contas, com dígito verificador. As linhas de grupo trazem o número do nível correspondente — por exemplo `1-7` (ATIVO) e `1.1-6` (DISPONIBILIDADES). |
| `Nome da Conta` | string | `"Conta Caixa - Banco Exemplo"` | Nome descritivo da conta contábil. |
| `Tipo da Conta` | string (enum) | `"A"` | Tipo da linha: `"A"` para conta analítica; `"S"` para conta sintética (agrupadora). |
| `Saldo em Término de {Data de Início}` | número | `40000.00` | Saldo da conta na Data de Início, em reais. Negativo indica saldo de natureza contrária à conta. |
| `Movimentos de Débito` | número | `5000.00` | Soma dos lançamentos a débito no período (em reais). O sinal segue a natureza da conta: positivo nas contas devedoras, negativo nas credoras. |
| `Movimentos de Crédito` | número | `0.00` | Soma dos lançamentos a crédito no período (em reais). Sinal invertido em relação à coluna de débito: negativo nas contas devedoras, positivo nas credoras. |
| `Saldo em Término de {Data Final}` | número | `45000.00` | Saldo da conta na Data Final, em reais. |

---

# Demonstrativo de Caixa

URL: /documentation/iaas/relatorios_dtvm/cash_account_demonstrative

## Visão Geral

O relatório `cash_account_demonstrative` é um extrato diário das movimentações e saldos das contas bancárias do fundo ao fim do dia. Ele é gerado uma vez por dia, após o encerramento do ciclo financeiro, e apresenta os saldos de abertura (D-1) e encerramento (D0) de cada conta, além de todas as transações ocorridas ao longo do dia. Gestores e administradores utilizam este relatório para conferir a posição de caixa e conciliar as movimentações financeiras do fundo.

O relatório pode ser gerado em modo de fundo único ou em modo multi-fundo. No modo multi-fundo, cada classe de fundo é apresentada em uma aba separada dentro da mesma planilha.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX |
| Aba | `Demonstrativo de Caixa` (no modo multi-fundo, uma aba por fundo, nomeada com os 31 primeiros caracteres do nome do fundo — o limite do Excel para nome de aba) |
| Nomenclatura | `{nome_resumido_fundo}_cash_account_demonstrative_{AAAA-MM-DD}.xlsx` |

:::tip Versão para conciliação automatizada

Este relatório é uma planilha formatada para leitura. Para conciliar as movimentações de forma automatizada — com identificador de transação, tipo, status de conciliação e saldos antes e depois de cada lançamento — utilize o relatório [Movimentações de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements), em CSV.

:::

## Conteúdo da Planilha

Cada aba da planilha (uma por fundo) contém as seguintes seções:

### Cabeçalho do Fundo

Apresentado no topo da aba, com as informações de identificação da classe de fundo:

| Campo | Descrição |
|-------|-----------|
| Data de referência | Data de referência do relatório no formato `YYYY-MM-DD`. |
| Nome da classe de fundo | Nome completo da classe de fundo. |
| CNPJ da classe de fundo | CNPJ da classe de fundo. |
| Nome da gestora | Nome da gestora responsável pelo fundo. |
| CNPJ da gestora | CNPJ da gestora responsável pelo fundo. |

### Extrato por Conta Bancária

Abaixo do cabeçalho, sob o título **Extrato**, é exibida uma tabela por conta bancária do fundo, com as seguintes colunas:

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `Data de referência` | data | `2026-07-29` | Data de referência do relatório. |
| `Banco` | string | `"999 - BANCO EXEMPLO S.A."` | Código COMPE e nome da instituição financeira, no formato `{código} - {nome}`. |
| `Agência/Conta` | string | `"0001/4417206-9"` | Número da agência e da conta, no formato `{agência}/{conta}-{dígito}`. |
| `Descrição` | string | `"Liquidação de parcelas"` | Descrição da movimentação conforme o grupo de conciliação da transação. |
| `Identificador do Pix` | string | `"E99999999202607291200ABCDEFGHIJK"` | Identificador fim a fim (`end_to_end_id`) da transação Pix. Vazio quando a movimentação não é um Pix. |
| `Valor (R$)` | número | `2417.86` | Valor da movimentação em reais. Valores negativos indicam saída de caixa. |

Cada tabela de conta exibe ainda três linhas de resumo, em negrito e com fundo cinza. Nessas linhas, o rótulo (`Saldo D-1`, `Total`, `Saldo D0`) ocupa a primeira coluna, no lugar da data de referência:

| Linha | Posição | Descrição |
|-------|---------|-----------|
| **Saldo D-1** | primeira linha da tabela | Saldo da conta ao início do dia (encerramento do dia anterior). |
| **Total** | após as movimentações | Soma de todas as movimentações do dia para a conta. |
| **Saldo D0** | última linha da tabela | Saldo da conta ao encerramento do dia de referência. |

---

# Movimentações de Caixa

URL: /documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements

## Visão Geral

O relatório `cash_account_demonstrative_movements` lista, transação a transação, todas as movimentações das contas bancárias do fundo na data de referência. É a versão tabular do [Demonstrativo de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative): enquanto o demonstrativo é uma planilha formatada para leitura, este arquivo é um CSV pensado para conciliação automatizada, com o identificador de cada transação, o tipo, o status de conciliação e os saldos antes e depois do lançamento.

:::info Janela do dia

São consideradas as transações registradas entre 03:00 (UTC) da data de referência e 03:00 (UTC) do dia seguinte — ou seja, o dia inteiro no horário de Brasília. As linhas vêm ordenadas por data e hora da transação.

:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_cash_account_demonstrative_movements_{AAAA-MM-DD}.csv` |

:::caution Valores em centavos

As colunas `amount`, `previous_balance` e `post_balance` são números **inteiros em centavos** — `241786` significa R$ 2.417,86. Diferente dos demais relatórios, que trazem valores em reais.

:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `fund_class_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_class_document_number` | string | `"11.222.333/0001-81"` | CNPJ da classe de fundo. |
| `account_number` | string | `"4417206"` | Número da conta bancária, sem o dígito. |
| `account_digit` | string | `"9"` | Dígito verificador da conta. |
| `account_branch` | string | `"0001"` | Agência da conta. |
| `if_name` | string | `"BANCO EXEMPLO S.A."` | Nome da instituição financeira. |
| `if_code` | string | `"999"` | Código COMPE da instituição financeira. |
| `if_ispb` | string | `"99999999"` | ISPB da instituição financeira. |
| `transaction_key` | string | `"30c40d50-0001-4ddd-9444-000000000401"` | Identificador único da transação na QI DTVM (UUID). |
| `external_key` | string | `"40d50e60-0001-4eee-9555-000000000501"` | Identificador da transação na instituição financeira de origem. |
| `transaction_description` | string | `"Liquidação de parcelas de CCB"` | Descrição da transação conforme informada pela instituição financeira. |
| `transaction_type` | string (enum) | `"incoming_pix"` | Tipo da transação. Ver [tabela de tipos](#tipos-de-transacao). |
| `transaction_status` | string (enum) | `"reconciled"` | Status de conciliação: `created`, `pending_conciliation` ou `reconciled`. |
| `amount` | inteiro (centavos) | `241786` | Valor da transação. Negativo indica saída de caixa. |
| `previous_balance` | inteiro (centavos) | `52811947` | Saldo da conta antes da transação. |
| `post_balance` | inteiro (centavos) | `53053733` | Saldo da conta após a transação. |
| `transaction_datetime` | data | `2026-07-29` | Data e hora da transação. **No arquivo, o campo é exportado apenas com a data**, no formato `AAAA-MM-DD`. |
| `accounting_date` | data | `2026-07-29` | Data contábil atribuída à transação. |
| `conciliation_description` | string | `"Liquidação de parcelas"` | Descrição do grupo de conciliação ao qual a transação foi associada. Vazio enquanto a transação não é conciliada. |

## Tipos de transação

| Valor | Descrição |
|-------|-----------|
| `incoming_pix` | Pix recebido. |
| `outgoing_pix` | Pix enviado. |
| `incoming_wire_transfer` | TED recebida. |
| `outgoing_wire_transfer` | TED enviada. |
| `outgoing_bank_slip_payment` | Pagamento de boleto. |
| `incoming_bank_slip_payment_reversal` | Estorno de pagamento de boleto. |
| `outgoing_bankslip_registration` | Custo de registro de boleto. |
| `outgoing_bankslip_payment` | Custo de pagamento de boleto. |
| `outgoing_bankslip_due_date_extension` | Custo de prorrogação de vencimento de boleto. |
| `outgoing_bankslip_permanence` | Custo de permanência de boleto. |
| `outgoing_bankslip_rebate` | Custo de abatimento de boleto. |
| `outgoing_bankslip_write_off` | Custo de baixa de boleto. |
| `outgoing_ted_fee` | Tarifa de TED enviada. |
| `outgoing_pix_fee` | Tarifa de Pix enviado. |
| `incoming_pix_fee` | Tarifa de recebimento de Pix. Apesar do prefixo `incoming`, é uma saída de caixa. |
| `incoming_reversal` | Estorno recebido de uma transação enviada. |
| `incoming_pix_reversal` | Devolução recebida de um Pix enviado. |
| `outgoing_pix_block` | Bloqueio de valor relacionado a Pix. |
| `incoming_pix_unblock` | Desbloqueio de valor bloqueado por Pix. |

---

# Aquisição Consolidada de Direitos Creditórios

URL: /documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets

## Visão Geral

O relatório `consolidated_credit_rights_acquisition_assets` lista os direitos creditórios adquiridos pelo fundo na data de referência, com os valores de compra, o spread e as características da operação. Em um único arquivo, ele reúne três naturezas de ativo:

- **operações de crédito** (ex: CCB) — uma linha por **parcela** adquirida;
- **direitos creditórios descontados** (ex: duplicatas) — uma linha por **ativo**, já que não têm parcelas;
- **títulos** (`commercial_paper`, `cri`, `cra`, `debenture`) — uma linha por parcela do cronograma do título, ou uma única linha quando o título não tem cronograma de parcelas.

Este relatório substitui os antigos `credit_rights_acquisition_assets`, `credit_rights_acquisition_installments` e `discounted_credit_rights_acquisition_assets`, que deixaram de ser entregues.

:::tip Também em PDF

Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](/downloads/manual_relatorios_qi_tech.pdf) — revisão 3, outubro de 2026. O manual cobre quatro relatórios: este, a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), a [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) e a [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets).

:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_consolidated_credit_rights_acquisition_assets_{YYYY-MM-DD}.csv` |

## O que o relatório traz

- Os ativos comprados na data de referência (`purchase_date` igual à data informada).
- Ativos inativos são excluídos.
- Campos sem valor vêm **vazios** no arquivo.

:::info Entrega de abertura

Quando o relatório é entregue no momento de **abertura**, a data de referência da entrega é o **dia útil imediatamente anterior** ao dia do fechamento. Essa mesma data vale para o conteúdo do arquivo (todas as naturezas de ativo), para o nome do arquivo e para o `reference_date` do [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega).

:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `reference_date` | data | `2026-07-29` | Data de compra do ativo. |
| `fund_class_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_class_document_number` | string | `"11.222.333/0001-81"` | CNPJ da classe de fundo. |
| `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora do ativo. |
| `originator_document_number` | string | `"22.222.222/0001-91"` | CNPJ do originador. |
| `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente. |
| `assignor_document_number` | string | `"33.333.333/0001-91"` | CNPJ do cedente. |
| `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor (tomador do crédito) ou do sacado. |
| `borrower_document_number` | string | `"969.698.790-03"` | CPF ou CNPJ do devedor/sacado. |
| `asset_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"` | Tipo do ativo. Determina qual natureza originou a linha. Para títulos: `commercial_paper`, `cri`, `cra` ou `debenture`. |
| `has_assignor_coobligation` | booleano | `False` | Indica se há coobrigação do cedente. Para títulos, sempre `False`. |
| `asset_key` | string | `"1a2b3c40-0001-4aaa-9111-000000000101"` | Chave interna do ativo gerada pela QI Tech (UUID). |
| `contract_number` | string | `"0900112233/EXA"` | Número do contrato (operação de crédito) ou do pedido (direito creditório descontado). Para direito creditório descontado sem número de pedido, cai no número do contrato. |
| `external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo da linha. Para operação de crédito, é o identificador externo da **parcela** quando ela tem um; caso contrário, o do ativo. Para as demais naturezas, é o identificador externo do ativo. |
| `asset_external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo. Igual em todas as linhas de um mesmo ativo. |
| `installment_number` | número | `1` | Número da parcela. Para direito creditório descontado, sempre `1`. |
| `issue_date` | data | `2026-07-28` | Data de emissão do contrato. Para direito creditório descontado, vem `-`. |
| `purchase_date` | data | `2026-07-29` | Data de compra do ativo pelo fundo. |
| `installment_maturity_date` | data | `2026-08-28` | Data de vencimento da parcela. Para direito creditório descontado, é o vencimento do próprio ativo. |
| `total_purchase_value` | número | `4712.35` | Valor total pago pelo ativo, incluindo encargos (em reais). Repete-se em todas as parcelas do mesmo ativo. |
| `asset_purchase_value` | número | `4690.8` | Valor do ativo sem encargos e sem spread (em reais). |
| `installment_purchase_value` | número | `1598.7421` | Valor de compra da parcela (em reais). Para direito creditório descontado e para títulos, é igual ao `total_purchase_value`. |
| `principal_value` | número | `1480.12` | Valor de principal da parcela (em reais). Para direito creditório descontado, vem **vazio**. |
| `face_value` | número | `1678.9` | Valor de face da parcela ou do ativo (em reais). |
| `index` | string (enum) | `"pre_fixed"` | Indexador / tipo de taxa de juros. Para direito creditório descontado, sempre `pre_fixed`. Para títulos, `pre_fixed` ou `post_fixed`. |
| `index_calendar_base` | string (enum) | `"calendar_365"`, `"calendar_360"`, `"workdays"` | Base de calendário usada na apropriação de juros. Para direito creditório descontado, sempre `workdays`. |
| `monthly_rate` | string | `"0.0231"` | Taxa mensal pré-fixada do contrato. Para direito creditório descontado, traz a **taxa de compra do recebível (TIR)**, e não uma taxa mensal — no exemplo, `0.19842300000000`. |
| `calendar_base` | string (enum) | `"calendar_365"` | Base de calendário do pré-fixado. Para direito creditório descontado, sempre `workdays`. |
| `iof_value` | string | `"52.40"` | Valor de IOF do contrato. Para direito creditório descontado, vem `-`; para títulos, `0`. |
| `maturity_date` | data | `2026-10-28` | Data de vencimento final do ativo. |
| `total_purchase_spread` | número | `21.55` | Spread de aquisição (`total_purchase_value − asset_purchase_value`), em reais. **Nunca negativo**: quando a diferença é menor que zero, o campo vem `0`. |

:::info Como cruzar as linhas de um mesmo ativo

As parcelas de uma operação de crédito repetem `asset_key`, `asset_external_id` e `contract_number`, e variam em `installment_number`, `installment_maturity_date`, `installment_purchase_value`, `principal_value` e `face_value` — e também em `external_id`, quando as parcelas têm identificador externo próprio. Use `asset_key` ou `asset_external_id` para agrupar. Os valores de nível de ativo (`total_purchase_value`, `asset_purchase_value`, `total_purchase_spread`) se repetem em todas as parcelas — **não devem ser somados** por linha.

:::

---

# Conciliação Consolidada de Direitos Creditórios

URL: /documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets

## Visão Geral

O relatório `consolidated_credit_rights_conciliation_assets` lista os eventos de pagamento dos direitos creditórios registrados em uma data contábil, mostrando o efeito de cada pagamento sobre o valor do ativo: valor antes, valor depois, redução e resultado contábil apurado. Em um único arquivo, ele reúne três naturezas de ativo:

- **operações de crédito** (ex: CCB);
- **direitos creditórios descontados** (ex: duplicatas);
- **títulos** (`commercial_paper`, `cri`, `cra`, `debenture`).

Este relatório substitui os antigos `credit_rights_conciliation_assets`, `credit_rights_conciliation_installments` e `discounted_credit_rights_conciliation_assets`, que deixaram de ser entregues.

:::tip Também em PDF

Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](/downloads/manual_relatorios_qi_tech.pdf) — revisão 3, outubro de 2026. O manual cobre quatro relatórios: este, a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), a [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) e a [Aquisição Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets).

:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. Sem `end_date`, é o único dia do relatório; com `end_date`, é o primeiro dia do intervalo. |
| `end_date` | não | Data final do intervalo, no formato `AAAA-MM-DD`, igual ou posterior a `reference_date`. Quando informada, o relatório traz os eventos de `reference_date` até `end_date`, incluindo os dois dias. |

:::info Intervalo de datas

O intervalo está disponível na solicitação pelo Portal do Gestor: em **Carteira > Gerar Relatório**, escolha **Liquidados e baixados** e informe **Data de Início** e **Data de Fim**. O arquivo chega por e-mail com os eventos do intervalo inteiro. Nas rotinas de entrega, o relatório traz sempre um único dia: a data de referência da entrega.

:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_consolidated_credit_rights_conciliation_assets_{YYYY-MM-DD}.csv`, com a `reference_date` — num intervalo, o primeiro dia. |

## O que o relatório traz

- Os eventos de pagamento cuja data contábil é a data de referência — ou, com `end_date`, qualquer data de `reference_date` a `end_date`, incluindo as duas.
- Considera os ativos nas situações **ativo**, **vendido**, **liquidado** e **baixado**.
- Cada linha é **um evento de pagamento** — um mesmo ativo pode aparecer em várias linhas no mesmo dia. Num intervalo, a coluna `reference_date` traz a data contábil de cada evento, e não a data de referência pedida.

:::info Campos sem valor vêm como `-`

Diferente dos outros relatórios em CSV, este preenche os campos nulos com `-` em vez de deixá-los vazios.

:::

:::info Entrega de abertura

Quando o relatório é entregue no momento de **abertura**, a data de referência da entrega é o **dia útil imediatamente anterior** ao dia do fechamento. Essa mesma data vale para o conteúdo do arquivo (todas as naturezas de ativo), para o nome do arquivo e para o `reference_date` do [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega).

:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `reference_date` | data | `2026-07-29` | Data contábil do evento de pagamento. |
| `fund_class_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_class_document_number` | string | `"11.222.333/0001-81"` | CNPJ da classe de fundo. |
| `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora do ativo. |
| `originator_document_number` | string | `"22.222.222/0001-91"` | CNPJ do originador. |
| `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente. |
| `assignor_document_number` | string | `"33.333.333/0001-91"` | CNPJ do cedente. |
| `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor (tomador do crédito) ou do sacado. |
| `borrower_document_number` | string | `"969.698.790-03"` | CPF ou CNPJ do devedor/sacado. |
| `asset_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"` | Tipo do ativo. Determina qual natureza originou a linha. Para títulos: `commercial_paper`, `cri`, `cra` ou `debenture`. |
| `asset_key` | string | `"1a2b3c40-0003-4aaa-9111-000000000103"` | Chave interna do ativo gerada pela QI Tech (UUID). |
| `external_id` | string | `"10a20b30-0003-4bbb-9222-000000000203"` | Para operação de crédito, identificador externo da **parcela** paga, conforme registrado no evento de pagamento — vem `-` quando o evento não traz esse identificador. Para as demais naturezas, identificador externo do ativo. |
| `asset_external_id` | string | `"10a20b30-0003-4bbb-9222-000000000203"` | Identificador externo do ativo. Use este campo, e não `external_id`, para cruzar com os outros relatórios por ativo. |
| `contract_number` | string | `"0900098765/EXC"` | Número do contrato (operação de crédito) ou do pedido (direito creditório descontado). Para direito creditório descontado sem número de pedido, cai no número do contrato. |
| `maturity_date` | data | `2027-01-11` | Data de vencimento final do ativo. |
| `total_purchase_value` | número | `5324.8` | Valor total pago pelo fundo na aquisição do ativo (em reais). |
| `purchase_date` | data | `2026-01-12` | Data de aquisição do ativo pelo fundo. |
| `internal_rate_of_return` | número | `0.0231` | Taxa interna de retorno do ativo. Operação de crédito: taxa corrente. Direito creditório descontado: taxa de compra do recebível. Títulos: `-`. |
| `payment_date` | data | `2026-07-29` | Data contábil do pagamento. Traz sempre o mesmo valor de `reference_date`. |
| `payment_amount` | número | `512.68` | Valor pago no evento (em reais). |
| `payment_key` | string | `"20b30c40-0001-4ccc-9333-000000000301"` | Chave interna do evento de pagamento gerada pela QI Tech (UUID). |
| `payment_type` | string (enum) | `"installment_settlement"`, `"installment_amortization"`, `"asset_settlement"`, `"asset_amortization"`, `"fine_payment"`, `"gloss"`, ... | Tipo do pagamento. |
| `payment_event_type` | string (enum) | `"settlement"`, `"substitution"`, `"repurchase"`, `"extension"`, `"unperformed"`, `"reactivation"`, `"installment_payment_reversal"`, `"asset_payment_reversal"`, `"bankslip"` | Natureza do evento que originou o pagamento — por exemplo, liquidação, substituição, recompra, prorrogação ou inadimplemento. Eventos anteriores à criação deste campo vêm como `-`. |
| `old_asset_current_value` | número | `5361.42` | Valor contábil do ativo imediatamente **antes** do evento (em reais). |
| `new_asset_current_value` | número | `4890.33` | Valor contábil do ativo imediatamente **depois** do evento (em reais). |
| `asset_reduction_value` | número | `471.09` | Redução do valor contábil do ativo (`old − new`), em reais. |
| `result_value` | número | `41.59` | Resultado contábil apurado no evento (em reais). |
| `written_off_accounting_result_value` | número inteiro | `0` | Resultado contábil de baixa (*write-off*) associado ao evento, **em centavos** — este é o único campo monetário do arquivo que não é convertido para reais. Para direito creditório descontado e para títulos, sempre `0`. |
| `installment_number` | string | `"1"` | Número da parcela liquidada. Para direito creditório descontado, é o sufixo do número do pedido quando ele existe (`8977-3` → `3`); caso contrário, `-`. Para títulos, é a parcela registrada no evento de pagamento. |
| `end_to_end_id` | string | `"-"` | Identificador *end-to-end* da transação de pagamento, quando registrado no evento; caso contrário, `-`. |

:::tip Conferindo o resultado do dia

A soma de `result_value` é o resultado contábil reconhecido pelos direitos creditórios na data, e deve fechar com as contas de receita correspondentes no [Relatório de Balanço](/documentation/iaas/relatorios_dtvm/balance_report) e na [Razão Contábil](/documentation/iaas/relatorios_dtvm/accounting_ledger). A soma de `asset_reduction_value` é a variação do estoque explicada por pagamentos no dia.

:::

---

# Relatórios DTVM

URL: /documentation/iaas/relatorios_dtvm/

Os relatórios DTVM fornecem uma visão detalhada das operações e posições financeiras dos fundos de investimento administrados pela QI DTVM. Eles são destinados a gestores e analistas que precisam acompanhar a composição da carteira, as aquisições e liquidações de ativos, e a movimentação de caixa do fundo em cada data de referência.

## Exemplos de relatórios

Baixe exemplos de todos os relatórios disponíveis: [example_reports.zip](/downloads/example_reports.zip)

O pacote contém um arquivo de cada relatório, com o mesmo layout dos arquivos gerados em produção e dados fictícios. Todos descrevem o mesmo fundo (`FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA`) na mesma data de referência (`2026-07-29`). Os relatórios de posição — composições de carteira, cotas, caixa e XMLs ANBIMA — fecham entre si: patrimônio líquido, saldo de caixa e posição por classe de ativo são os mesmos em todos eles. O balancete e o razão contábil usam um conjunto próprio de lançamentos, só para ilustrar o layout.

## Nomenclatura dos arquivos

Todos os arquivos seguem o padrão `{nome_resumido_fundo}_{modelo}_{data_de_referência}.{extensão}`, onde:

- **nome resumido do fundo** é o nome-base de relatórios cadastrado para a classe de fundo, em minúsculas e sem acentos (nos exemplos, `example_name`);
- **modelo** é o nome do relatório, conforme a coluna "Modelo" da tabela abaixo;
- **data de referência** está no formato `AAAA-MM-DD`.

O prefixo vem do cadastro da classe, não da configuração da entrega. Se você precisa de um prefixo diferente, fale com o time de integração. Entregas configuradas em inglês recebem o sufixo `_EN` antes da extensão.

Há quatro exceções ao padrão: o `wallet_composition_by_composition` é entregue como `wallet_composition` (sem o sufixo do modelo); o `xml_5_by_composition` segue o nome do padrão ANBIMA, `FD{CNPJ do fundo, só dígitos}_{AAAAMMDD}.xml`; o `assignment_assets_wallet_composition` acrescenta o identificador da cessão ao final do nome; e o `assignment_documents` coloca o identificador da cessão **antes** da data, que nele é a data de geração do arquivo.

:::info Relatórios de período

`quota_mec`, `balance_report` e `accounting_ledger` são gerados a partir de um intervalo (`start_date` / `end_date`), e não de uma única data. Nesses casos, a data no nome do arquivo é a `reference_date` informada na rotina; quando a rotina não informa `reference_date`, é a data de geração do arquivo, no horário de Brasília. A [Conciliação Consolidada](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets) aceita, opcionalmente, um intervalo (`reference_date` / `end_date`); o nome do arquivo leva a `reference_date`, o primeiro dia do intervalo.

:::

## Convenções dos arquivos CSV

Valem para todos os relatórios em CSV:

| Atributo | Padrão |
|----------|--------|
| Encoding | UTF-8, **sem BOM** |
| Delimitador | `,` (vírgula) |
| Separador decimal | `.` (ponto) |
| Fim de linha | `CRLF` (`\r\n`) |
| Cabeçalho | sempre presente, na primeira linha, com os nomes das colunas em minúsculas |

:::info Delimitador e separador decimal são configuráveis

Se o seu processo exigir `;` como delimitador ou `,` como separador decimal, a QI DTVM pode configurar isso por fundo na entrega. Sem configuração específica, valem os padrões da tabela acima. As exceções são o `quota_mec` em CSV, que usa `;` por definição do relatório, e o `assignment_documents`, que usa sempre `,` como delimitador e `.` como separador decimal.

:::

## Como os relatórios são entregues

A entrega é organizada em **rotinas**, configuradas por fundo. Cada rotina define três coisas: **quais** relatórios entram, com **qual periodicidade**, e para **qual destino**.

| Elemento | Opções |
|----------|--------|
| Periodicidade | diária · semanal (primeiro dia útil da semana) · mensal (último dia útil do mês) |
| Destino | SFTP · e-mail |

Um mesmo fundo pode ter mais de uma rotina — por exemplo, uma diária em SFTP e uma mensal por e-mail. Para incluir ou remover um relatório, mudar a periodicidade ou o destino, entre em contato com o time de integração.

### Quando a rotina é disparada

O gatilho é o **fechamento do dia daquele fundo**, e não um horário fixo. O fechamento acontece somente em dia útil, e dispara os relatórios em três momentos distintos:

| Momento | Contém |
|---------|--------|
| Pré-cota | Relatórios apurados antes do cálculo da cota do dia. |
| Fechamento | Relatórios da posição consolidada do dia, com a cota de fechamento. |
| Abertura | Relatórios apurados sobre a cota de abertura. |

Os relatórios do momento de abertura têm como data de referência o **dia útil anterior** à data contábil que está sendo aberta — é essa data que aparece no nome do arquivo.

Cada relatório é entregue no momento previsto na configuração da rotina do fundo — é por isso que os arquivos de um mesmo dia não chegam todos juntos. Uma rotina semanal ou mensal só materializa arquivos na data em que a periodicidade dela cai; nos outros dias o fechamento roda e ela não produz nada.

### Relatórios fora da rotina

Dois relatórios não seguem a periodicidade da rotina, porque não são do dia do fundo e sim de uma operação: a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) e os [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents). Os dois são gerados quando a cessão entra na etapa de aprovação, desde que estejam habilitados na configuração de cessão, e são entregues no destino definido na configuração de cessão.

Eles **não** emitem o [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega) — o acompanhamento é pelo [webhook de status do lote de cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks).

### Entrega via SFTP

Cada arquivo é gravado na pasta configurada para o fundo, com exatamente o nome descrito acima. Para instruções de conexão, credenciais e exemplos de código para download, consulte a [documentação de integração SFTP](/documentation/iaas/integracao_sftp/inicio).

:::tip Você pode ser avisado a cada entrega concluída

Em vez de varrer a pasta em intervalos fixos, configure o [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega): ao fim de cada entrega, a QI DTVM notifica a sua aplicação com a lista de arquivos gravados e o status de cada relatório.

:::

## Relatórios disponíveis

| Relatório | Descrição | Modelo | Formato do arquivo |
|-----------|-----------|--------|-------------------|
| [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) | Posição completa de todos os ativos que compõem o estoque do fundo em uma data de referência, ativo a ativo. | `assets_wallet_composition` | CSV |
| [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) | Ativos de uma cessão específica, no mesmo formato da composição de carteira. Gerado por cessão, fora da rotina diária. | `assignment_assets_wallet_composition` | CSV |
| [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) | Documentos comprobatórios dos ativos de uma cessão, com link de download por arquivo. Gerado por cessão, fora da rotina diária. | `assignment_documents` | CSV |
| [Composição da Carteira](/documentation/iaas/relatorios_dtvm/wallet_composition) | Carteira consolidada do fundo ao fim do dia, por classe de ativo, com séries de emissão, valores a pagar e a receber, caixa, rentabilidade e resultado. | `wallet_composition_by_composition` | XLSX |
| [Aquisição Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) | Direitos creditórios adquiridos em um dia — operações de crédito por parcela e direitos creditórios descontados por ativo, no mesmo arquivo. | `consolidated_credit_rights_acquisition_assets` | CSV |
| [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets) | Eventos de pagamento dos direitos creditórios em uma data contábil, com o efeito de cada pagamento sobre o valor do ativo. | `consolidated_credit_rights_conciliation_assets` | CSV |
| [Demonstrativo de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative) | Extrato diário das movimentações e saldos das contas bancárias do fundo. | `cash_account_demonstrative` | XLSX |
| [Movimentações de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements) | Mesma movimentação do demonstrativo de caixa em formato tabular, transação a transação, para conciliação automatizada. | `cash_account_demonstrative_movements` | CSV |
| [Cotas MEC](/documentation/iaas/relatorios_dtvm/quota_mec) | Evolução diária de cotas, patrimônio e rentabilidade das séries de emissão. | `quota_mec` | XLSX ou CSV |
| [Relatório de Balanço](/documentation/iaas/relatorios_dtvm/balance_report) | Balanço contábil consolidado do fundo com saldos e movimentações por conta. | `balance_report` | XLSX |
| [Razão Contábil](/documentation/iaas/relatorios_dtvm/accounting_ledger) | Razão contábil detalhado com todos os lançamentos por conta no período. | `accounting_ledger` | XLSX |
| [XML ANBIMA (tipos 5 e 401)](/documentation/iaas/relatorios_dtvm/xml_anbima) | Arquivos de posição no padrão ANBIMA, gerados a partir da composição da carteira. | `xml_5_by_composition` `xml_401_by_composition` | XML |

---

# Cotas MEC

URL: /documentation/iaas/relatorios_dtvm/quota_mec

## Visão Geral

O relatório `quota_mec` apresenta a evolução diária das cotas e do patrimônio do fundo em um intervalo de datas, calculada com base nos fechamentos de série de emissão. Cada linha representa um dia útil de uma série de emissão, contendo valores de patrimônio bruto e líquido, cota de fechamento, movimentações de aplicação e resgate, come-cotas e rentabilidade acumulada diária, mensal e anual. Gestores e administradores utilizam este relatório para acompanhar a performance do fundo e enviar informações regulatórias ao MEC (Método de Envio de Cota).

O relatório pode ser gerado nos formatos XLSX (uma aba por classe de fundo) ou CSV. O CSV só é aceito quando o pedido cobre **uma única classe de fundo**.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `start_date` | sim | Data de início do período, no formato `AAAA-MM-DD`. |
| `end_date` | sim | Data de fim do período, no formato `AAAA-MM-DD`. Não pode ser anterior à data de início. |
| `include_secondary_market` | não | Booleano. Quando omitido, vale `true`. |
| `file_format` | não | `xlsx` (padrão) ou `csv`. O valor não é conferido na solicitação: qualquer outro formato, ou `csv` com mais de uma classe de fundo, faz a geração do relatório falhar. |
| `issuance_serie_key` | não | Restringe o arquivo a uma única série de emissão. |

:::caution É preciso haver cota no período

O relatório só é gerado se ao menos uma série de emissão da classe tiver valor de cota (de abertura ou de fechamento) dentro do intervalo. Sem isso a solicitação é recusada.

:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX ou CSV |
| Encoding | UTF-8 |
| Delimitador (CSV) | `;` (ponto e vírgula) |
| Nomenclatura | `{nome_resumido_fundo}_quota_mec_{AAAA-MM-DD}.xlsx` (ou `.csv`) |

No XLSX, cada classe de fundo ocupa uma aba, nomeada com o nome do fundo (limitado a 31 caracteres pelo Excel), o cabeçalho vem em português e as linhas em ordem cronológica crescente. Nos dois formatos, XLSX e CSV, as datas vêm no formato `DD/MM/AAAA` e os campos sem valor vêm como `0`.

:::info Variação no formato CSV

O CSV é gerado apenas para uma classe de fundo por arquivo e difere do XLSX em dois pontos: o cabeçalho vem com os **nomes técnicos em inglês** (`fund_class_name`, `fund_class_document_number`, `sub_class_name`, `issuance_serie_name`, `accounting_date`, `gross_net_worth`, `gross_quota_value`, `performance_fee_current_value`, `net_net_worth`, `net_quota_value`, `final_net_worth`, `final_quota_value`, `total_quotas`, `issued_quotas`, `total_daily_applications`, `redeemed_quotas`, `total_daily_redemptions`, `tax_anticipated_quotas`, `total_daily_tax_anticipations`, `total_daily_amortizations`, `daily_rentability`, `monthly_rentability`, `yearly_rentability`), na mesma ordem da tabela abaixo; e as linhas vêm em ordem **cronológica decrescente**, da data mais recente para a mais antiga.

:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `Nome do Fundo` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `CNPJ do Fundo` | string | `"11.222.333/0001-81"` | CNPJ da classe de fundo. |
| `Sub Classe` | string | `"SUBORDINADA"` | Nome da subclasse do fundo. |
| `Série de Emissão` | string | `"PRIMEIRA"` | Nome da série de emissão. |
| `Data de Referência` | data | `29/07/2026` | Data contábil de referência (apenas dias úteis). |
| `Patrimônio Bruto` | número | `10500000.00` | Patrimônio líquido bruto antes da provisão de taxa de performance (em reais). |
| `Cota Bruta` | número | `1.050000` | Valor da cota bruta antes da taxa de performance. |
| `Taxa de Performance` | número | `5000.00` | Valor corrente da taxa de performance provisionada (em reais). |
| `PL Pré Movimentação` | número | `10495000.00` | Patrimônio líquido antes das movimentações do dia (em reais). |
| `Cota Pré Movimentação` | número | `1.049500` | Valor da cota antes das movimentações do dia. |
| `PL de Fechamento` | número | `10495000.00` | Patrimônio líquido de fechamento antes das amortizações (em reais). |
| `Cota de Fechamento` | número | `1.049500` | Valor da cota de fechamento antes das amortizações. |
| `Total de Cotas` | número | `10000.00000` | Quantidade total de cotas da série, calculada como `PL de Fechamento / Cota de Fechamento`. É uma quantidade de cotas, não um valor em reais. |
| `Cotas Integralizadas` | número | `1000.00000` | Quantidade de cotas emitidas (aplicadas) no dia. |
| `Total Aplicado` | número | `1049500.00` | Valor total aplicado no dia (em reais). |
| `Cotas Resgatadas` | número | `500.00000` | Quantidade de cotas resgatadas no dia. |
| `Total Resgatado` | número | `524750.00` | Valor total resgatado no dia (em reais). |
| `Come-cotas` | número | `200.00000` | Quantidade de cotas consumidas pela antecipação de IR (come-cotas). |
| `Total de Come-cotas` | número | `200.00` | Valor total do come-cotas do dia (em reais). |
| `Total Amortizado` | número | `0.00` | Valor total amortizado no dia (em reais). |
| `Rentabilidade Diária` | número | `0.000420` | Rentabilidade do dia, calculada como `(cota_pré_movimentação / cota_fechamento_anterior) - 1`. |
| `Rentabilidade Mensal` | número | `0.005200` | Rentabilidade acumulada no mês corrente (base composta). Reinicia no início de cada mês. |
| `Rentabilidade Anual` | número | `0.063000` | Rentabilidade acumulada no ano corrente (base composta). Reinicia no início de cada ano. |

---

# Testando a Captura de Lastro

URL: /documentation/iaas/relatorios_dtvm/testar_captura_lastro

Esta página é um roteiro para quem está construindo a leitura automatizada dos [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) e precisa de um `document_url` que funcione de verdade para testar antes de ir a produção.

A ideia é simples: em sandbox, você roda uma cessão de ponta a ponta usando os PDFs de exemplo que disponibilizamos abaixo. O `assignment_documents` é gerado pelo mesmo código que gera o relatório em produção, com links pré-assinados legítimos — nada é montado à mão.

:::info Por que não entregamos um arquivo pronto com links

`document_url` é uma URL pré-assinada de S3, gerada no momento em que o relatório é produzido e válida por 5 dias. Um arquivo estático com links reais expiraria antes de chegar até você. Rodando o roteiro, você gera links novos sempre que precisar.

:::

## O que você precisa ter em sandbox

Este teste usa o fluxo normal de cessão, então ele pressupõe o mesmo setup de qualquer integração:

| Item | Como obter |
|------|------------|
| Classe de fundo (`fund_class_key`) | Fornecida pelo time de integração. |
| Configuração de cessão (`assignment_configuration_key`) | Fornecida pelo time de integração. Ela define o tipo de ativo da cessão e quais documentos são exigidos. |
| `assignment_documents` na rotina de relatórios da configuração | Peça ao time de integração para incluir o relatório na configuração de cessão. Sem isso o arquivo não é gerado. |
| Destino de entrega (SFTP) | Configurado junto com a rotina de relatórios. Veja a [integração SFTP](/documentation/iaas/integracao_sftp/inicio). |

:::caution Não há atalho para o setup

Não existe caminho que produza um `document_url` real sem uma cessão real em sandbox — o relatório é uma consulta aos documentos efetivamente anexados aos ativos daquela cessão. Se o seu objetivo é apenas conferir a estrutura das colunas, use o [pacote de exemplos](/documentation/iaas/relatorios_dtvm/) da introdução, que traz o CSV com URL de exemplo no formato correto.

:::

## Arquivos de exemplo

Um documento por `document_type`, com dados fictícios, texto extraível (não são imagem) e a estrutura típica de cada tipo:

[📦 Baixar todos (lastros_exemplo.zip)](/downloads/lastros_exemplo.zip)

| Arquivo | `document_type` | O que é |
|---------|-----------------|---------|
| [ccb_exemplo_01.pdf](/downloads/lastros_exemplo/ccb_exemplo_01.pdf) | `ccb` | CCB emitida pela QI SCD, 3 parcelas, 22 páginas com cadeia de endossos |
| [ccb_exemplo_02.pdf](/downloads/lastros_exemplo/ccb_exemplo_02.pdf) | `ccb` | CCB emitida pela QI SCD, 2 parcelas, 22 páginas com cadeia de endossos |
| [duplicata_mercantil_exemplo.pdf](/downloads/lastros_exemplo/duplicata_mercantil_exemplo.pdf) | `duplicata_mercantil` | Duplicata mercantil com chave de acesso da NF-e |
| [invoice_exemplo.pdf](/downloads/lastros_exemplo/invoice_exemplo.pdf) | `invoice` | DANFE da NF-e referenciada pela duplicata |
| [duplicata_servicos_exemplo.pdf](/downloads/lastros_exemplo/duplicata_servicos_exemplo.pdf) | `duplicata_servicos` | Duplicata de prestação de serviços, referenciando NFS-e |
| [cte_exemplo.pdf](/downloads/lastros_exemplo/cte_exemplo.pdf) | `cte` | DACTE |
| [discounted_contract_exemplo.pdf](/downloads/lastros_exemplo/discounted_contract_exemplo.pdf) | `discounted_contract` | Contrato de prestação de serviços com cláusula de cessão |

:::danger Estes arquivos são fictícios

Nenhum deles tem validade jurídica ou fiscal, nenhum foi transmitido à SEFAZ e nenhum contém dados de pessoas ou empresas reais. Servem exclusivamente para teste de leitura.

:::

Os dois PDFs de `ccb` são consistentes com o `example_reports.zip` publicado na [introdução aos relatórios](/documentation/iaas/relatorios_dtvm/): mesmos números de contrato (`0900112233/EXA` e `0900112247/EXB`), mesmos valores de parcela, mesmos vencimentos e mesma taxa mensal que aparecem no `assignment_assets_wallet_composition` de exemplo.

:::tip As CCBs de exemplo seguem o layout real de emissão da QI Tech

Os dois PDFs de `ccb` são a estrutura de verdade de uma CCB emitida pela **QI Sociedade de Crédito Direto S.A.** — os Quadros I a XI na ordem em que aparecem no documento real, com o texto integral das condições gerais e especiais, a página de assinatura eletrônica do emitente e a **cadeia de endossos** até o fundo. É o documento que o seu leitor vai encontrar em produção quando o originador emite pela QI Tech, com os dados trocados por fictícios.

Três partes que costumam ser as mais úteis para validação de lastro:

- **Quadro V, item 5** — a tabela com as datas possíveis de liberação. Cada linha tem seu próprio Valor Total, IOF, Valor Líquido e CET; a linha que vale é a da data em que os recursos foram efetivamente liberados. Um leitor que assuma uma linha só extrai o valor errado.
- **Quadro V, item 13** — o demonstrativo do CET, que reconcilia com a **primeira** linha da tabela do item 5.
- **Endossos (últimas páginas)** — a cadeia `QI SCD → cedente → fundo`, cada elo com sua própria página de assinatura digital (hash, data, signatários). É por aí que se comprova a titularidade do título pelo fundo.

O `document_type` do relatório continua sendo a fonte de verdade sobre o tipo — não tente inferir da estrutura interna.

:::

:::caution Duas duplicações do template foram preservadas de propósito

O template de produção repete palavras em dois pontos, e os exemplos reproduzem isso:

- item 1.1 do Quadro V — `2,3100% % a.m. (dois inteiros e três mil e cem décimos de milésimo por cento por cento)`, com `%` e `por cento` duplicados;
- item 2 do Quadro V — `2. Prazo: 91 dias dias corridos.`

Não é erro destes arquivos. Mantivemos como está para o seu leitor encontrar em sandbox exatamente o texto que vai encontrar em produção — se você normalizar o texto antes de casar o padrão, esses dois campos são os que mais provavelmente quebram. Quando o template for corrigido, os exemplos são regerados.

:::

:::info CPF e CNPJ destes PDFs têm dígito verificador válido

Para não reprovar em validações de lastro que conferem dígito verificador, os CPFs e CNPJs impressos nestes PDFs têm DV válido, e as chaves de acesso de NF-e e CT-e também. Todos são fictícios.

Consequência: o `borrower_document` do `assignment_assets_wallet_composition` do pacote de exemplos difere do CPF impresso no PDF nos dois últimos dígitos. Se você está testando o cruzamento entre os dois arquivos, use `asset_external_id`, `asset_key`, número de contrato, valores e vencimentos — não o documento do sacado.

:::

## Roteiro

### 1. Crie a cessão

Chame `POST /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment`. O `external_id` que você informar aqui é o mesmo que vai aparecer na coluna `assignment_external_id` do relatório e no nome do arquivo. Detalhes em [Criação da Cessão](/documentation/iaas/negociacao_recebiveis/assignment/criacao).

### 2. Insira o ativo

Chame `POST .../assignment/{assignment_external_id}/asset`, uma vez por ativo. O payload depende do tipo de ativo da sua configuração de cessão — veja [Criação de Ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) para operação de crédito, ou as páginas de [duplicata](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata), [CT-e](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte) e [contrato descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract).

Guarde o `external_id` do ativo: ele é a chave de junção com os outros relatórios.

### 3. Anexe o documento de exemplo

Converta o PDF escolhido para Base64:

```bash
base64 -w 0 ccb_exemplo_01.pdf > ccb_exemplo_01.b64
```

Envie o arquivo com `POST .../assignment/{assignment_external_id}/asset/{asset_external_id}/document`:

```json title="Request Body"
{
    "document_type": "ccb",
    "document_b64": "JVBERi0xLjcKJfCflqQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..."
}
```

Os tipos aceitos em `document_type` são os que a **sua** configuração de cessão exige, não a lista completa de tipos existentes. Detalhes e erros possíveis em [Envio do Lastro do Ativo](/documentation/iaas/negociacao_recebiveis/asset/documents).

:::info Duplicatas mercantis podem não passar por aqui

Para ativos do tipo `duplicata_mercantil`, a plataforma pode gerar a documentação automaticamente a partir dos dados da nota fiscal — nesse caso não há upload a fazer, e o lastro aparece no relatório sem você anexar nada.

Isso **depende da configuração de cessão**: em algumas configurações a geração automática não acontece e o documento é esperado por upload. Confirme com o time de integração qual dos dois casos se aplica à sua antes de montar o teste. Independente disso, os PDFs de `duplicata_mercantil` e `invoice` deste pacote servem como referência de estrutura para o seu leitor.

:::

### 4. Encerre a inserção

Chame `PUT .../assignment/{assignment_external_id}` com o status de encerramento:

```json title="Request Body"
{
    "assignment_status": "completed_assets_insertion"
}
```

A partir daqui a cessão segue para a elegibilidade e para a aprovação — veja [Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento) e [Aprovação da cessão](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao).

### 5. Receba o arquivo

O `assignment_documents` é gerado quando a cessão passa pela etapa de aprovação e entregue no destino definido na configuração de cessão, com o nome:

```text
{nome_resumido_fundo}_assignment_documents_{external_id}_{AAAA-MM-DD}.csv
```

É o CSV com os links — os PDFs em si não são transferidos para o SFTP. Instruções de conexão e exemplos de download em [Integração SFTP](/documentation/iaas/integracao_sftp/inicio).

:::danger O arquivo espera na pasta, os links não

Este é o ponto de atenção mais importante da entrega por SFTP. A validade de 5 dias dos links começa a contar na **geração** do relatório, não na hora em que você busca o arquivo. O CSV continua na pasta indefinidamente, mas um arquivo coletado no sexto dia traz links que já não funcionam.

Colete o arquivo assim que ele chegar, ou trate o erro de link expirado como sinal de que o relatório precisa ser gerado novamente — e não como falha do seu leitor.

:::

:::caution Este relatório não emite o Webhook de Entrega

O [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega) cobre as rotinas de relatório do fundo, e não as entregas geradas por cessão. Para o `assignment_documents` não há aviso de arquivo disponível.

O sinal mais próximo é o [webhook de status do lote de cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). Em fluxos com aprovação manual, a passagem para `pending_consultant_approval` ou `pending_manager_approval` marca a entrada na etapa de aprovação, que é quando o relatório é gerado — use esse evento para agendar a coleta. Em fluxos com aprovação automática esses dois status não ocorrem, e o sinal utilizável é o status seguinte do lote no seu fluxo. Em ambos os casos o arquivo aparece na pasta em seguida, não no mesmo instante do webhook.

:::

## O que validar no seu leitor

Três comportamentos do `document_url` que costumam quebrar implementações e que você consegue exercitar com o arquivo que acabou de receber:

**Os links expiram em 5 dias.** O prazo conta a partir da geração do relatório. Passado o prazo o link retorna erro e é preciso gerar o relatório novamente. O identificador estável do documento é o `document_key` — nunca a URL. Se você precisa arquivar o lastro, baixe os arquivos dentro da janela.

**O nome do arquivo baixado não identifica o formato com segurança.** O download vem com `Content-Disposition: attachment; filename="{document_type}-{asset_external_id}.pdf"` (acentos são removidos e os demais caracteres fora de `A-Z a-z 0-9 . _ -` viram `_`). Não infira o tipo pelo nome nem pelo `Content-Type` — use a coluna `document_type` do CSV.

**Um ativo pode ocupar mais de uma linha.** Quando o ativo tem mais de um documento, ele aparece repetido, com o mesmo `asset_key` e `document_type` diferente. Ativos sem documento anexado não aparecem, e ativos descartados (`discarded`) ou reprovados (`denied`) são excluídos do arquivo.

:::caution `document_url` não é sempre uma URL

Se a assinatura do link falhar no momento em que o relatório é gerado, a coluna vem preenchida com uma **mensagem de erro em texto** — `Erro: Credenciais não configuradas corretamente.` —, não com uma URL — e o CSV é entregue normalmente, com as outras colunas íntegras.

Trate `document_url` como campo não confiável: valide que o valor começa com `https://` antes de tentar baixar. Uma linha nessa condição significa que aquele documento precisa ser obtido em uma nova geração do relatório, não que o arquivo não exista. Um leitor que assuma "toda linha tem URL válida" quebra no primeiro caso desses.

:::

## Cruzando com a composição da cessão

Para validação de lastro, o cruzamento mais útil é entre este relatório e a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), pelas colunas `asset_external_id` e `asset_key`. Ativo que aparece na composição e não aparece no lastro é ativo sem documento anexado.

## Um limite deste teste

**Não existe um layout QI Tech DTVM por tipo de documento.** Os arquivos de lastro são os documentos originais do cedente ou do originador — a CCB emitida pelo originador, o DANFE gerado pelo ERP dele, o DACTE da transportadora. A DTVM armazena e valida esses arquivos, não os gera, e é por isso que a validação de cada tipo é configurada por template do nosso lado.

:::info "QI Tech" não é o mesmo que "QI Tech DTVM"

A distinção importa aqui. A QI Tech **emite** crédito por outras frentes — BaaS e LaaS — e essas emissões têm, sim, um layout próprio de CCB, que é o das CCBs de exemplo desta página. O que não existe é um layout definido pela **DTVM** para o lastro que ela recebe: quando o originador é a própria QI Tech, o documento segue o padrão daquela emissão; quando é outro originador, segue o padrão dele.

Ou seja: a CCB de exemplo é *um* layout de lastro possível — o mais provável, se o seu originador emite pela QI Tech — e não *o* layout que a DTVM exige.

:::

Consequência prática: o que você pode tratar como contrato estável é o CSV — colunas, tipos e semântica. O interior do PDF varia por originador. Se o seu fundo compra de mais de um originador, ou se o originador não emite pela QI Tech, teste também contra um arquivo real dele antes de fechar a implementação. Os outros cinco exemplos (duplicata, invoice, CT-e, contrato) reproduzem a estrutura típica de cada tipo, mas não vêm de um emissor específico — são referência de campos, não de layout.

---

# Composição da Carteira

URL: /documentation/iaas/relatorios_dtvm/wallet_composition

## Visão Geral

O relatório `wallet_composition_by_composition` é a foto consolidada da carteira do fundo ao fim do dia. Ele reúne, em uma única planilha, o patrimônio e a cota de cada série de emissão, a posição por classe de ativo (títulos públicos, emissões, operações de crédito, direitos creditórios descontados, contratos, cotas de fundo, swaps e imóveis), os valores a pagar e a receber, os saldos de caixa e a rentabilidade das séries — sempre com o percentual que cada linha representa do patrimônio líquido.

É o relatório usado por gestores e administradores para conferir o fechamento do dia: o somatório das seções de ativos, menos os valores a pagar e mais os valores a receber, reconcilia com o patrimônio líquido informado no cabeçalho.

:::info Base do relatório

O relatório é gerado a partir de uma **composição** de carteira já fechada — confirmada ou aguardando confirmação. Por padrão é usada a composição de cota de fechamento (`final_quota`); mediante configuração, também pode ser gerado sobre a composição de cota de abertura (`opening_quota`) ou pré-cota (`pre_quota`).

:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim, se não informar `composition_key` | Data de referência, no formato `AAAA-MM-DD`. |
| `composition_key` | alternativa à data | Identificador de uma composição específica. |
| `composition_type` | não | `final_quota` (padrão), `opening_quota` ou `pre_quota`. Qualquer outro valor é recusado. |

:::caution É preciso existir composição na data

Se não houver composição do tipo pedido na data de referência, a solicitação é recusada com a mensagem `"Não existe composition para esta 'reference_date' = {reference_date}"`, com a data informada no lugar de `{reference_date}`.

:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX |
| Abas | `Sheet` (composição) e `P&L` (receitas e despesas do dia) |
| Nomenclatura | `{nome_resumido_fundo}_wallet_composition_{AAAA-MM-DD}.xlsx` |

:::info Nome do arquivo

O modelo a ser solicitado é `wallet_composition_by_composition`, mas o arquivo entregue é nomeado `wallet_composition`, sem o sufixo.

:::

Cada seção é apresentada com um título em negrito, uma linha de cabeçalho e, ao final, linhas de total por tipo de ativo e um total geral da seção — essas linhas de total aparecem em negrito e com fundo cinza. **Seções sem posição na data não são impressas**: um fundo que não tem imóveis, por exemplo, não terá a seção `IMÓVEIS`.

:::tip Como conferir o fechamento

Somando a coluna `% do PL` dos totais gerais de todas as seções — ativos, mais valores a receber, menos valores a pagar, mais caixa — o resultado é 100% do patrimônio líquido do cabeçalho.

Uma diferença pequena pode aparecer quando o fundo tem **ágio ainda não diferido em emissões ou em direitos creditórios descontados**: nas seções `EMISSÕES` e `DC DESCONTADOS` o `Valor D0 (R$)` é apurado pelo valor contábil, enquanto em `OPERAÇÕES DE CRÉDITO` e `CONTRATOS` ele parte do valor justo. O ágio a diferir, nesse caso, fica fora da soma das seções, mas está dentro do patrimônio líquido.

:::

## Aba `Sheet`

### Cabeçalho do fundo

| Campo | Descrição |
|-------|-----------|
| Data de referência | Data da composição, no formato `AAAA-MM-DD`. |
| Nome da classe de fundo | Nome completo da classe de fundo. |
| CNPJ da classe de fundo | CNPJ da classe de fundo. |
| Nome da gestora | Nome da gestora do fundo. |
| CNPJ da gestora | CNPJ da gestora do fundo. |
| Patrimônio bruto (R$) | Soma do patrimônio bruto de todas as séries de emissão. |
| Patrimônio líquido (R$) | Soma do patrimônio líquido de todas as séries de emissão. É o denominador da coluna `% do PL` em todas as seções. |
| Número de cotas | Soma das cotas de todas as séries de emissão. |

### `SÉRIES DE EMISSÃO`

| Coluna | Descrição |
|--------|-----------|
| Nome | Nome da série de emissão. |
| Patrimônio bruto (R$) | Patrimônio bruto da série, antes da provisão de taxa de performance. |
| Cota bruta (R$) | Valor da cota bruta da série. |
| Patrimônio líquido (R$) | Patrimônio líquido da série. |
| Cota líquida (R$) | Valor da cota líquida da série. |
| Número de cotas | Quantidade de cotas da série. |

### `TÍTULOS PÚBLICOS`

Uma linha por título público em estoque (LFT, LTN, NTN-B e suas versões compromissadas).

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Identificador / Código SELIC | Código SELIC do título (as duas colunas trazem o mesmo valor). |
| Tipo do ativo | `LFT`, `LTN`, `NTN-B`, `LFT COMPROMISSADA`, etc. |
| Emissor | `Tesouro Nacional`. |
| Tipo de amortização | `No vencimento` ou `Juros semestrais`. |
| Data de emissão / Data de compra / Data de vencimento | Datas do título e da aquisição. |
| Unidades compradas / Unidades atuais | Quantidade de títulos adquirida e em estoque. |
| PU de compra (R$) / PU D0 (R$) | Preço unitário de aquisição e preço unitário na data de referência. |
| Valor de compra (R$) / Valor D0 (R$) | Valor financeiro de aquisição e valor na data de referência. |
| Valor esperado de resgate (R$) | Valor de recompra previsto na operação compromissada. Vazio nos títulos que não são compromissadas. |
| % de Tesouros | Participação do título no total de títulos públicos. |
| % do PL | Participação do título no patrimônio líquido do fundo. |

### `EMISSÕES`

Uma linha por título privado ofertado (debênture, CRI, CRA, CDB, letra financeira). Notas comerciais vêm em um segundo bloco, também intitulado `EMISSÕES`, com colunas equivalentes em outra ordem: o `Identificador` é o número do contrato, não há a coluna `PDD (%)` e o percentual da seção se chama `% de EMISSÕES`.

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Identificador | Código externo do papel. |
| Tipo do ativo | `DEBENTURE`, `CRI`, `CRA`, `CDB`, `Letra Financeira`, `NOTA COMERCIAL`. |
| Código ISIN / Código B3 | Códigos de identificação do papel. |
| Emissor | Nome do emissor. |
| Data de emissão / Data de compra / Data de vencimento | Datas do papel e da aquisição. |
| Unidades compradas / Unidades atuais | Quantidade adquirida e em estoque. |
| PU de compra (R$) / PU do ativo (R$) / PU D0 (R$) | Preço unitário de aquisição, preço unitário contábil e preço unitário líquido de PDD. |
| Valor de compra (R$) / Valor do ativo (R$) / Valor D0 (R$) | Valor de aquisição, valor contábil e valor líquido de PDD. |
| PDD (R$) / PDD (%) | Provisão para devedores duvidosos, em reais (negativa) e em percentual. |
| Valor vencido (R$) / Valor não vencido (R$) | Parcela vencida e não vencida do valor contábil. |
| % de Emissões | Participação do papel no total de emissões. |
| % do PL | Participação do papel no patrimônio líquido do fundo. |

### `OPERAÇÕES DE CRÉDITO`

Operações de crédito (CCB, CCE, NCE e suas versões estruturadas). Para os tipos consolidados — `CCB`, `CCE`, `NCE` — a carteira é apresentada em **uma única linha por tipo**, identificada como `CCB CONSOLIDADO`, e não operação a operação; o detalhamento ativo a ativo está no relatório [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition).

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Identificador | Número do contrato da operação ou `{TIPO} CONSOLIDADO` nas linhas consolidadas. |
| Tipo do ativo | `CCB`, `CCB ESTRUTURADA`, `CCE`, `NCE ESTRUTURADA`, etc. |
| Código IF | Código do papel na B3, quando registrado. |
| Data de emissão / Data de compra / Data de vencimento | Datas do contrato e da aquisição. Vazias nas linhas consolidadas. |
| Unidades atuais | Quantidade de operações em estoque. |
| PU de compra (R$) / PU em acruo (R$) / PU D0 (R$) | Preços unitários. Vazios nas linhas consolidadas. |
| Valor D0 (R$) | Valor justo da posição, líquido de PDD. |
| PDD (R$) / PDD (%) | Provisão para devedores duvidosos. |
| Valor do ativo (R$) | Valor contábil da posição. |
| Valor vencido (R$) / Valor em acruo (R$) | Parcela vencida e parcela em acruo do valor contábil. |
| Ágio restante (R$) | Ágio ainda não diferido (valor justo menos valor contábil). |
| Juros pós-vencimento (R$) / Juros de mora (R$) / Multa por atraso (R$) | Encargos por atraso. **Estas três colunas só aparecem quando há algum encargo de atraso na carteira de CCB.** |
| % de Operações de Crédito | Participação da linha no total de operações de crédito. |
| % do PL | Participação da linha no patrimônio líquido do fundo. |

### `DC DESCONTADOS`

Direitos creditórios descontados (duplicatas mercantis e de serviços, CT-e, contratos descontados, cheques e notas promissórias). Sempre apresentados de forma consolidada, uma linha por tipo.

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Identificador | `{TIPO} CONSOLIDADO`. |
| Tipo do ativo | `DUPLICATA MERCANTIL`, `DUPLICATA SERVIÇOS`, `CTE`, `CONTRATO`, `CHEQUE`, `NOTA PROMISSÓRIA`. |
| Valor D0 (R$) | Valor da posição líquido de PDD. |
| Valor do ativo (R$) | Valor contábil da posição. |
| Valor vencido (R$) / Valor em acruo (R$) | Parcela vencida e parcela em acruo do valor contábil. |
| PDD (R$) | Provisão para devedores duvidosos (negativa). |
| % de Direitos Creditórios Descontados | Participação da linha no total de direitos creditórios descontados. |
| % do PL | Participação da linha no patrimônio líquido do fundo. |

### `CONTRATOS`

Contratos de crédito, contratos de financiamento e confissões de dívida. Sempre apresentados de forma consolidada, uma linha por tipo.

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Identificador | `{TIPO} CONSOLIDADO`. |
| Tipo do ativo | `CONTRATO DE CRÉDITO`, `CONTRATO DE FINANCIAMENTO`, `CONFISSÃO DE DÍVIDA`. |
| Unidades atuais | Quantidade de contratos em estoque. |
| Valor D0 (R$) | Valor justo da posição, líquido de PDD. |
| PDD (R$) | Provisão para devedores duvidosos (negativa). |
| Valor do ativo (R$) | Valor contábil da posição. |
| Valor vencido (R$) / Valor em acruo (R$) | Parcela vencida e parcela em acruo do valor contábil. |
| Ágio restante (R$) | Ágio ainda não diferido (valor justo menos valor contábil). |
| Juros pós-vencimento (R$) / Juros de mora (R$) / Multa por atraso (R$) | Encargos por atraso. **Estas três colunas só aparecem quando há algum encargo de atraso nos contratos.** |
| % de Contratos | Participação da linha no total de contratos. |
| % do PL | Participação da linha no patrimônio líquido do fundo. |

### `COTAS DE FUNDOS`

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Tipo do ativo | `FIDC`, `RENDA FIXA`, `MULTIMERCADO`, `FIA`, `FIP`, `FII`, `FIAGRO`. |
| Nome do Fundo / Documento do Fundo | Nome e CNPJ do fundo investido. |
| Senioridade | `SÊNIOR`, `MEZANINO` ou `SUBORDINADA`. |
| Código Interno | Código interno da classe investida. |
| Data de compra | Sempre vazia nesta seção. |
| Valor de compra (R$) / Unidades compradas / PU de compra (R$) | Dados da aquisição. |
| Unidades atuais / Valor D0 (R$) / PU D0 (R$) | Posição na data de referência. |
| % de Cotas | Participação da linha no total de cotas de fundos. |
| % do PL | Participação da linha no patrimônio líquido do fundo. |

### `SWAP` e `IMÓVEIS`

Apresentadas apenas para fundos que possuem esses ativos. `SWAP` traz contraparte, valores nominais e valores atualizados de ativo e passivo; `IMÓVEIS` traz número de matrícula, valor e data de avaliação e a próxima avaliação prevista.

### `VALORES A PAGAR`

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Tipo de a pagar | Descrição da despesa (ex: `TAXA DE ADMINISTRAÇÃO`). |
| Total provisionado | Valor total provisionado da despesa. |
| Valor reconhecido | Valor já reconhecido no resultado, apresentado como negativo. |
| Valor restante | Diferença entre o total provisionado e o valor reconhecido. |
| Inicio da provisão / Fim da provisão / Data do pagamento | Datas da provisão e do pagamento previsto. |
| % do PL | Participação do valor reconhecido no patrimônio líquido (negativa). |

### `VALORES A RECEBER`

Mesma estrutura da seção anterior, com as colunas `Tipo de a receber`, `Total a diferir`, `Valor diferido`, `Valor restante`, `Inicio do diferimento`, `Fim do diferimento` e `Data do pagamento`. Aqui o `% do PL` é calculado sobre o `Valor restante`, e é positivo.

### `CONTAS CAIXA`

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Nome da conta | Instituição financeira e identificação contábil da conta. |
| Dados da conta | Agência e conta no formato `Ag.: {agência} \| Cc.: {conta}-{dígito}`. |
| Entrada a conciliar / Saída a conciliar | Valores creditados ou debitados ainda não conciliados. |
| Saldo | Saldo da conta na data de referência. |
| % do PL | Participação do saldo no patrimônio líquido do fundo. |

### `RENTABILIDADE`

Um bloco por série de emissão, com uma linha por janela de apuração.

| Coluna | Descrição |
|--------|-----------|
| Tipo | `Diária`, `Mensal`, `Anual` ou `D-N` (janela de N dias corridos). |
| Data de Referência | Data inicial da janela de apuração. |
| Cota de Referência | Valor da cota na data inicial da janela. |
| Cota Benchmark | Valor da cota do benchmark (DI) na data inicial da janela. |
| Cota Atual | Valor da cota líquida na data da composição. |
| Rendimento Total | Rentabilidade da cota na janela, em percentual. |
| Rendimento (%CDI) | Rentabilidade como percentual do CDI. `-` quando não há benchmark na janela. |
| Rendimento (CDI+) | Rentabilidade expressa como CDI mais spread anualizado (252 dias úteis). `-` quando o resultado é negativo ou não há benchmark. |

## Aba `P&L`

Compara os saldos das contas de resultado (grupos contábeis `07` — receitas — e `08` — despesas) entre o dia útil anterior e a data de referência.

### `RESUMIDO`

| Coluna | Descrição |
|--------|-----------|
| Data de Referência | Data da composição. |
| Tipo | `Receitas`, `Despesas` ou `Resultado`. A classificação usa o **sinal do saldo final** de cada conta, não o grupo do plano de contas: uma conta de receita com saldo negativo entra em `Despesas`. |
| Valor (R$) | Variação do dia. `Resultado` é a soma de receitas e despesas. |

### `DETALHES`

| Coluna | Descrição |
|--------|-----------|
| Nome da Conta | Nome da conta contábil de resultado. |
| Data Inicial / Valor Inicial (R$) | Dia útil anterior e saldo da conta nessa data. |
| Data Final / Valor Final (R$) | Data de referência e saldo da conta nessa data. |
| Resultado (R$) | Variação do saldo no dia. |
| Variação (%) | Variação percentual em relação ao saldo inicial. Quando o saldo inicial é zero, a célula traz o valor-sentinela `999999999` (exibido em formato percentual), e não uma variação real. |

Somente contas com variação no dia aparecem na seção.

---

# Webhook de Entrega

URL: /documentation/iaas/relatorios_dtvm/webhook_de_entrega

## Visão Geral

Sempre que uma entrega de relatórios é concluída, a QI DTVM pode notificar a sua aplicação por webhook. A notificação diz **qual entrega terminou, para qual destino, e quais arquivos ela levou** — com o status de cada relatório. É o sinal para você disparar a coleta no SFTP em vez de varrer a pasta em intervalos fixos.

O webhook é **opcional** e configurado por rotina de entrega. Sem configuração, nenhuma notificação é enviada.

:::info Como habilitar

Informe ao time de integração a URL que vai receber as notificações. Devolvemos uma *Signature Key* para você validar a assinatura, e vinculamos a configuração à rotina de entrega do fundo. A habilitação é por rotina — um fundo com duas rotinas configura as duas.

:::

## Quando é enviado

Uma notificação por **destino concluído**, no momento em que aquele destino termina de ser processado.

Um destino só é processado depois que **todos** os relatórios da entrega chegam a um estado final — `generated` ou `failed`. Só então os arquivos são transferidos e a notificação sai. Ou seja: quando o webhook chega, a pasta já tem os arquivos.

| Situação | Status do destino | Webhook |
|----------|-------------------|---------|
| Todos os relatórios gerados | `delivered` | enviado |
| Parte dos relatórios falhou | `delivered` | enviado — os que falharam aparecem em `reports`, mas **não têm arquivo** na pasta |
| Todos os relatórios falharam | `failed` | enviado — nenhum arquivo é transferido |

:::caution É um webhook por destino, não por arquivo

Uma rotina que entrega oito relatórios em uma pasta SFTP gera **uma** notificação, com oito entradas em `reports`. Não há uma notificação por arquivo.

Se a mesma entrega tem dois destinos — por exemplo uma pasta SFTP e um e-mail — são **duas** notificações, uma por destino, e as duas trazem a mesma lista de `reports`.

:::

:::info Cada destino é notificado uma única vez

A notificação de um destino é registrada quando é enviada e não se repete. Um reprocessamento do envio não gera notificação nova. Para reenviar uma notificação já emitida, veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks).

:::

## Tipos de webhook

| `webhook_type` | Quando |
|----------------|--------|
| `report.recurring_delivery_destination_completed` | Entrega originada de uma **rotina** — o caso da entrega diária de relatórios do fundo. |
| `report.delivery_destination_completed` | Entrega **avulsa**, criada fora da rotina. |

A diferença de payload está em `data`: o tipo de rotina acrescenta `recurring_delivery_key` e `description`.

## Estrutura do webhook

```json title="Webhook Body — rotina, destino SFTP"
{
    "webhook_type": "report.recurring_delivery_destination_completed",
    "webhook_datetime": "2026-07-30T09:12:44Z",
    "data": {
        "solicitation_time": "2026-07-30T09:05:00Z",
        "delivery_key": "3f1c9b7e-0a44-4c21-9f18-6b2d5e7a1c33",
        "recurring_delivery_key": "b8d2a6f4-77c1-4e90-8a3b-1d5f9c0e2a77",
        "description": "Relatórios diários — FUNDO EXEMPLO FIDC",
        "destination": {
            "destination_key": "c4e7a1b9-2d63-4f85-90ab-7c1e3f5d8b02",
            "destination_type": "sftp",
            "folder_path": "/fundos/fundo_exemplo",
            "status": "delivered"
        },
        "reports": [
            {
                "report_type": "consolidated_credit_rights_acquisition_assets",
                "file_name": "example_name_consolidated_credit_rights_acquisition_assets_2026-07-29.csv",
                "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860",
                "reference_date": "2026-07-29",
                "status": "generated"
            },
            {
                "report_type": "cash_account_demonstrative",
                "file_name": "example_name_cash_account_demonstrative_2026-07-29.xlsx",
                "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860",
                "reference_date": "2026-07-29",
                "status": "generated"
            }
        ]
    }
}
```

### Atributos de `data`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `solicitation_time` | string | Data e hora em que a entrega foi solicitada, em ISO 8601 (UTC). |
| `delivery_key` | string | Identificador da entrega (UUID). Único por execução da rotina. |
| `recurring_delivery_key` | string | Identificador da rotina. **Presente apenas** em `report.recurring_delivery_destination_completed` — é estável entre execuções e serve para identificar de qual rotina veio a entrega. |
| `description` | string | Descrição cadastrada na rotina. **Presente apenas** em `report.recurring_delivery_destination_completed`. |
| `destination` | object | Destino concluído. Veja **[Atributos de `destination`](#atributos-de-destination)**. |
| `reports` | array | Relatórios da entrega. Veja **[Atributos de `reports`](#atributos-de-reports)**. |

### Atributos de `destination`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `destination_key` | string | Identificador do destino (UUID). É a chave desta notificação: um `destination_key` é notificado uma única vez. |
| `destination_type` | string (enum) | `sftp` ou `email`. |
| `status` | string (enum) | `delivered` ou `failed`. Veja a tabela de [quando é enviado](#quando-e-enviado). |
| `folder_path` | string | Pasta de destino no SFTP. **Presente apenas** quando `destination_type` é `sftp`. |
| `recipients` | array | Destinatários do e-mail. **Presente apenas** quando `destination_type` é `email`. |
| `title` | string | Assunto do e-mail. **Presente apenas** quando `destination_type` é `email`. |

Os arquivos são gravados em `folder_path` com exatamente o `file_name` de cada relatório — o caminho completo é `{folder_path}/{file_name}`.

### Atributos de `reports`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `report_type` | string (enum) | Modelo do relatório, conforme a coluna "Modelo" da [lista de relatórios disponíveis](/documentation/iaas/relatorios_dtvm/). |
| `file_name` | string | Nome do arquivo entregue, já com o prefixo do fundo e a data. |
| `fund_class_key` | string | Classe de fundo do relatório. |
| `reference_date` | string | Data de referência, em `AAAA-MM-DD`. **Pode vir nulo** nos relatórios gerados por intervalo (`quota_mec`, `balance_report`, `accounting_ledger`), que são parametrizados por `start_date` e `end_date` em vez de uma data única — trate o campo como opcional e use `file_name` para identificar o arquivo. |
| `status` | string (enum) | `generated` ou `failed`. |

:::danger Confira o `status` de cada relatório

Um webhook recebido **não** significa que todos os arquivos estão na pasta. Relatórios com `status: "failed"` aparecem na lista e não têm arquivo correspondente.

Um leitor que itere `reports` e tente baixar tudo vai falhar no primeiro relatório com erro. Filtre por `status == "generated"` antes de montar a lista de arquivos a coletar, e trate a presença de `failed` como alerta operacional — não como ausência de entrega.

:::

## Autenticação e reenvio

A validação da assinatura, a lista de IPs de origem, a política de tentativas e o reenvio são iguais aos dos demais webhooks da QI DTVM — veja **[Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks)**.

## Onde não há webhook

Duas entregas de relatório **não** emitem esta notificação:

- **Relatórios de cessão** — o [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) e a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) são gerados na etapa de aprovação da cessão, e não na rotina do fundo. Para esses dois, o acompanhamento é pelo [webhook de status do lote de cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) e pela coleta na pasta.
- **Download sob demanda da carteira** — a rota de [Baixar a Carteira](/documentation/iaas/composicao_carteira/baixar_carteira) é síncrona e devolve o arquivo na própria resposta, em base64. Não passa por entrega, destino, nem webhook.

:::caution Atenção ao lastro da cessão

O `assignment_documents` é justamente o relatório em que o aviso de chegada faria mais diferença, porque os links de download dentro dele expiram em 5 dias contados da **geração**. Como ele não emite webhook, a orientação de coleta continua sendo a do roteiro de [Testando a Captura de Lastro](/documentation/iaas/relatorios_dtvm/testar_captura_lastro).

:::

---

# XML ANBIMA (tipos 5 e 401)

URL: /documentation/iaas/relatorios_dtvm/xml_anbima

## Visão Geral

A QI DTVM gera os arquivos de posição de carteira no padrão ANBIMA a partir da composição de carteira do fundo. São dois modelos, entregues como arquivos independentes:

| Modelo | Padrão | Descrição |
|--------|--------|-----------|
| `xml_5_by_composition` | Arquivo de Posição ANBIMA 5.0 (ISO 20022, `semt.003.001.04`) | Posição da carteira em estrutura ISO 20022, com identificação de administrador, gestor e custodiante, posição por ativo, valores a pagar e a receber. |
| `xml_401_by_composition` | Arquivo de Posição ANBIMA 4.01 | Posição da carteira no layout 4.01, com cabeçalho do fundo e blocos por classe de ativo. |

:::info Qual é o "XML da ANBIMA"

Quando se fala do XML da ANBIMA no dia a dia, o arquivo em questão é o **`xml_5_by_composition`** — a versão 5.0 do arquivo de posição. O `xml_401_by_composition` é a versão anterior do mesmo padrão, ainda exigida por alguns consumidores.

:::

## Parâmetros da rotina

Na entrega pela rotina do fundo, o arquivo é gerado para a `fund_class_key` e a `reference_date` da entrega. Dois parâmetros opcionais podem ser configurados pelo time de integração na rotina — eles **não** são aceitos no download sob demanda pela API:

| Parâmetro | Descrição |
|-----------|-----------|
| `type_fund_code_anbima` | Código do tipo de fundo na tabela da ANBIMA. Quando omitido, é derivado do cadastro do fundo. Um código fora da lista de válidos faz a geração falhar. |
| `issuance_serie_key` | Só XML 401. Restringe o arquivo a uma única série de emissão. Sem ele, todas as séries da classe entram no arquivo. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XML |
| Encoding | UTF-8 |
| Nomenclatura | Tipo 5: `FD{CNPJ do fundo, só dígitos}_{AAAAMMDD}.xml`, o nome do padrão ANBIMA (sem CNPJ cadastrado, cai no padrão `{nome_resumido_fundo}_xml_5_by_composition_{AAAA-MM-DD}.xml`, que é o do pacote de exemplos). Tipo 401: `{nome_resumido_fundo}_xml_401_by_composition_{AAAA-MM-DD}.xml` |

Ambos os arquivos são gerados a partir de uma **composição de carteira** já fechada na data de referência — confirmada ou aguardando confirmação. Antes de montar o arquivo, o serviço reconcilia a posição: a soma dos ativos, mais os valores a receber, menos os valores a pagar, tem que fechar com o patrimônio líquido informado pelas séries de emissão. Quando não fecha, o arquivo não é gerado.

## Como receber

Há duas formas, que podem ser usadas em conjunto:

1. **Na rotina de entrega do fundo**, junto com os demais relatórios — veja [como os relatórios são entregues](/documentation/iaas/relatorios_dtvm/). Basta solicitar ao time de integração a inclusão dos modelos `xml_5_by_composition` e/ou `xml_401_by_composition` na configuração da entrega.
2. **Sob demanda, pela API**, com `POST /composition/fund_class/{fund_class_key}/report`, informando `report_type` igual a `xml_5_by_composition` ou `xml_401_by_composition`. A resposta traz o arquivo em base64 no campo `document_b64`. Contrato, perfis que têm acesso e erros em [Baixar a Carteira](/documentation/iaas/composicao_carteira/baixar_carteira).

```json title="Request Body"
{
    "composition_type": "final_quota",
    "report_type": "xml_5_by_composition",
    "reference_date": "2026-07-29"
}
```

:::caution Carteira de validação não gera XML

Os dois XMLs não são gerados para a carteira `pre_quota` (resposta **404**, `CMP000026`). A carteira precisa estar em `confirmed`, `pending_confirmation` ou `reproved_by_agent`; em outro status, a resposta é **400** (`CMP000015`).

:::

## Conteúdo do arquivo tipo 5

O arquivo tem o elemento raiz `PosicaoAtivosCarteira` e é dividido em duas partes:

- **`AppHdr`** — cabeçalho da mensagem: administrador remetente (nome e CNPJ), fundo destinatário, identificador da mensagem, versão do layout (`semt.003.001.04`), serviço (`Arquivo de Posicao 5.0`) e data/hora de geração.
- **`Document / SctiesBalAcctgRpt`** — corpo da posição:

| Elemento | Conteúdo |
|----------|----------|
| `Pgntn` | Paginação do arquivo. |
| `StmtGnlDtls` | Dados gerais do extrato: data da composição, frequência e tipo de atualização. |
| `AcctOwnr` | CNPJ do administrador (titular da conta). |
| `AcctSvcr` | CNPJ da gestora. |
| `SfkpgAcct` | CNPJ e nome do custodiante. |
| `BalForAcct` | Classe de fundo e séries de emissão, com ISIN, quantidade de cotas, valor da cota, valor total dos ativos, e o detalhamento de valores a pagar (`PAYA`) e a receber (`RECE`). |
| `SubAcctDtls` | Uma entrada por ativo da carteira: títulos públicos, títulos privados, debêntures, cotas de fundo, direitos creditórios, swaps, imóveis e contas caixa. |
| `AcctBaseCcyTtlAmts` | Patrimônio líquido total do fundo. |

Os valores a pagar são classificados com os códigos ISO correspondentes à natureza da despesa — `ADMF` (taxa de administração), `MANF` (gestão), `PERF` (performance), `CETI` (CETIP), `REGF` (CVM), `ANBI` (ANBIMA), `AUDT` (auditoria), `SELC` (SELIC), `CUST` (custódia), `LEGA` (serviços) — ou `OTHR` para os demais.

## Conteúdo do arquivo tipo 401

O arquivo tem o elemento raiz `arquivoposicao_4_01`, com um elemento `fundo` que reúne:

| Bloco | Conteúdo |
|-------|----------|
| `header` | ISIN, CNPJ e nome do fundo, data da posição, administrador, gestor e custodiante, valor e quantidade de cotas, patrimônio líquido, valor dos ativos, valores a receber e a pagar, tipo de fundo ANBIMA. |
| `titpublico` | Um bloco por título público, com código SELIC, datas, quantidades, PUs, indexador e valor financeiro. |
| `titprivado` | Um bloco por título privado que não seja debênture. |
| `debenture` | Um bloco por debênture. |
| `swap` | Um bloco por contrato de swap, com valores de ativo e passivo. |
| `cotas` | Um bloco por cota de fundo investida, com ISIN, CNPJ do fundo, quantidade e PU. |
| `caixa` | Saldo das contas caixa. |
| `despesas` | Taxas de administração e performance do fundo. |
| `outrasdespesas` | Demais despesas provisionadas. |
| `provisao` | Provisões constituídas, com data e valor. |
| `fidc` | Valor financeiro total dos direitos creditórios da carteira. |

Blocos sem posição na data não são incluídos no arquivo.