# QI Tech — Investment-as-a-Service › Recompra e venda de ativos Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 4 página(s). Índice: - Criação de um ativo a ser recomprado/vendido (/documentation/iaas/venda_ativos/asset/criacao_recompra) - Criação de um lote de recompra (/documentation/iaas/venda_ativos/assignment/criacao_recompra) - Encerrar inserção de ativos (/documentation/iaas/venda_ativos/assignment/fechamento_recompra) - Recompra e Venda de Ativos (/documentation/iaas/venda_ativos/inicio) --- # Criação de um ativo a ser recomprado/vendido URL: /documentation/iaas/venda_ativos/asset/criacao_recompra Insere um ativo da carteira do fundo num lote em `pending_assets_insertion`. Faça uma requisição por ativo. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/ASSIGNMENT_EXTERNAL_ID/asset MÉTODO POST `ASSIGNMENT_EXTERNAL_ID` é o `external_id` do **lote**, informado na [criação do lote](/documentation/iaas/venda_ativos/assignment/criacao_recompra). O `external_id` do corpo é o do **ativo**. ```json title='Request Body' { "external_id": "7c2d5a10-3f4e-4b8a-9d61-0e2f4a6b8c90", "sale_value": 1234.56 } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `external_id` | string | Identificador do ativo, o mesmo com que ele foi encarteirado. Envie este **ou** `contract_number`. | Até 50 | | `contract_number` | string | Número do contrato do ativo, alternativa ao `external_id`. Aceito para `ccb`, `structured_cci`, `duplicata_servicos`, `duplicata_mercantil` e `cte`. | Até 50 | | `borrower_document_number` | string | Documento do devedor, para desambiguar a busca do ativo | 11 a 18 | | `sale_value` | number | Valor pelo qual o ativo será baixado. Envie este **ou** `calculation_method`. | 2 casas decimais | | `calculation_method` | string | Calcula o valor de venda em vez de informá-lo. Único valor aceito: `current_fair_value` (valor justo contábil atual do ativo). | Até 255 | :::info Regras - O ativo precisa estar **ativo** na carteira do fundo e ser do mesmo tipo de ativo da configuração do lote. - Envie exatamente um entre `external_id` e `contract_number`, e exatamente um entre `sale_value` e `calculation_method`. - Em lotes `assignment_resolution`, o `sale_value` precisa ser igual ao valor de aquisição do ativo (`TRR000053`). ::: ## Response STATUS 201 ```json title='Response Body' { "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10", "asset_resolve_key": "e4a1c9d2-7b3f-4e8a-a5c6-1d2e3f4a5b6c", "asset_status": "pending_wallet_sale" } ``` | `asset_status` | Quando | |-|-| | `pending_wallet_sale` | O preço de venda diverge até 5% do valor justo contábil do ativo. O ativo segue no fluxo. | | `pending_validation` | O preço de venda diverge mais de 5% do valor justo contábil. O ativo fica retido até uma confirmação, que não está disponível na API: alinhe com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). | :::tip Reenvio e duplicidade Em caso de erro, reenvie a requisição. Duplicidade (`TRR000042`) significa que o ativo já está num lote não descartado: não o insira de novo. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ::: ## Erros | Status | Código | Quando acontece | |-|-|-| | 400 | `QIT000001` | Corpo fora do contrato: campo desconhecido ou formato inválido | | 400 | `TRR000050` | Nem `sale_value` nem `calculation_method` foram enviados | | 400 | `TRR000051` | `sale_value` e `calculation_method` enviados juntos | | 400 | `TRR000052` | `calculation_method` diferente de `current_fair_value` | | 400 | `TRR000071` | Nem `external_id` nem `contract_number` foram enviados | | 400 | `TRR000070` | `external_id` e `contract_number` enviados juntos | | 400 | `TRR000072` | O tipo de ativo do lote não aceita `contract_number`: use `external_id` | | 400 | `TRR000021` | O lote não está em `pending_assets_insertion` (já foi encerrado ou descartado) | | 400 | `TRR000029` | Mais de um ativo encontrado: informe `borrower_document_number` ou use `external_id` | | 400 | `TRR000053` | Lote `assignment_resolution` com `sale_value` diferente do valor de aquisição | | 403 | `TRR000049` | O agente não tem acesso a esse fundo ou a esse lote | | 404 | `TRR000006` | Não existe fundo com essa `fund_class_key` | | 404 | `TRR000020` | Lote não encontrado com esse `external_id` | | 404 | `TRR000028` | Ativo não encontrado ativo na carteira do fundo com esse `external_id` | | 404 | `TRR000073` | Ativo não encontrado com esse `contract_number` | | 409 | `TRR000042` | O ativo já está num lote e não foi descartado | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Criação de um lote de recompra URL: /documentation/iaas/venda_ativos/assignment/criacao_recompra Cria o lote (`assignment`) que vai agrupar os ativos a serem recomprados ou vendidos. O lote nasce em `pending_assets_insertion`. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment MÉTODO POST ```json title='Request Body' { "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "assignment_date": "2024-04-01", "assignment_configuration_key": "d9308a2b-21fa-4724-9bbe-59ae65287b10", "source_account": { "document_number": "11.222.333/0001-81" } } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `external_id` * | string | Chave única de identificação deste lote no sistema do parceiro integrador. | Até 50 | | `assignment_date` * | string | Data da recompra. Precisa ser igual à data contábil atual do fundo. | YYYY-MM-DD | | `assignment_configuration_key` | string | Chave da configuração de recompra, fornecida pela QI Tech. Envie esta **ou** `assignment_type`. | 36 | | `assignment_type` | string | Tipo do lote, quando você usa a configuração padrão do fundo para esse tipo: `assignment_repurchase`, `wallet_sale` ou `assignment_resolution`. Envie este **ou** `assignment_configuration_key`. | Até 50 | | `source_account` * | objeto | Conta que fará o pagamento ao fundo | - | :::info Configuração do lote Envie exatamente um entre `assignment_configuration_key` e `assignment_type`. Sem nenhum dos dois a API devolve `TRR000017`; com os dois, `TRR000016`. ::: ## Objeto de source account | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `document_number` * | string | CPF ou CNPJ, com máscara, de quem fará o pagamento ao fundo. Precisa ser um documento válido. | 14 a 18 | ## Response STATUS 201 ```json title='Response Body' { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignment_status": "pending_assets_insertion" } ``` :::tip Reenvio e duplicidade Em caso de erro, reenvie a requisição. Duplicidade (`TRR000015`) significa que o recurso já existe: consulte-o em vez de recriar. Pela `assignor-api`, a consulta é `GET /trade_resolve/fund_class/{fund_class_key}/assignment/{external_id}`; a `manager-api` e a `consultant-api` não expõem essa consulta, então trate `TRR000015` como lote já criado e siga para a [inserção dos ativos](/documentation/iaas/venda_ativos/asset/criacao_recompra). Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ::: ## Erros | Status | Código | Quando acontece | |-|-|-| | 400 | `QIT000001` | Corpo fora do contrato: campo obrigatório ausente, campo desconhecido, formato inválido | | 400 | `TRR000014` | `assignment_date` diferente da data contábil do fundo | | 400 | `TRR000002` | `source_account.document_number` não é um CPF ou CNPJ válido | | 400 | `TRR000016` | `assignment_configuration_key` e `assignment_type` enviados juntos | | 400 | `TRR000017` | Nem `assignment_configuration_key` nem `assignment_type` foram enviados | | 400 | `TRR000019` | A configuração de recompra não está ativa | | 403 | `TRR000049` | O agente não tem acesso a esse fundo ou a essa configuração de recompra | | 404 | `TRR000006` | Não existe fundo com essa `fund_class_key` | | 404 | `TRR000013` | Configuração de recompra não encontrada para o fundo (ou o fundo não tem configuração padrão para o `assignment_type`) | | 404 | `TRR000018` | `assignment_type` não existe | | 409 | `TRR000015` | Já existe um lote com esse `external_id` no fundo | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Encerrar inserção de ativos URL: /documentation/iaas/venda_ativos/assignment/fechamento_recompra Encerra a inserção de ativos de um lote em `pending_assets_insertion`. O lote precisa ter ao menos um ativo não descartado. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/ASSIGNMENT_EXTERNAL_ID MÉTODO PUT ```json title='Request Body' { "assignment_status": "completed_assets_insertion", "number_of_assets": 2, "total_value": 2469.12 } ``` ### Body Params | Campo | Tipo | Descrição | |-|-|-| | `assignment_status` * | string | Único valor aceito: `completed_assets_insertion` | | `number_of_assets` | number | Quantidade de ativos não descartados que você espera no lote. Se enviada e divergir, a API recusa o encerramento (`TRR000067`). | | `total_value` | number | Soma dos `sale_value` dos ativos não descartados que você espera no lote. Se enviada e divergir, a API recusa o encerramento (`TRR000066`). | ## Response STATUS 200 ```json title='Response Body' { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignment_status": "completed_assets_insertion" } ``` Em lotes com termo externo, `assignment_status` volta como `pending_signed_term_submission`. Veja [Termo de Recompra](/documentation/iaas/venda_ativos/inicio#4-termo-de-recompra). ## Erros | Status | Código | Quando acontece | |-|-|-| | 400 | `QIT000001` | Corpo fora do contrato: `assignment_status` ausente ou campo desconhecido | | 400 | `TRR000033` | O lote não está em `pending_assets_insertion` | | 400 | `TRR000021` | `assignment_status` diferente de `completed_assets_insertion` | | 400 | `TRR000034` | O lote não tem nenhum ativo não descartado | | 400 | `TRR000067` | `number_of_assets` diferente da quantidade de ativos do lote | | 400 | `TRR000066` | `total_value` diferente da soma dos ativos do lote | | 403 | `TRR000049` | O agente não tem acesso a esse fundo ou a esse lote | | 404 | `TRR000006` | Não existe fundo com essa `fund_class_key` | | 404 | `TRR000020` | Lote não encontrado com esse `external_id`. Pelo `assignor-api`, o mesmo caso volta como `TRR000013`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Recompra e Venda de Ativos URL: /documentation/iaas/venda_ativos/inicio Esta seção documenta as APIs que viabilizam a **venda e a recompra de direitos creditórios** já encarteirados nos fundos administrados pela QI DTVM. O fluxo abrange desde a criação do lote até a baixa dos ativos da carteira do fundo. :::tip Contexto Este serviço apenas **baixa os ativos da carteira** do fundo. Ele não envia dados para outras administradoras. Existem dois conceitos fundamentais: o **lote** (`assignment`) e o **ativo** (`asset`). Um lote é composto por um ou mais ativos, e cada ativo inserido precisa já estar na carteira do fundo. ::: :::info Pré-requisitos - Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de sandbox e produção. - Você precisará da `fund_class_key` (chave do fundo), que compõe a URL base de todos os endpoints desta API, e da `assignment_configuration_key` (chave da configuração), informada na criação do lote: ```text /trade_resolve/fund_class/{fund_class_key} ``` ::: ## Fluxo de venda/recompra O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação. 5%', dashed: true }, { from: 'validacao', to: 'encerramento', label: 'confirmado', dashed: true }, { from: 'ativos', to: 'encerramento' }, { from: 'encerramento', to: 'descartado', label: 'discarded', tone: 'end' }, { from: 'encerramento', to: 'termo', label: 'encerrado', tone: 'ok' }, { from: 'termo', to: 'credito', label: 'assinado' }, { from: 'credito', to: 'baixa', label: 'pago' }, ]} /> ## Passo a passo ### 1. Criação do Lote Crie o lote informando um identificador único (`external_id`), a data da operação (a data contábil atual do fundo) e o documento de quem fará o pagamento ao fundo. O lote nasce em `pending_assets_insertion` e é o contêiner de todos os ativos que serão baixados. **[Acessar documentação da criação do lote](/documentation/iaas/venda_ativos/assignment/criacao_recompra)** ### 2. Inserção dos Ativos Insira um ativo por requisição, identificando-o pelo mesmo `external_id` com que ele foi encarteirado (ou pelo número do contrato). O ativo precisa estar **ativo** na carteira do fundo no momento da inserção. **[Acessar documentação da inserção de ativos](/documentation/iaas/venda_ativos/asset/criacao_recompra)** :::caution Divergência de preço acima de 5% Se o preço de venda informado divergir em **mais de 5%** do valor justo contábil do ativo, o ativo não segue automaticamente: ele fica em `pending_validation` e exige uma confirmação antes de entrar na baixa. Divergências de até 5% seguem direto para `pending_wallet_sale`. A confirmação não está disponível na API. Enquanto houver ativo em `pending_validation`, o lote não avança depois do encerramento. Se o seu fluxo pode gerar divergências acima de 5%, alinhe o procedimento com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). ::: ### 3. Encerramento do Lote Após inserir todos os ativos, encerre o lote. É necessário ter ao menos um ativo não descartado. Opcionalmente, você pode enviar `number_of_assets` e `total_value` para que a API confira a quantidade e o valor total consolidados antes de aceitar o encerramento. O lote só pode ser descartado até esta etapa, e o descarte do lote não está disponível na API: solicite a [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). **[Acessar documentação do encerramento](/documentation/iaas/venda_ativos/assignment/fechamento_recompra)** ### 4. Termo de Recompra O responsável pela emissão do Termo de Recompra depende da configuração do lote: - **Termo interno** — quando todos os ativos estão prontos para a baixa, a QI Tech gera o termo (`pending_documents_generation`) e coleta as assinaturas das partes (`pending_documents_signature`). Nenhuma ação do integrador é necessária. - **Termo externo** — o lote passa para `pending_signed_term_submission` e precisa receber o termo já assinado. O envio desse termo **não está disponível** na `manager-api`, na `consultant-api` nem na `assignor-api`: antes de operar com termo externo, combine o envio com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). Em ambos os casos, com o termo assinado o lote passa a `pending_payment`, aguardando o crédito na conta do fundo. ### 5. Pagamento e Baixa dos Ativos As etapas finais são automatizadas: a QI Tech confirma o crédito na conta do fundo, o lote passa a `pending_wallet_sale`, os ativos são baixados da carteira e, quando todos os ativos são concluídos, o lote é encerrado em `completed`. ## Webhook Quando o termo **interno** é assinado e o lote passa a `pending_payment`, a QI Tech envia o webhook `trade_resolve.assignment_status_change` aos agentes cadastrados na configuração do lote. É o único status que emite webhook: lotes com termo externo não recebem este evento. O cadastro é feito pela QI Tech: solicite em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). Para validar a assinatura, veja [Autenticação de webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ```json title='Webhook Body' { "webhook_type": "trade_resolve.assignment_status_change", "webhook_datetime": "2024-04-02T10:15:00Z", "data": { "assignment_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "assignment_new_status": "pending_payment", "signed_term_url": "https://URL_TEMPORARIA_DO_TERMO" } } ``` | Campo | Descrição | |-|-| | `assignment_external_id` | `external_id` do lote | | `assignment_new_status` | Novo status do lote: `pending_payment` | | `signed_term_url` | Link para baixar o termo assinado. Expira em 24 horas. |