Roteiro de Integração de escrituração de notas comerciais
O roteiro de homologação descreve todos os recursos e funcionalidades que precisam ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), antes da entrada em ambiente de produção para emissão de notas comerciais.
Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto.
Atenção
Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes). As operações realizadas em ambiente de Sandbox são operações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.
Cadastro e Autenticação API Escrituração
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
|---|---|---|---|---|
| CAB0001* | Troca de chaves públicas | Realizar a troca de chaves públicas com o time operações de plataforma (suporte.dcm@qitech.com.br) | Link Documentação | |
| CAB0002* | Teste de autenticação de chamadas | Após receber a chave de api com o time de plataformas, finalizar teste de autenticação de chamadas | Link Documentação Link Documentação | CAB0001 |
| CAB0003* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI. | Link Documentação Link Documentação Link Documentação | CAB0001 e CAB0002 |
Homologação do Emissor
Atenção
Para o fluxo de homologação do emissor, caso o cliente já tenha realizado a integração com o cadastros de cedentes QI TECH, é possível reutilizar esses cadastros, simplificando a homologação no sistema de escrituração
Homologação do emissor para cadastros feitos no sistema de cedentes QI TECH
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
|---|---|---|---|---|
| CED1001* | Reaproveitar cadastro cedente | Realizar o reaproveitamento do cadastro de cedente utilizando o CNPJ do mesmo. | Link Documentação | |
| CED1002* | Listagem dos emissores cadastrados | Listagem dos cedentes cadastrados, com filtros por CNPJ, nome | Link Documentação | |
| CED1003* | Detalhes do emissor | Visualizar os detalhes de um emissor cadastrado, por issuer_key | Link Documentação |
Homologação do emissor para cadastros feitos pelo sistema de escrituração
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
|---|---|---|---|---|
| CED0001* | Cadastro Básico do emissor | Criar o emissor, informando as informações básicas do cadastro. | Link Documentação | |
| CED0002* | Envio e remoção de Documentos do Emissor | Envio e remoção de documentos associados a um emissor previamente cadastrado | Link Documentação Link Documentação | CED0001 |
| CED0003* | Cadastro e remoção de Representantes do Emissor | Envio e remoção de representantes associados a um emissor previamente cadastrado | Link Documentação Link Documentação | CED0001 |
| CED0004* | Envio e remoção de Documentos do Representante do Emissor | envio e remoção de documentos associados a um representante de um emissor previamente cadastrado | Link Documentação Link Documentação | CED0001, CED0003 |
| CED0005* | Cadastro e remoção de Conta Bancária do Emissor | cadastro e remoção de conta bancária associada a um emissor previamente cadastrado | Link Documentação Link Documentação | CED0001 |
| CED0006* | Cadastro e remoção de Grupos de Assinantes do Emissor | cadastro e remoção de grupos de assinantes associados a um emissor previamente cadastrado | Link Documentação Link Documentação | CED0001 |
| CED0007* | Cadastro e remoção de Informações de Contato do Emissor | cadastro e remoção de informações de contato associadas a um emissor previamente cadastrado | Link Documentação Link Documentação | CED0001 |
| CED0008* | Envio para Análise do Emissor | Este endpoint permite alterar o status de um emissor para análise, enviando-o para o processo de validação. | Link Documentação | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0009* | Alteração de Cadastro do Emissor | alterar emissor para permitir edição | Link Documentação | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0010* | Listagem dos emissores cadastrados | Listagem dos cedentes cadastrados, com filtros por CNPJ, nome | Link Documentação | |
| CED0011* | Detalhes do emissor | Visualizar os detalhes de um emissor cadastrado, por issuer_key | Link Documentação |
Homologação do Investidor
Atenção
Para o fluxo de homologação do investidor, caso o cliente tenha fundos fixos, é possível realizar o cadastro desses no setup, simplificando a integração.
Homologação do investidor para cadastros feitos no setup
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
|---|---|---|---|---|
| INV1001* | Listagem dos investidores cadastrados | Listagem dos fundos cadastrados, com filtros por CNPJ, nome | Link Documentação | |
| INV1002* | Detalhes do investidor | Visualizar os detalhes de um investidor cadastro, por investor_key | Link Documentação |
Homologação do investidor para cadastros feitos pelo sistema de escrituração
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
|---|---|---|---|---|
| INV0001* | Cadastro Básico do investidor | Criar o investidor, informando as informações básicas do cadastro. | Link Documentação | |
| INV0002* | Envio e remoção de Documentos do investidor | Envio e remoção de documentos associados a um investidor previamente cadastrado | Link Documentação Link Documentação | INV0001 |
| INV0003* | Cadastro e remoção de Representantes do investidor | Envio e remoção de representantes associados a um investidor previamente cadastrado | Link Documentação Link Documentação | INV0001 |
| INV0004* | Envio e remoção de Documentos do Representante do investidor | envio e remoção de documentos associados a um representante de um investidor previamente cadastrado | Link Documentação Link Documentação | INV0001, INV0003 |
| INV0005* | Cadastro e remoção de Conta Bancária do investidor | cadastro e remoção de conta bancária associada a um investidor previamente cadastrado | Link Documentação Link Documentação | INV0001 |
| INV0006* | Cadastro e remoção de Grupos de Assinantes do investidor | cadastro e remoção de grupos de assinantes associados a um investidor previamente cadastrado | Link Documentação Link Documentação | INV0001 |
| INV0007* | Cadastro e remoção de Informações de Contato do investidor | cadastro e remoção de informações de contato associadas a um investidor previamente cadastrado | Link Documentação Link Documentação | INV0001 |
| INV0008* | Envio para Análise do investidor | Este endpoint permite alterar o status de um investidor para análise, enviando-o para o processo de validação. | Link Documentação | INV0001, INV0002, INV0003, INV0004, INV0005, INV0006, INV0007 |
| INV0009* | Alteração de Cadastro do investidor | alterar investidor para permitir edição | Link Documentação | INV0001, INV0002, INV0003, INV0004, INV0005, INV0006, INV0007 |
| INV0010* | Listagem dos investidores cadastrados | Listagem dos fundos cadastrados, com filtros por CNPJ, nome | Link Documentação | |
| INV0011* | Detalhes do investidor | Visualizar os detalhes de um investidor cadastrado, por investor_key | Link Documentação |
Emissão de nota comercial
Após os cadastros de emissores e investidores, é possível realizar a emissão de notas comerciais. Para isso, existem algumas combinações de fluxos de emissão, que serão contempladas abaixo.
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
|---|---|---|---|---|
| COM0001* | Simulação de condições financeiras | simular as condições financeiras e o fluxo de pagamentos de uma operação | Link Documentação | |
| COM0002* | Cadastro de Operação de Nota Comercial | criar uma nova operação de nota comercial com base nos dados financeiros e de investidores. | Link Documentação | COM0001 |
| COM0003* | Cadastro e Remoção de Partes Relacionadas | cadastro e a remoção de partes relacionadas a uma operação | Link Documentação | COM0002 |
| COM0004* | Envio e Remoção de Documentos de Representantes de Partes Relacionadas | envio e a remoção de documentos associados a representantes de partes relacionadas a uma operação | Link Documentação | COM0002, COM0003 |
| COM0005* | Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas | envio e a remoção de grupos de assinantes associados a representantes de partes relacionadas a uma operação | Link Documentação | COM0002, COM0003 |
| COM0006 | Pré-visualizar Termo Constitutivo | geração de uma minuta do Termo Constitutivo para uma operação específica, utilizando um template predefinido. | Link Documentação | COM0002 |
| COM0007* | Alterar Template do Termo Constitutivo | alteração do template do Termo Constitutivo para uma operação específica | Link Documentação | COM0002 |
| COM0008* | Envio de documentos | envio de documentos associados a uma operação. O "document_key" retornado poderá ser utilizado, por exemplo, no sistema de garantias | Link Documentação | COM0002 |
| COM0009* | Envio de Garantia na Operação | adição de garantias associadas a uma operação | Link Documentação | COM0002, COM0008 |
| COM0010* | Cadastro e Remoção de Partes Relacionadas de um contrato/Garantia | cadastro e a remoção de partes relacionadas de um contrato/garantia específicos da operação | Link Documentação | COM0002, COM0003 |
| COM0011* | Enviar Operação para Análise | alterar o status de uma operação para "em análise", enviando-a para o processo de validação de compliance pelo escriturador | Link Documentação | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0012* | Enviar Atas de Aprovação Assinadas | Este endpoint permite enviar as atas de aprovação de empresas do tipo SA ou COP assinadas de forma externa para o sistema de escrituação, enviando um base64 que será analisado e aprovado pelo escriturador. | Link Documentação | COM0002 |
| COM0013* | Consulta de Operações por Filtros | consultar operações de nota comercial utilizando filtros opcionais | Link Documentação | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0014* | Consulta de Operação por Chave | consultar os detalhes completos de uma operação específica, utilizando sua chave única. | Link Documentação | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
Caso assinatura seja via QI SIGN
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
|---|---|---|---|---|
| COM0015* | Consulta dos Links para assinatura via QI SIGN da Operação | consultar todos os links para assinatura de uma operação específica via QI SIGN, utilizando sua chave única. | Link Documentação | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0016* | Consulta do Link dos contratos assinados via QI SIGN da Operação | consultar todos os documentos assinados de uma operação específica via QI SIGN, utilizando sua chave única | Link Documentação | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
Processo de integralização/Subscrição
| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
|---|---|---|---|---|
| INT0001* | Consulta de Integralização por Chave | consultar os detalhes de um processo de integralização utilizando sua chave única | Link Documentação | |
| INT0002* | Consulta de Subscrição | consultar uma subcrição em andamento | Link Documentação | INT0001 |
| INT0003 | Cadastro de Subscrição | registrar a intenção de um investidor em subscrever uma quantidade específica de cotas de uma integralização (útil caso seja necessário deslocar a data de uma subscrição) | Link Documentação | INT0001, INT0002 |
| INT0004 | Cancelar subscrição | cancelar subscrição (útil caso seja necessário deslocar a data de uma subscrição) | Link Documentação | INT0001, INT0002 |
Roteiro de Integração de Amortização Extraordinária
Este roteiro descreve, em ordem, os passos que o integrador executa para registrar uma amortização extraordinária na QI Tech — desde a identificação das parcelas-alvo até o 201 da chamada de criação. A criação é fire-and-forget: o integrador apenas cria o evento; a liquidação, o cancelamento e a finalização são orquestrados internamente pela QI Tech (account-liquidation-api liquida quando o pagamento entra; a rotina diária de settlement do security-service decide cancelar ou finalizar). A referência completa do endpoint de criação é apresentada na seção de Endpoints.
Antes de começar, confirme que o Conceito já está claro, especialmente os cinco valores possíveis de amortization_type e o papel do reference_date.
Atenção
Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech. Chamadas de amortização extraordinária movimentam installment.paid_amount e consomem Valor Presente — valide o fluxo completo em sandbox antes de habilitar em produção.
Pré-requisitos
- API key configurada — Troca de chaves.
- Security criado e integralizado — Emissão de notas e Integralização de cotas.
- Conceitos do produto compreendidos — Conceito.
Fluxo passo a passo
O fluxo completo tem quatro etapas. Cada linha da tabela indica quem executa a ação, qual chamada ou evento ocorre e o que merece atenção durante a execução.
| # | Etapa | Responsável | Chamada / Evento | Observação |
|---|---|---|---|---|
| 1 | Identificar parcelas-alvo | Integrador | GET /security/security/{security_key} | Obtém installment_number e os valores correntes das parcelas, usados para escolher o tipo e o montante da amortização. Não é necessário extrair installment_key — a criação trabalha apenas com os números das parcelas. |
| 2 | Criar a amortização extraordinária | Integrador | POST /event_conciliation/extraordinary_event | Envie security_key, investment_key, amortization_type, amount, reference_date, due_date e, quando aplicável, installment_list (array de installment_number, inteiros ≥ 1). A resposta 201 traz o extraordinary_event_conciliation_key (evento extraordinário de amortização único) e a lista event_conciliation_list (evento de conciliação de cada parcela). A partir daqui é fire-and-forget para o integrador. |
| 3 | Confirmar pagamento externo | Integrador / Provedor | Conciliação de recebíveis | Aguarde a confirmação do recebimento dos valores pelo canal combinado. Os eventos de conciliação da parcela permanecem em pending_conciliation enquanto o pagamento não chega. |
| 4 | Liquidação ou finalização automática | QI Tech | Orquestração interna | Ao detectar a entrada do pagamento, a QI Tech (via account-liquidation-api) liquida cada parcela. Caso o pagamento não chegue, a rotina diária de settlement do security-service finaliza ou cancela o evento. Em ambos os casos não há ação do integrador. |
Ao criar, o evento nasce em pending_conciliation. A transição para paid ocorre só depois da etapa 4 do fluxo acima.
Pontos de atenção
Atenção
reference_dateé obrigatório e fornecido pelo chamador — deve corresponder à data de quitação do evento extraordinário.- Liquidação, finalização e cancelamento são internos — o integrador apenas cria o evento; a QI Tech orquestra o restante. Não há webhook tenant-facing dedicado para as transições de status do
event_conciliationextraordinário. - Para investidores em
internal_legacy_system(CTVM), a liquidação interna é assíncrona — o estado final (paidousettlement_failed) é definido pelo cron de autoconciliate.
Próximos passos
Para a referência completa do endpoint de criação, consulte Criar Amortização Extraordinária. As regras de negócio detalhadas (tolerância, discriminação por reference_date, ordem de distribuição por tipo, fluxo interno de liquidação e cancelamento) estão consolidadas em Regras de Negócio. Para cenários completos passo-a-passo com JSON bodies reais, veja Exemplos.
Mapeamento de erros
Os erros originários das apis de emissores, investidores e nota comercial podem ser encontrados em Link Catálogo de Erros