# QI Tech — Investment-as-a-Service › Composição da Carteira Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 5 página(s). Índice: - Carteira - Aprovação (/documentation/iaas/composicao_carteira/aprovar_carteira) - Carteira - Baixar a Carteira (/documentation/iaas/composicao_carteira/baixar_carteira) - Introdução (/documentation/iaas/composicao_carteira/inicio) - Carteira - Recuperação da Carteira (/documentation/iaas/composicao_carteira/recuperar_carteira) - Webhooks da carteira (/documentation/iaas/composicao_carteira/webhooks) --- # Carteira - Aprovação URL: /documentation/iaas/composicao_carteira/aprovar_carteira Aprova ou reprova a carteira de validação. Só é aceito para carteiras no status `pending_confirmation` — o status em que a carteira fica quando está pronta para a sua análise e em que a gestora recebe o [webhook de mudança de status](/documentation/iaas/composicao_carteira/webhooks). :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/composition/COMPOSITION_KEY MÉTODO PUT ```json title='Request Body — aprovar' { "new_status": "confirmed" } ``` ```json title='Request Body — reprovar' { "new_status": "reproved_by_agent", "reproved_reason": "Cota divergente do controle interno da gestora." } ``` | Campo | Tipo | Obrigatório | Descrição | | ----------------- | ------ | --------------------------------------------- | ----------------------------------------------------- | | `new_status` | string | Sim | Novo status da carteira. Ver enumeradores abaixo. | | `reproved_reason` | string | Sim, quando `new_status` é `reproved_by_agent` | Motivo da reprovação, de 1 a 255 caracteres. | ## Enumeradores do "new_status" | Enumerador | Descrição | | ------------------- | ------------------------------------------------------------------------- | | `confirmed` | Aprova a carteira. | | `reproved_by_agent` | Reprova a carteira, registrando o motivo informado em `reproved_reason`. | | `reproved` | Reprova a carteira sem exigir motivo. Prefira `reproved_by_agent`. | O motivo da reprovação fica registrado no histórico da carteira: o campo `status_events` da [consulta da carteira](/documentation/iaas/composicao_carteira/recuperar_carteira#informacoes-da-carteira) traz cada mudança de status com o seu `metadata`. ## Response Em caso de sucesso, a API devolve **204 No Content**, sem corpo. Consulte a carteira para ver o novo status. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | --------------------------------------------------------------------------------------------------- | | 404 | `CMP000013` | A carteira não está em `pending_confirmation` (já foi aprovada, reprovada ou ainda está em processamento). | | 404 | `CMP000010` | `new_status` diferente de `confirmed`, `reproved_by_agent` ou `reproved`. | | 404 | `CMP000025` | `new_status` é `reproved_by_agent` e `reproved_reason` não foi enviado. | | 404 | `CMP000012` | Não existe carteira com essa `composition_key` na classe informada. | | 404 | `CMP000001` | Não existe classe com essa `fund_class_key`. | | 409 | `CMP000022` | Já existe outra carteira da mesma classe, data e tipo no status pedido. | | 400 | `QIT000001` | Corpo fora do contrato: `new_status` ausente ou fora dos valores aceitos, ou campo não previsto. | | 400 | `QIT000004` | A `fund_class_key` é de uma classe de outra gestora. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Carteira - Baixar a Carteira URL: /documentation/iaas/composicao_carteira/baixar_carteira ## Introdução Este recurso gera, de forma síncrona, um relatório da classe de fundo e o devolve em base64. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------------------------ | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Carteiras | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/report MÉTODO POST STATUS 201 ```json title='Request Body' { "report_type": "wallet_composition_by_composition", "composition_type": "final_quota", "reference_date": "2025-01-20" } ``` | Campo | Tipo | Obrigatório | Descrição | | ------------------ | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `report_type` | string | Sim | Relatório a gerar. Ver tabela abaixo. | | `reference_date` | string | Sim | Data de referência, no formato `YYYY-MM-DD`. | | `composition_type` | string | Para relatórios da carteira, este ou `composition_key` | `pre_quota`, `final_quota` ou `opening_quota`. Usa a carteira desse tipo na `reference_date`. | | `composition_key` | string | Para relatórios da carteira, este ou `composition_type` | Chave de uma carteira específica. | ### Relatórios disponíveis | `report_type` | Conteúdo | Precisa identificar a carteira | | --------------------------------------- | ------------------------------------------ | ------------------------------ | | `wallet_composition_by_composition` | Carteira em planilha (`.xlsx`) | Sim | | `wallet_composition_by_composition_pdf` | Carteira em PDF | Sim | | `xml_401_by_composition` | XML 4.01 da carteira — não aceita `pre_quota` | Sim | | `xml_5_by_composition` | XML 5.0 da carteira — não aceita `pre_quota` | Sim | | `cash_account_demonstrative` | Demonstrativo da conta caixa | Não (só `reference_date`) | | `pmts_reconciliation` | Conciliação de PMTs | Não (só `reference_date`) | Os demais valores aceitos pelo contrato (`wallet_composition_a_pagar`, `assets_wallet_composition_legacy`, `wallet_asset_installments_settlement_legacy`, `settlements_status_by_reference_date`, `discarded_settlements_on_payment_batch`) não são gerados por este endpoint e devolvem `CMP000027`. ### Response ```json title='Response Body' { "document_b64": "UEsDBBQABgAIAAAAIQ..." } ``` `document_b64` é o arquivo do relatório codificado em base64. :::caution Atenção Para os relatórios da carteira, ela precisa estar em **`confirmed`**, **`pending_confirmation`** ou **`reproved_by_agent`**. Em outro status, a resposta é **400** (`CMP000015`). ::: ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ----------------------------------------------------------------------------------------------------- | | 400 | `CMP000015` | A carteira não está em `confirmed`, `pending_confirmation` ou `reproved_by_agent`. | | 400 | `CMP000044` | Relatório da carteira sem `composition_key` nem `composition_type`. | | 400 | `CMP000027` | `report_type` não é gerado por este endpoint. | | 404 | `CMP000026` | `xml_401_by_composition` ou `xml_5_by_composition` pedido para uma carteira `pre_quota`. | | 404 | `CMP000012` | Não existe carteira com a `composition_key` informada, ou do `composition_type` na `reference_date`. | | 400 | `CMP000014` | O gerador de relatórios recusou o pedido; a `description` traz o motivo. | | 400 | `QIT000001` | Corpo fora do contrato: campo obrigatório ausente, data fora do formato ou campo não previsto. | | 400 | `QIT000004` | A `fund_class_key` é de uma classe de outra gestora. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Introdução URL: /documentation/iaas/composicao_carteira/inicio Nesta seção iremos explicar como funciona o consumo da Carteira por meio de APIs. Todos os dias as carteiras de todos os Fundos de Investimento dos Fundos administrados pela QI DTVM são disponibilizadas por essa API, com as informações que compõe a cota daquele determinado dia. Durante o processamento do fechamento do Fundo, e consequentemente de disponibilização da sua carteira, geramos uma primeira carteira, chamada de **Carteira de Validação** (`composition_type` = `pre_quota`), e uma vez que esta é aprovada, seguimos para a disponibilização da **Carteira Final** (`composition_type` = `final_quota`). A principal diferença entre ambas as carteiras é que a de validação é gerada anterior ao processamento do passivo, isso inclui amortizações, aplicações e resgates, enquanto a final, já sensibiliza essas movimentações. Informações dos ativos, despesas, conciliações, e caixa, são sempre idênticas entre as duas carteiras. De forma prática o que muda, é que eventuais "A Pagar" de Resgates a Cotizar, ou "A Receber" de Aplicações Financeiras a Cotizar, são cotizados e sensibilizam o número de Cotas das Séries de Emissão, sem alterar portanto a Cota Divulgada. :::caution É muito importante que quaisquer criticas, ou validações sejam feitos em cima da **Carteira de Validação** antes da sua aprovação, pois uma vez que esta é aprovada, o sistema segue para o processamento do passivo e consequentemente para a disponibilização da carteira final. Nesta etapa, como já houve o processamento do passivo, eventuais resgates e amortizações já podem ter sido até liquidados. ::: Quando a carteira fica pronta para a sua análise, ela entra no status `pending_confirmation` e a gestora recebe o [webhook de mudança de status](/documentation/iaas/composicao_carteira/webhooks). A aprovação ou reprovação é feita em [Aprovação de carteira](/documentation/iaas/composicao_carteira/aprovar_carteira). Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em sandbox quanto em produção. --- # Carteira - Recuperação da Carteira URL: /documentation/iaas/composicao_carteira/recuperar_carteira --- ## Lista de Carteiras Lista as carteiras de uma classe de fundo, paginadas, da data mais recente para a mais antiga. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Carteiras | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/compositions MÉTODO GET ### Query Params | Parâmetro | Descrição | |------------------|-----------------------------------------------------------------------------------------------------| | `not_status` | Filtra os resultados excluindo composições que esteja no status informado. | | `status` | Filtra os resultados trazendo apenas composições que esteja no status informado. | | `reference_date` | Data de referência para a consulta das composições. Deve estar no formato `YYYY-MM-DD`. | | `type` | Tipo da carteira: `pre_quota`, `final_quota` ou `opening_quota`. | | `start_date` | Data inicial do intervalo de busca. Obrigatório se `end_date` for informado. Formato: `YYYY-MM-DD`. | | `end_date` | Data final do intervalo de busca. Obrigatório se `start_date` for informado. Formato: `YYYY-MM-DD`. | | `page` | Página a recuperar, começando em `0`. Padrão: `0`. | | `limit` | Itens por página. Padrão: `20`; máximo: `100`. | `status` e `not_status` aceitam mais de um valor (`?status=pending_confirmation&status=confirmed`). Os status possíveis de uma carteira são `created`, `pending_processing`, `pending_validation`, `pending_variation_reason`, `pending_quota_performance`, `pending_confirmation`, `confirmed`, `reproved`, `reproved_by_agent` e `reprocessed`. A carteira que espera a sua aprovação está em `pending_confirmation`. :::caution Atenção Existem duas formas de filtrar por data: - Uma **data específica**, enviando o query param `reference_date`. - Um **período**, enviando os query params `start_date` e `end_date` (os dois juntos). ::: ```json title='Response Body' { "data": [ { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "status": "confirmed", "composition_type": "pre_quota", "composition_date": "2024-11-13", "fund_class": { "name": "A SAMPLE CLASS", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "document_number": "11.222.333/0001-81" } }, { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "status": "confirmed", "composition_type": "final_quota", "composition_date": "2024-11-13", "fund_class": { "name": "A SAMPLE CLASS", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "document_number": "11.222.333/0001-81" } } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Objeto Paginado | Campo | Tipo | Descrição | |---------------|--------|----------------------------------------------------------------| | `data` | array | Lista de objetos de **[Composition](#composition)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última | ### Composition | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------| | `composition_key` | string | Chave única de identificação da carteira | | `status` | string | O status daquela carteira | | `composition_type` | string | O tipo daquela carteira, pre_quota/final_quota | | `composition_date` | string | Data de referência da carteira | | `fund_class` | object | Objeto de **[Fund Class](#fund_class)** | ### Fund Class {#fund_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da classe de fundo | até 255 | | `fund_class_key` | string | Chave única de identificação da classe de fundo | 36 | | `document_number` | string | CNPJ da classe de fundo | - | --- ## Informações da Carteira Retorna a carteira completa: séries de emissão, ativos, a receber, a pagar, contas e o histórico de status. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Carteiras | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/composition/COMPOSITION_KEY MÉTODO GET ```json title='Response Body' { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "status": "confirmed", "composition_type": "pre_quota", "composition_date": "2024-12-02", "fund_class": { "name": "A SAMPLE CLASS", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "document_number": "11.222.333/0001-81" }, "issuance_series": [ { "issuance_serie_key": "840e01e9-0df8-4719-83c4-f10b839d8384", "name": "SUBORDINADA - 1", "gross_net_worth": 1891397.29, "net_net_worth": 1891397.29, "gross_quota_value": 1.76821576, "net_quota_value": 1.76821576, "number_of_quotas": 1069664.309518427, "applied_value": 0.0, "applied_quotas": 0.0, "redeemed_value": 0.0, "redeemed_quotas": 0.0, "amortized_value": 0.0, "tax_anticipated_value": 0.0, "tax_anticipated_quotas": 0.0, "profitabilities": [ { "reference_date": "2024-11-29", "quota_value": 1.76065188, "di_benchmark_quota_value": 1.7613906, "quota_percentage": 100.43, "di_benchmark_percentage": 100.43, "type": "monthly" }, { "reference_date": "2024-11-25", "quota_value": 1.7568068, "di_benchmark_quota_value": 1.76049545, "quota_percentage": 99.79, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-11-01", "quota_value": 1.74121452, "di_benchmark_quota_value": 1.75502225, "quota_percentage": 99.21, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-10-03", "quota_value": 1.72167143, "di_benchmark_quota_value": 1.75002091, "quota_percentage": 98.38, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-09-03", "quota_value": 1.70128747, "di_benchmark_quota_value": 1.74445962, "quota_percentage": 97.52, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-06-05", "quota_value": 1.63380383, "di_benchmark_quota_value": 1.7178922, "quota_percentage": 95.1, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2023-12-08", "quota_value": 1.52421994, "di_benchmark_quota_value": 1.68553599, "quota_percentage": 90.43, "di_benchmark_percentage": 100.0, "type": "daily" } ] } ], "assets": [ { "asset_key": "34f42521-f27f-424a-958f-8b53f15cc80d", "asset_type": "fixed_income_fund_quota", "purchase_date": "2024-11-27", "total_purchase_value": 1009320, "bad_debt_percentage": 0, "bad_debt_value": 0, "overdue_accounting_value": 0, "current_accounting_value": 1234335, "current_fair_accounting_value": 1234335 } ], "consolidated_assets": [ { "asset_type": "ccb", "asset_category": "credit", "total_units": 175623, "bad_debt_value": 0, "overdue_accounting_value": 75642, "current_accounting_value": 187762590, "current_fair_accounting_value": 187762590, "post_maturity_interest_value": 0, "delay_interest_value": 0, "delay_fine_value": 0 } ], "receivables": [ { "origin_key": "a60f9226-edac-488e-9a58-6205a334e6ba", "origin_type": "expense", "description": "Taxa CVM - 2024", "total_value": 711515, "recognized_value": 654125, "start_date": "2024-01-09", "end_date": "2024-12-31", "payment_date": "2024-05-10" } ], "payables": [ { "origin_key": "19b83b17-d36c-4edd-97fe-99af6a0a4a63", "origin_type": "expense", "description": "Taxa de Gestão - 2024/12", "total_value": 14586, "recognized_value": 14586, "start_date": "2024-12-02", "end_date": "2024-12-31", "payment_date": "2025-01-08" } ], "cash_accounts": [ { "account_key": "a41e4fa8-6950-485e-9a5b-70f21cc6774a", "balance": 100000, "unconcilied_cash_in": 0, "unconcilied_cash_out": 0, "account_branch": "0001", "account_digit": "1", "account_number": "372832", "accounting_identification": 1, "financial_institution": { "code": "329", "ispb": "32402502", "name": "QI Sociedade de Crédito Direto" } } ] } ``` ### Composition Completo | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------------------| | `composition_key` | string | Chave única de identificação da carteira | | `status` | string | O status daquela carteira | | `composition_type` | string | O tipo daquela carteira, pre_quota/final_quota | | `composition_date` | string | Data de referência da carteira | | `fund_class` | object | Objeto de **[Fund Class](#fund_class)** | | `issuance_series` | array | Lista de objetos de **[Issuance Series](#issuance_serie)** | | `assets` | array | Lista de objetos de **[Assets](#assets)** | | `consolidated_assets` | array | Lista de objetos de **[Consolidated Assets](#consolidated-assets)** | | `receivables` | array | Lista de objetos de **[Receivables](#receivables)** | | `payables` | array | Lista de objetos de **[Payables](#payables)** | | `cash_accounts` | array | Lista de objetos de **[Cash Accounts](#cash-accounts)** | | `status_events` | array | Histórico de status da carteira. Ver **[Status Events](#status-events)** | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------------------| | `issuance_serie_key` | string | Chave única de identificação da série de emissão | | `name` | string | O nome daquela série | | `gross_net_worth` | float | O PL Bruto daquela série | | `net_net_worth` | float | O PL Líquido daquela série | | `gross_quota_value` | float | Valor da Cota Bruta | | `net_quota_value` | float | Valor da Cota Líquida | | `number_of_quotas` | float | Número Total de Cotas | | `applied_value` | float | Valor total aplicado no período (opcional) | | `applied_quotas` | float | Quantidade de cotas aplicadas no período (opcional) | | `redeemed_value` | float | Valor total resgatado no período (opcional) | | `redeemed_quotas` | float | Quantidade de cotas resgatadas no período (opcional) | | `amortized_value` | float | Valor total amortizado no período (opcional) | | `tax_anticipated_value` | float | Valor do imposto antecipado (opcional) | | `tax_anticipated_quotas` | float | Quantidade de cotas do imposto antecipado (opcional) | | `isin_code` | string | Código ISIN da série (opcional) | | `profitabilities` | array | Lista de objetos de **[Profitability](#profitability)** | ### Profitability | Campo | Tipo | Descrição | |-----------------------------|--------|----------------------------------------------------------------------| | `reference_date` | string | Data de Referência no qual a performance é analisada | | `quota_value` | float | O valor da Cota da Série na Data de Referência | | `di_benchmark_quota_value` | float | O valor da Cota hoje caso a Cota de referência rodasse a 100% do DI | | `quota_percentage` | float | Rentabilidade acumulada da cota no período (%) | | `di_benchmark_percentage` | float | Rentabilidade acumulada do benchmark DI no período (%) | | `type` | string | Tipo do período de rentabilidade | ### Assets | Campo | Tipo | Descrição | |---------------------------------|---------|-------------------------------------------------------| | `asset_key` | string | Chave única de identificação do ativo | | `asset_type` | string | O Tipo do ativo | | `purchase_date` | string | Data de Aquisição do ativo | | `total_purchase_value` | string | Valor Total de Aquisição do Ativo | | `bad_debt_percentage` | string | % de PDD aplicado | | `bad_debt_value` | integer | Valor total de PDD considerado - Inteiro em centavos | | `overdue_accounting_value` | integer | Valor vencido do Ativo - Inteiro em centavos | | `current_accounting_value` | integer | Valor total do Ativo - Inteiro em centavos | | `current_fair_accounting_value` | integer | Valor total do Ativo - Inteiro em centavos | ### Consolidated Assets | Campo | Tipo | Descrição | |---------------------------------|---------|----------------------------------------------------------------------| | `asset_type` | string | O Tipo do ativo | | `asset_category` | string | A categoria do ativo | | `total_units` | integer | O número total de Ativos consolidados desse tipo | | `bad_debt_value` | integer | Valor total de PDD considerado - Inteiro em centavos | | `overdue_accounting_value` | integer | Valor vencido do Ativo - Inteiro em centavos | | `current_accounting_value` | integer | Valor total do Ativo - Inteiro em centavos | | `current_fair_accounting_value` | integer | Valor justo total do Ativo - Inteiro em centavos | | `post_maturity_interest_value` | integer | Juros pós-vencimento - Inteiro em centavos | | `delay_interest_value` | integer | Juros de mora - Inteiro em centavos | | `delay_fine_value` | integer | Multa por atraso - Inteiro em centavos | ### Receivables | Campo | Tipo | Descrição | |-----------------------------|--------|----------------------------------------------------------------------| | `origin_key` | string | Chave única de identificação do recurso que origina esse A Receber | | `origin_type` | string | O Tipo do recurso que origina esse A Receber | | `description` | string | Descrição do item | | `total_value` | float | O valor Total A Receber | | `recognized_value` | float | O valor que já foi apropriado | | `start_date` | string | A data de início de apropriação | | `end_date` | string | O data de fim da apropriação | | `payment_date` | string | A data de Liquidação | ### Payables | Campo | Tipo | Descrição | |-----------------------------|--------|----------------------------------------------------------------------| | `origin_key` | string | Chave única de identificação do recurso que origina esse A Pagar | | `origin_type` | string | O Tipo do recurso que origina esse A Pagar | | `description` | string | Descrição do item | | `total_value` | float | O valor Total A Pagar | | `recognized_value` | float | O valor que já foi apropriado | | `start_date` | string | A data de início de apropriação | | `end_date` | string | O data de fim da apropriação | | `payment_date` | string | A data de Liquidação | ### Cash Accounts | Campo | Tipo | Descrição | |-----------------------------|---------|-------------------------------------------------------------------| | `account_key` | string | Chave única de identificação da conta | | `balance` | integer | O saldo da conta - Inteiro em centavos | | `unconcilied_cash_in` | integer | O valor de Entradas A Conciliar nessa conta - Inteiro em centavos | | `unconcilied_cash_out` | integer | O valor de Saídas A Conciliar nessa conta - Inteiro em centavos | | `account_branch` | string | A Agência da conta | | `account_digit` | string | O Dígito da conta | | `account_number` | string | O número da conta | | `accounting_identification` | integer | O identificador contábil daquela conta | | `financial_institution` | object | Objetos de **[Financial Institution](#financial_institution)** | | `account_data` | object | Objeto com os dados da conta (contém os mesmos campos acima) | ### Financial Institution {#financial_institution} | Campo | Tipo | Descrição | |-----------------------------|--------|-----------------------| | `code` | string | Código COMPE da IF | | `ispb` | string | O ISPB da IF | | `name` | string | O nome da IF | ### Status Events | Campo | Tipo | Descrição | |------------------|--------|---------------------------------------------------------------------------------------------------------| | `status` | string | Status assumido pela carteira | | `event_datetime` | string | Data e hora da mudança de status | | `metadata` | object | Dados da mudança, quando houver. Numa reprovação pela gestora, traz o `reproved_reason` informado | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------------------------- | | 400 | `CMP000016` | Listagem com só um de `start_date` e `end_date`. | | 400 | `CMP000017` | Listagem com `end_date` anterior a `start_date`. | | 400 | `QIT000004` | A `fund_class_key` é de uma classe de outra gestora. | | 400 | `QIT000010` | Parâmetro de query inválido: `limit` acima de 100, `page` negativo ou `reference_date` fora de `YYYY-MM-DD`. | | 404 | `CMP000001` | Não existe classe com essa `fund_class_key`. | | 404 | `CMP000012` | Consulta de uma `composition_key` que não existe na classe informada. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Webhooks da carteira URL: /documentation/iaas/composicao_carteira/webhooks A carteira emite o webhook `composition.status_change` quando muda para alguns status. Ele é enviado **só para a gestora** da classe de fundo. Assinatura, headers e política de reenvio são os mesmos de todos os webhooks: veja [Autenticação de webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ## Quando é enviado | `status` | Quando | O que fazer | | ---------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `pending_confirmation` | A carteira está pronta e aguarda a aprovação da gestora. | Analise a carteira e [aprove ou reprove](/documentation/iaas/composicao_carteira/aprovar_carteira). | | `confirmed` | A carteira foi confirmada: a de validação, ao ser aprovada pela gestora (ou automaticamente, se a classe tem aprovação automática); a final, ao fim do processamento. | Consulte ou [baixe](/documentation/iaas/composicao_carteira/baixar_carteira) a carteira. | | `reprocessed` | Uma carteira já confirmada foi reprocessada pela QI DTVM. | A carteira confirmada deixa de valer. Liste as carteiras da mesma data para obter a versão vigente. | Reprovações (`reproved`, `reproved_by_agent`) e os status intermediários de processamento não emitem webhook. ## Payload ```json title='Webhook Body' { "webhook_type": "composition.status_change", "webhook_datetime": "2025-01-22T20:30:23.459123+00:00", "data": { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "composition_date": "2025-01-21", "composition_type": "pre_quota", "status": "pending_confirmation", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860" } } ``` | Campo | Tipo | Descrição | | ----------------------- | ------ | ---------------------------------------------------------------------- | | `webhook_type` | string | Sempre `composition.status_change`. | | `webhook_datetime` | string | Data e hora do envio, em UTC (ISO 8601). | | `data.composition_key` | string | Chave da carteira. Use-a para consultar a carteira completa. | | `data.composition_date` | string | Data de referência da carteira (`YYYY-MM-DD`). | | `data.composition_type` | string | `pre_quota`, `final_quota` ou `opening_quota`. | | `data.status` | string | Novo status da carteira. | | `data.fund_class_key` | string | Chave da classe de fundo. | ## Configuração A URL do webhook e os tipos de carteira que geram notificação (por exemplo, só `pre_quota`) são configurados pela QI DTVM — não há endpoint para isso na sua integração. Solicite ao time de integração em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br).