# QI Tech — Investment-as-a-Service › Bookkeeping Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 130 página(s). Índice: - Aditamento (/en/documentation/escrituracao/aditamento/conceito) - Baixar Documento (/en/documentation/escrituracao/aditamento/endpoints/baixar-documento) - Cancelar Aditamento (/en/documentation/escrituracao/aditamento/endpoints/cancelar-aditamento) - Consultar Aditamento (/en/documentation/escrituracao/aditamento/endpoints/consultar-aditamento) - Consultar Signatários (/en/documentation/escrituracao/aditamento/endpoints/consultar-signatarios) - Criar Aditamento (/en/documentation/escrituracao/aditamento/endpoints/criar-aditamento) - Simular Aditamento (/en/documentation/escrituracao/aditamento/endpoints/simular-aditamento) - Validar Aditamento (/en/documentation/escrituracao/aditamento/endpoints/validar-aditamento) - Exemplos (/en/documentation/escrituracao/aditamento/exemplos) - Regras de Negócio — Aditamento (/en/documentation/escrituracao/aditamento/regras-de-negocio) - Tipos de Alteração (/en/documentation/escrituracao/aditamento/tipos-de-alteracao) - Extraordinary Amortization (/en/documentation/escrituracao/amortizacao-extraordinaria/conceito) - Query Extraordinary Amortization (/en/documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao) - Create Extraordinary Amortization (/en/documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao) - Simulate the Present Value of an Extraordinary Amortization (/en/documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente) - Examples — Extraordinary Amortization (/en/documentation/escrituracao/amortizacao-extraordinaria/exemplos) - Amortization with Repurchase (/en/documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao) - Business Rules — Extraordinary Amortization (/en/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio) - Error Catalog (/en/documentation/escrituracao/catalogo-erros/catalogo-erros) - Webhook Configuration (/en/documentation/escrituracao/configuracao-webhooks) - Register Underlying Asset (Lastro) (/en/documentation/escrituracao/emissao-cr/cadastro-lastro) - Register CR Operation (/en/documentation/escrituracao/emissao-cr/cadastro-operacao) - Send Document (/en/documentation/escrituracao/emissao-cr/envio-documento) - Send Operation External Document (/en/documentation/escrituracao/emissao-cr/envio-documento-externo) - Register Underlying Asset (Lastro) (/en/documentation/escrituracao/emissao-cra/cadastro-lastro) - Register CRA Operation (/en/documentation/escrituracao/emissao-cra/cadastro-operacao) - Send Document (/en/documentation/escrituracao/emissao-cra/envio-documento) - Send Operation External Document (/en/documentation/escrituracao/emissao-cra/envio-documento-externo) - Register Underlying Asset (Lastro) (/en/documentation/escrituracao/emissao-cri/cadastro-lastro) - Register CRI Operation (/en/documentation/escrituracao/emissao-cri/cadastro-operacao) - Send Document (/en/documentation/escrituracao/emissao-cri/envio-documento) - Send Operation External Document (/en/documentation/escrituracao/emissao-cri/envio-documento-externo) - Operation disbursement account update. (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso) - Financial Data Update in Operation (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros) - Signature Method Update in Operation (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura) - Sending Collateral in an Operation (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) - Collateral Removal from Operation (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia) - Document Upload (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento) - Operation Metadata Registration and Removal (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao) - Related Party Representative Document Upload and Removal (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento) - Related Party Representative Signer Group Upload and Removal (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) - Specific Document Related Party Registration and Removal (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento) - Related Party Registration and Removal (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) - Commercial Paper Operation Registration (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) - Third-party disbursement on the operation (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro) - Extra Fields (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields) - Client acceptance log upload (/en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite) - Cancel Operation (/en/documentation/escrituracao/emissao-de-notas/cancelar-operacao) - Query Signed Contract Link via QI SIGN of the Operation (/en/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) - Query Signature Links via QI SIGN for Operation (/en/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) - Consulta dos Documentos da Operação (/en/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao) - Operation Query by Key (/en/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) - Operation Query by Filters (/en/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) - Next Issue Number Query by Issuer (/en/documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao) - Send Signed Approval Minutes (/en/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) - Send Signed Operation Documents (/en/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados) - Send Operation for Analysis (/en/documentation/escrituracao/emissao-de-notas/envio-para-analise) - Send Operation for Signature (/en/documentation/escrituracao/emissao-de-notas/envio-para-assinatura) - Change Adhesion Term Template (/en/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta) - Change Commercial Paper Template (/en/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) - Preview Adhesion Term (/en/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao) - Preview Commercial Paper Term (/en/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) - Introduction to Commercial Paper Issuance (/en/documentation/escrituracao/emissao-de-notas/inicio) - Financial Conditions Simulation (/en/documentation/escrituracao/emissao-de-notas/simulacao) - Register Debenture Operation (/en/documentation/escrituracao/emissao-debentures/cadastro-operacao) - Send Document (/en/documentation/escrituracao/emissao-debentures/envio-documento) - Send Operation External Document (/en/documentation/escrituracao/emissao-debentures/envio-documento-externo) - Send Operation Collateral (/en/documentation/escrituracao/emissao-debentures/envio-garantia) - Issuer Registration Update (/en/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) - Consulta da Auto-assinatura (/en/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) - Consulta dos Links de Assinatura do Termo de Adesão (/en/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) - Auto-assinatura do Emissor (/en/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) - Solicitação da Auto-assinatura (/en/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) - Issuer Signer Groups Registration (/en/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) - Issuer Signer Groups Removal (/en/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) - Issuer Registration (/en/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) - Issuer Bank Account Registration (/en/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor) - Setting the Issuer's Primary Bank Account (/en/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal) - Issuer Bank Account Removal (/en/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) - Issuer Documents Submission (/en/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor) - Issuer Documents Removal (/en/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) - Issuer Representative Document Upload (/en/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor) - Issuer Representative Document Removal (/en/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) - Issuer Contact Information Registration (/en/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor) - Setting the Issuer's Primary Contact (/en/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal) - Issuer Contact Information Removal (/en/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) - Issuer Representatives Registration (/en/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor) - Issuer Representative Removal (/en/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) - Get Issuer (/en/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) - Issuer Query by Filters (/en/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) - Issuer Analysis Submission (/en/documentation/escrituracao/homologacao-emissor/envio-analise/) - Introduction (/en/documentation/escrituracao/homologacao-emissor/inicio) - Issuer Data Access Request (/en/documentation/escrituracao/homologacao-emissor/solicitacao-acesso) - Investor Registration Update (/en/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/) - Investor Signer Groups Registration (/en/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor) - Investor Signer Groups Removal (/en/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) - Investor Registration (/en/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico) - Investor Bank Account Registration (/en/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor) - Investor Bank Account Removal (/en/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) - Investor Documents Submission (/en/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor) - Investor Documents Removal (/en/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) - Investor Representative Documents Submission (/en/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor) - Investor Representative Documents Removal (/en/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) - Investor Contact Information Registration (/en/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor) - Investor Contact Information Removal (/en/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao) - Investor Representatives Registration (/en/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor) - Investor Representative Removal (/en/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) - Get Investor (/en/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) - Investor Query by Filters (/en/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) - Investor Analysis Submission (/en/documentation/escrituracao/homologacao-investidor/envio-analise/) - Introduction (/en/documentation/escrituracao/homologacao-investidor/inicio) - **Investor Data Access Request** (/en/documentation/escrituracao/homologacao-investidor/solicitacao-acesso) - Get Transaction Receipt (/en/documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao) - Settlement Account Query (/en/documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao) - Get Integralization by Key (/en/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) - Get Integralization Transactions (/en/documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao) - Introduction to Shares Integralization (/en/documentation/escrituracao/integralizacao-cotas/inicio) - Subscription Registration (/en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao) - Cancel Subscription (/en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao) - Subscription Payment Confirmation or Rejection (/en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento) - Get Subscription (/en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas) - Subscription Payment Registration (/en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento) - Receiving Webhooks (/en/documentation/escrituracao/introducao/autenticacao_webhooks) - Commercial Paper Bookkeeping (/en/documentation/escrituracao/introducao/) - Test endpoints (/en/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) - Authentication test (/en/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao) - Keys Exchange (/en/documentation/escrituracao/introducao/troca_de_chaves) - Asset Query (/en/documentation/escrituracao/operacoes-ativas/consulta-security) - Investor Position (/en/documentation/escrituracao/operacoes-ativas/posicao-investidor) - Webhooks (/en/documentation/escrituracao/webhooks-escrituracao) --- # Aditamento URL: /en/documentation/escrituracao/aditamento/conceito ## Visão geral Aditamento é o processo de alterar as condições de um título já emitido. Depois que a Nota Comercial foi assinada e emitida, qualquer mudança nas condições pactuadas — repactuar o fluxo de pagamento, substituir uma garantia, incluir ou remover um avalista, corrigir o número da emissão — precisa ser formalizada em um termo aditivo assinado pelas partes. A QI Tech recebe esse pedido via API, valida a elegibilidade do título, calcula o novo fluxo, gera o termo aditivo, cobra a taxa do serviço, coleta as assinaturas e só então aplica as alterações no título. O resultado é um evento rastreável, com `status` próprio, histórico de transições e os documentos assinados disponíveis para download. O integrador inicia o fluxo com uma chamada e acompanha o restante por consulta. As etapas intermediárias — geração do termo, emissão do boleto, envio do envelope de assinatura, aplicação das alterações — são orquestradas internamente pela QI Tech. ## O que pode ser aditado Cada aditamento carrega uma ou mais alterações, no campo `changes`. Os cinco tipos ficam em `changes[].type`: - `financial_flow` (fluxo financeiro) — repactuação do cronograma: novas datas de vencimento, novos valores e/ou nova taxa de juros. - `collateral` (garantia) — inclusão ou remoção de uma garantia do título. - `related_party` (parte relacionada) — inclusão, alteração ou remoção de avalista, devedor solidário, fiel depositário e demais papéis. - `issue_number` (número da emissão) — correção do número da emissão. - `term_clause` (cláusula do termo) — regeração do documento com campos livres preenchidos pelo solicitante. Um mesmo aditamento pode combinar vários tipos. As alterações são aplicadas em conjunto: ou todas valem, ou nenhuma vale. ## Conceitos-chave - **`financial_base_date`** — data em que o aditamento passa a valer e a âncora de todo o cálculo. O saldo devedor é apurado nessa data e o novo fluxo parte dela. Aditamento com data base no passado é recusado, salvo operações com origem de tombamento. - **`outstanding_balance`** (saldo devedor) — calculado internamente na `financial_base_date` e devolvido na simulação, na validação e na consulta. O integrador não precisa calcular saldo devedor do seu lado. - **Fechamento (`closing`)** — em uma repactuação de fluxo, a QI Tech confere se o novo cronograma fecha contra o valor presente do título dentro de uma tolerância. Um fluxo que não fecha faz o aditamento nascer recusado, com o `difference` e a `tolerance` na resposta. - **Termo aditivo** — o documento que formaliza a alteração. Pode ser **gerado pela QI Tech** a partir dos dados do aditamento, ou **enviado pronto pelo integrador** no array `documents`. A escolha muda o caminho que o aditamento percorre (veja [Regras de Negócio](./regras-de-negocio.md)). - **Cobrança** — o aditamento tem uma taxa, cobrada por boleto. O pagamento é o que libera o envio do termo para assinatura. O valor segue a configuração comercial do seu contrato e vem na simulação, em `charge_amount`. - **Envelope de assinatura** — o conjunto de signatários do termo. Os signatários vêm dos grupos de assinatura cadastrados na operação; uma parte relacionada incluída pelo próprio aditamento também pode ser eleita signatária. - **Um aditamento por vez** — um título só admite um aditamento em andamento. Enquanto o anterior não chega a um estado terminal, uma nova criação é recusada com `AMD000031`. ## O ciclo de vida Um aditamento atravessa a esteira uma vez, e cada parada espera por uma coisa só: | `status` | O que está acontecendo | | --- | --- | | `created` | Criado e roteado. Estado transitório. | | `validation_failed` | Recusado na validação. Nada foi cobrado nem assinado. Estado terminal. | | `pending_manual_approval` | O termo foi enviado pronto pelo integrador e aguarda conferência da QI Tech. | | `pending_term_generation` | A QI Tech está gerando o termo aditivo. | | `pending_charge_settlement` | Boleto emitido, aguardando o pagamento da taxa. | | `pending_signature` | Montando e enviando o envelope de assinatura. | | `pending_signature_confirmation` | Envelope enviado, aguardando os signatários. | | `pending_application` | Aplicando as alterações no título. | | `applied` | Alterações aplicadas. Estado terminal. | | `application_failed` | Falha ao aplicar. Estado terminal até intervenção. | | `canceled` | Cancelado ou recusado. O motivo fica em `status_reason`. Estado terminal. | :::info Acompanhamento por consulta Não há webhook dedicado às transições de status do aditamento. Acompanhe pelo endpoint de [consulta](./endpoints/consultar-aditamento.md) — o campo `status_history` traz cada transição com data, ator e motivo. ::: ## Próximos passos - [Regras de Negócio](./regras-de-negocio.md) — elegibilidade, fechamento, assinatura e cancelamento. - [Tipos de Alteração](./tipos-de-alteracao.md) — o formato de `new_value` para cada `type`. - [Simular Aditamento](./endpoints/simular-aditamento.md) — o ensaio, sem criar nada. - [Criar Aditamento](./endpoints/criar-aditamento.md) — o disparo do rito. - [Exemplos](./exemplos.md) — casos completos de ponta a ponta. --- # Baixar Documento URL: /en/documentation/escrituracao/aditamento/endpoints/baixar-documento Devolve o conteúdo de um documento do aditamento em base64 — o termo aditivo gerado pela QI Tech, o termo que você enviou, ou a versão assinada. --- ## **Request** ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY /document/ DOCUMENT-KEY MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres | | --- | --- | --- | --- | | `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave do documento (UUID v4), obtida em `documents[].document_key` na [consulta](./consultar-aditamento.md). | 36 | ### **Query Params** | Campo | Tipo | Obrigatório | Padrão | Descrição | | --- | --- | --- | --- | --- | | `is_signed` | boolean | Não | `false` | Quando `true`, devolve a **versão assinada** do documento. | --- ## **Response** STATUS 200 ```json { "document_base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2UvTWVkaWFCb3hbMCAwIDU5NSA4NDJd..." } ``` | Campo | Tipo | Descrição | | --- | --- | --- | | `document_base64` | string | Conteúdo do arquivo em base64. | :::caution A versão assinada só existe depois da assinatura `is_signed=true` em um documento que ainda não foi assinado retorna `AMD000038`. Confira o campo `documents[].signed_file_key` na consulta: ele só é preenchido quando a versão assinada está disponível. ::: --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000017` | Aditamento não encontrado. | | 403 | `AMD000018` | O aditamento não pertence ao seu tenant. | | 404 | `AMD000037` | Documento não encontrado neste aditamento. | | 422 | `AMD000038` | O documento ainda não tem versão assinada. | ## Veja também - [Consultar Aditamento](./consultar-aditamento.md) - [Consultar Signatários](./consultar-signatarios.md) --- # Cancelar Aditamento URL: /en/documentation/escrituracao/aditamento/endpoints/cancelar-aditamento Desiste de um aditamento em andamento. O aditamento vai para `canceled` com `status_reason: withdrawn_by_tenant`. --- ## **Request** ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY /cancel MÉTODO PATCH ### **Path Params** | Campo | Tipo | Descrição | Caracteres | | --- | --- | --- | --- | | `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 | ### **Request Body** Nenhum. A requisição não leva corpo. --- ## Quando o cancelamento é aceito | `status` | Cancelável | | --- | --- | | `created` | Sim | | `pending_manual_approval` | Sim | | `pending_term_generation` | Sim | | `pending_charge_settlement` | Sim | | `pending_signature` | Sim | | `pending_signature_confirmation` | Sim | | `pending_application` | **Não** | | `applied` · `canceled` · `validation_failed` · `application_failed` | **Não** | :::caution Ponto sem volta A partir de `pending_application` o cancelamento deixa de ser aceito — a recusa é `AMD000012`, com o status atual na mensagem. Se precisar reverter um aditamento já aplicado, fale com o seu contato comercial na QI Tech: é um procedimento próprio, não uma chamada de API. ::: ## Efeitos fora do aditamento O cancelamento não se limita a mudar o `status`. Ele também: - **Baixa o boleto da taxa**, se houver um em aberto. Um boleto já compensado não é baixado — nesse caso, o estorno segue o seu contrato comercial. - **Cancela o envelope de assinatura**, se o termo já tiver sido enviado. Links de assinatura já distribuídos deixam de funcionar. --- ## **Response** STATUS 200 A resposta é o objeto completo do aditamento, já com `status: canceled`. Response Body ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "status": "canceled", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "amendment_number": 2, "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47", "operation_type": "commercial_paper", "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "created_by": "integration", "created_at": "2026-09-14T10:22:41", "applied_at": null, "envelope_key": null, "signature_method": "certifiqi", "changes": ["..."], "documents": ["..."], "charges": [ { "amendment_charge_key": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f", "charge_status": "canceled", "amount": 500.00, "settled_at": null, "charge_status_history": ["..."] } ], "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }, { "status": "pending_charge_settlement", "status_reason": null, "reason": null, "event_actor": "system", "event_datetime": "2026-09-14T10:23:02" }, { "status": "canceled", "status_reason": "withdrawn_by_tenant", "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T14:08:55" } ] } ``` --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000017` | Aditamento não encontrado. | | 403 | `AMD000018` | O aditamento não pertence ao seu tenant. | | 409 | `AMD000012` | O `status` atual não permite o cancelamento. | ## Veja também - [Consultar Aditamento](./consultar-aditamento.md) - [Regras de Negócio](../regras-de-negocio.md#cancelamento) --- # Consultar Aditamento URL: /en/documentation/escrituracao/aditamento/endpoints/consultar-aditamento Dois endpoints de consulta: um devolve o aditamento completo pela chave, outro lista os aditamentos do seu tenant de forma paginada. Como não há webhook dedicado às transições de status do aditamento, a consulta é o caminho para acompanhar o andamento. --- ## Consulta por chave ### **Request** ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres | | --- | --- | --- | --- | | `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 | ### **Response** STATUS 200 A resposta é o objeto completo do aditamento — o mesmo formato devolvido pela [criação](./criar-aditamento.md#response-body-params), agora com os campos preenchidos pelas etapas já percorridas. Response Body — aditamento aguardando o pagamento da taxa ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "status": "pending_charge_settlement", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "amendment_number": 2, "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47", "operation_type": "commercial_paper", "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "created_by": "integration", "created_at": "2026-09-14T10:22:41", "applied_at": null, "previous_financial_key": "b4d1e8a2-3c57-4f9b-8a06-5e2d7c1b9f34", "new_financial_key": null, "envelope_key": null, "signature_method": "certifiqi", "changes": [ { "amendment_change_key": "c9e7a1b3-5d24-4f68-9b0c-3a7e6d5f2c18", "type": "financial_flow", "operation": "modification", "target_key": null, "status": "created", "is_term_signer": false, "applied_at": null, "failure_reason": null, "previous_value": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" } }, "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" } }, "term_wording": null, "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" } ], "financial": { "previous_interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" }, "new_interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" }, "closing_present_value": 152340.55, "closing_difference": 0.00, "closing_tolerance": 0.01 } } ], "documents": [ { "document_key": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "document_type": "amendment_term", "description": null, "template_key": "de1862a0-e196-4329-9ca4-ba5068a78929", "signed_file_key": null, "externally_provided_at": null } ], "charges": [ { "amendment_charge_key": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f", "charge_status": "registered", "charge_payer_type": "issuer", "charge_attempt": 1, "amount": 500.00, "due_date": "2026-09-19", "payer_name": "Emissor Exemplo S.A.", "payer_document_number": "12.345.678/0001-90", "external_charge_key": "4c3d2e1f-9a8b-4756-b342-1e0d9c8b7a65", "digitable_line": "34191.79001 01043.510047 91020.150008 1 96690000050000", "settled_at": null, "charge_status_history": [ { "status": "created", "event_actor": "system", "event_datetime": "2026-09-14T10:23:02" }, { "status": "registration_requested", "event_actor": "system", "event_datetime": "2026-09-14T10:23:03" }, { "status": "registered", "event_actor": "system", "event_datetime": "2026-09-14T10:23:18" } ] } ], "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }, { "status": "pending_term_generation", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }, { "status": "pending_charge_settlement", "status_reason": null, "reason": null, "event_actor": "system", "event_datetime": "2026-09-14T10:23:02" } ] } ``` :::tip Onde está a linha digitável Em `charges[].digitable_line`. Enquanto o aditamento estiver em `pending_charge_settlement`, é o pagamento desse boleto que libera o envio do termo para assinatura. ::: --- ## Consulta paginada ### **Request** ENDPOINT /security_amendment/amendment MÉTODO GET ### **Query Params** | Campo | Tipo | Obrigatório | Padrão | Descrição | | --- | --- | --- | --- | --- | | `security_key` | string (UUID) | Não | — | Filtra os aditamentos de um título específico. | | `page` | integer | Não | `1` | Página desejada. | | `page_size` | integer | Não | `30` | Itens por página. | ### **Response** STATUS 200 :::info Resposta resumida A listagem devolve uma **versão reduzida** de cada aditamento: sem `documents`, `charges`, `status_history`, `envelope_key`, `signature_method` nem as chaves de fluxo financeiro. As alterações vêm sem `previous_value`, `new_value`, `term_wording` e histórico. Para o objeto completo, consulte pela chave. ::: Response Body ```json { "amendment_list": [ { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "status": "pending_charge_settlement", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "amendment_number": 2, "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47", "operation_type": "commercial_paper", "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "created_by": "integration", "created_at": "2026-09-14T10:22:41", "applied_at": null, "changes": [ { "amendment_change_key": "c9e7a1b3-5d24-4f68-9b0c-3a7e6d5f2c18", "type": "financial_flow", "operation": "modification", "target_key": null, "status": "created", "is_term_signer": false, "applied_at": null, "failure_reason": null, "financial": { "closing_present_value": 152340.55, "closing_difference": 0.00, "closing_tolerance": 0.01 } } ] } ], "total_count": 1, "page": 1, "page_size": 30 } ``` | Campo | Tipo | Descrição | | --- | --- | --- | | `amendment_list` | array | Aditamentos da página, em formato reduzido. | | `total_count` | integer | Total de aditamentos que atendem ao filtro. | | `page` | integer | Página devolvida. | | `page_size` | integer | Tamanho da página. | --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000017` | Aditamento não encontrado. | | 403 | `AMD000018` | O aditamento não pertence ao seu tenant. | ## Veja também - [Criar Aditamento](./criar-aditamento.md) - [Consultar Signatários](./consultar-signatarios.md) - [Baixar Documento](./baixar-documento.md) --- # Consultar Signatários URL: /en/documentation/escrituracao/aditamento/endpoints/consultar-signatarios Devolve o envelope de assinatura do termo aditivo: quem precisa assinar, quem já assinou e o **link de assinatura** de cada signatário. Use este endpoint enquanto o aditamento está em `pending_signature_confirmation` para saber quem falta e reenviar o link a quem precisa. --- ## **Request** ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY /signers MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres | | --- | --- | --- | --- | | `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 | --- ## **Response** STATUS 200 Response Body ```json { "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce", "status": "pending_signature", "documents": [ { "document_type": "amendment_term", "signers": [ { "name": "Emissor Exemplo S.A.", "document_number": "145.736.070-56", "email": "financeiro@emissor-exemplo.com.br", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "status": "on_signature" }, { "name": "Maria Oliveira", "document_number": "969.698.790-03", "email": "maria.oliveira@exemplo.com.br", "signature_url": "https://sign.qitech.com.br/s/k9Xp1Qa", "status": "signed" } ] } ] } ``` | Campo | Tipo | Descrição | | --- | --- | --- | | `envelope_key` | string (UUID) | Chave do envelope de assinatura. | | `status` | string | Estado do envelope. | | `documents` | array | Documentos do envelope e seus signatários. | | `documents[].signers[].name` | string | Nome do signatário. | | `documents[].signers[].document_number` | string | CPF do signatário. | | `documents[].signers[].email` | string | E-mail para onde o convite foi enviado. | | `documents[].signers[].signature_url` | string | **Link de assinatura** individual. | | `documents[].signers[].status` | string | Estado da assinatura daquele signatário. | :::info Só depois do envelope existir O envelope é criado quando a taxa do aditamento é paga e o termo segue para assinatura. Antes disso, este endpoint retorna `AMD000039`. ::: --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000017` | Aditamento não encontrado. | | 403 | `AMD000018` | O aditamento não pertence ao seu tenant. | | 422 | `AMD000039` | O aditamento ainda não tem envelope de assinatura. | | 500 | `AMD000019` | Falha ao consultar o provedor de assinatura. | ## Veja também - [Consultar Aditamento](./consultar-aditamento.md) - [Baixar Documento](./baixar-documento.md) - [Regras de Negócio](../regras-de-negocio.md#assinatura) --- # Criar Aditamento URL: /en/documentation/escrituracao/aditamento/endpoints/criar-aditamento Este endpoint cria o aditamento e dispara o rito. A partir daqui a QI Tech orquestra as etapas seguintes — geração do termo, cobrança da taxa, envio para assinatura e aplicação das alterações — e você acompanha pelo endpoint de [consulta](./consultar-aditamento.md). Valide antes de criar: um título só admite **um aditamento em andamento por vez**, e uma criação recusada no fechamento consome essa vaga até ser cancelada. --- ## **Request** ENDPOINT /security_amendment/amendment MÉTODO POST ### **Request Body** ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "signature_method": "certifiqi", "amendment_number": 2, "changes": [ { "type": "financial_flow", "operation": "modification", "term_wording": "As partes repactuam o cronograma de pagamento conforme abaixo.", "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ] } ``` ### **Request Body Params** | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `security_key` | string (UUID) | Sim | Chave do título a ser aditado. | | `financial_base_date` | string (date) | Sim | Data base em `YYYY-MM-DD`. Âncora do saldo devedor, do novo fluxo e do momento da aplicação. Retroativa é recusada com `AMD000005`. | | `changes` | array | Sim | Mínimo 1 item. Formato de cada tipo em [Tipos de Alteração](../tipos-de-alteracao.md). | | `amendment_key` | string (UUID) | Não | **Chave de idempotência** fornecida por você. Reenviar uma chave já usada retorna `AMD000024`. Quando omitido, a QI Tech gera a chave. | | `signature_method` | string | Não | Por onde o termo é assinado. Valores: `qi_sign`, `certifiqi`. Ausente, vale `qi_sign`. | | `amendment_number` | integer (≥ 1) | Não | Ordinal deste aditamento na vida do título, contando os feitos antes da entrada na plataforma. Ausente, a QI Tech usa a própria contagem de aditamentos aplicados + 1. | | `documents` | array | Não | Documentos anexados. É aqui que você envia o termo pronto — veja abaixo. | ### **Enviar o termo pronto** Por padrão a QI Tech gera o termo aditivo. Se você prefere enviar o seu, inclua um documento do tipo `amendment_term` no array `documents`: ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ "..." ], "documents": [ { "document_type": "amendment_term", "document_name": "termo-aditivo-002.pdf", "document_base64": "JVBERi0xLjQKJeLjz9MK...", "description": "Termo aditivo redigido pelo escritório do emissor" } ] } ``` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `document_type` | string | Sim | Valores: `amendment_term`, `deliberation_evidence`. | | `document_name` | string | Sim | Nome do arquivo. Entre 1 e 255 caracteres. | | `document_base64` | string | Sim | Conteúdo do arquivo em base64. | | `description` | string | Não | Descrição livre. | :::caution O termo enviado muda o caminho Enviar um documento do tipo `amendment_term` faz o aditamento nascer em `pending_manual_approval`: a QI Tech confere o documento antes de seguir para a cobrança. Essa conferência é interna e não tem endpoint no seu contrato — acompanhe pelo `status`. Um documento acima do tamanho máximo é recusado com `AMD000016`. ::: --- ## **Response** STATUS 201 Response Body ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "status": "pending_term_generation", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "amendment_number": 2, "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47", "operation_type": "commercial_paper", "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "created_by": "integration", "created_at": "2026-09-14T10:22:41", "applied_at": null, "previous_financial_key": "b4d1e8a2-3c57-4f9b-8a06-5e2d7c1b9f34", "new_financial_key": null, "envelope_key": null, "signature_method": "certifiqi", "changes": [ { "amendment_change_key": "c9e7a1b3-5d24-4f68-9b0c-3a7e6d5f2c18", "type": "financial_flow", "operation": "modification", "target_key": null, "status": "created", "is_term_signer": false, "applied_at": null, "failure_reason": null, "previous_value": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" } }, "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" } }, "term_wording": "As partes repactuam o cronograma de pagamento conforme abaixo.", "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" } ] } ], "documents": [], "charges": [], "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }, { "status": "pending_term_generation", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" } ] } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | --- | --- | --- | | `amendment_key` | string (UUID) | Chave única do aditamento. Use-a em todas as consultas. | | `status` | string | Estado atual. Veja o ciclo de vida em [Conceito](../conceito.md#o-ciclo-de-vida). | | `security_key` | string (UUID) | Título aditado. | | `amendment_number` | integer | Ordinal deste aditamento na vida do título. | | `operation_key` | string (UUID) | Operação de origem do título. | | `operation_type` | string | Tipo do instrumento. Exemplo: `commercial_paper`. | | `financial_base_date` | string (date) | Data base do aditamento. | | `outstanding_balance` | number | Saldo devedor apurado na data base. | | `created_by` | string | Quem criou o aditamento. | | `created_at` | string (datetime) | Momento da criação. | | `applied_at` | string (datetime) | Momento da aplicação. `null` enquanto não aplicado. | | `previous_financial_key` | string (UUID) | Fluxo financeiro vigente antes do aditamento. | | `new_financial_key` | string (UUID) | Fluxo resultante. Preenchido na aplicação. | | `envelope_key` | string (UUID) | Envelope de assinatura. Preenchido quando o termo é enviado para assinatura. | | `signature_method` | string | `qi_sign` ou `certifiqi`. | | `changes` | array | As alterações do aditamento, cada uma com status próprio. | | `documents` | array | Documentos do aditamento, incluindo o termo. | | `charges` | array | Cobranças do aditamento. Preenchido quando o boleto é emitido. | | `status_history` | array | Cada transição de status, com ator, motivo e data. | **`changes[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `amendment_change_key` | string (UUID) | Chave única da alteração. | | `type` / `operation` / `target_key` | string | Ecoados da requisição. | | `status` | string | Estado da alteração. | | `is_term_signer` | boolean | Se a parte relacionada foi eleita signatária do termo. | | `applied_at` | string (datetime) | Momento em que esta alteração foi aplicada. | | `failure_reason` | string | Motivo da falha, quando a aplicação não completa. | | `previous_value` | object | Estado anterior ao aditamento. | | `new_value` | object | Conteúdo enviado na requisição. | | `term_wording` | string | Redação específica desta alteração no termo. | | `status_history` | array | Transições desta alteração. | | `financial` | object | Presente apenas em alterações de `financial_flow`. Guarda o antes e o depois do fluxo e o resultado do fechamento. | **`changes[].financial`** | Campo | Tipo | Descrição | | --- | --- | --- | | `previous_interest_rate` | object | Taxa vigente antes do aditamento. | | `new_interest_rate` | object | Taxa resultante. | | `previous_installments` | array | Cronograma anterior. | | `new_installments` | array | Cronograma resultante. | | `closing_present_value` | number | Valor presente usado no fechamento. | | `closing_difference` | number | Diferença apurada. | | `closing_tolerance` | number | Tolerância aplicada. | **`charges[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `amendment_charge_key` | string (UUID) | Chave única da cobrança. | | `charge_status` | string | Estado do boleto. | | `charge_payer_type` | string | Quem é cobrado. | | `charge_attempt` | integer | Número da tentativa de cobrança. | | `amount` | number | Valor da taxa. | | `due_date` | string (date) | Vencimento do boleto. | | `payer_name` | string | Nome do pagador. | | `payer_document_number` | string | Documento do pagador. | | `digitable_line` | string | **Linha digitável do boleto.** | | `external_charge_key` | string (UUID) | Chave do boleto no emissor. | | `settled_at` | string (datetime) | Momento da compensação. | | `charge_status_history` | array | Transições da cobrança. | **`documents[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `document_key` | string (UUID) | Chave do documento. Use-a para [baixar](./baixar-documento.md). | | `document_type` | string | `amendment_term` ou `deliberation_evidence`. | | `description` | string | Descrição livre. | | `template_key` | string (UUID) | Template usado na geração, quando gerado pela QI Tech. | | `signed_file_key` | string | Referência do arquivo assinado. Preenchido após a assinatura. | | `externally_provided_at` | string (datetime) | Preenchido quando o documento foi enviado por você. | **`status_history[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `status` | string | Estado alcançado. | | `status_reason` | string | Motivo estruturado. Valores: `manual_approval_rejected`, `expired`, `withdrawn_by_tenant`, `withdrawn_by_issuer`, `signature_rejected`, `reverted`. | | `reason` | string | Descrição livre do motivo. | | `event_actor` | string | Quem provocou a transição. | | `event_datetime` | string (datetime) | Momento da transição. | --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000001` | Título não encontrado para este tenant. | | 422 | `AMD000002` | Título não está ativo. | | 422 | `AMD000003` | Operação de origem não está finalizada. | | 422 | `AMD000004` | Título já liquidado. | | 422 | `AMD000005` | Data base retroativa. | | 422 | `AMD000006` | Combinação de tipo e operação inexistente. | | 422 | `AMD000007` | `target_key` obrigatório e ausente. | | 422 | `AMD000008` | Garantia não suportada para este tipo de operação. | | 422 | `AMD000014` | Parte relacionada de papel imutável (`issuer`, `investor`). | | 422 | `AMD000015` | Garantia exige documentos que não foram enviados. | | 413 | `AMD000016` | Documento acima do tamanho máximo. | | 409 | `AMD000024` | `amendment_key` já utilizado. | | 422 | `AMD000040` | `is_term_signer` em um tipo que não aceita. | | 422 | `AMD000041` | Signatário do termo sem `signer_group_list`. | | 422 | `AMD000042` | Signatário sem e-mail, exigido pelo provedor de assinatura. | | 422 | `AMD000043` | Parte removida não tem grupo de assinatura. | | 409 | `AMD000044` | Número de emissão já utilizado. | | 409 | `AMD000031` | O título já tem um aditamento em andamento. | O catálogo completo está em [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). ## Veja também - [Validar Aditamento](./validar-aditamento.md) - [Consultar Aditamento](./consultar-aditamento.md) - [Cancelar Aditamento](./cancelar-aditamento.md) - [Tipos de Alteração](../tipos-de-alteracao.md) --- # Simular Aditamento URL: /en/documentation/escrituracao/aditamento/endpoints/simular-aditamento Este endpoint devolve o efeito de uma repactuação de fluxo **sem criar nada**: o saldo devedor na data base, o cronograma vigente, o cronograma proposto, o resultado do fechamento e o valor da taxa do aditamento. Use a simulação para apresentar o cenário ao emissor antes de qualquer compromisso. :::info Escopo da simulação A simulação aceita **exatamente uma** alteração, e ela precisa ser do tipo `financial_flow`. Qualquer outro tipo é recusado com `AMD000013`. Para conferir um conjunto completo de alterações, use a [validação](./validar-aditamento.md). ::: --- ## **Request** ENDPOINT /security_amendment/amendment/simulation MÉTODO POST ### **Request Body** ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ { "type": "financial_flow", "operation": "modification", "new_value": { "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ] } ``` ### **Request Body Params** | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `security_key` | string (UUID) | Sim | Chave do título a ser aditado. | | `financial_base_date` | string (date) | Sim | Data base em `YYYY-MM-DD`. Âncora do saldo devedor e do novo fluxo. | | `changes` | array | Sim | Exatamente 1 item, do tipo `financial_flow`. Formato em [Tipos de Alteração](../tipos-de-alteracao.md). | --- ## **Response** STATUS 200 Response Body ```json { "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "closing": { "present_value": 152340.55, "difference": 0.00, "tolerance": 0.01, "passed": true }, "preserved_installments": [ { "installment_number": 1, "due_date": "2026-07-20", "principal_amortization_amount": 48000.00, "interest_amount": 2100.00, "installment_status": "paid", "paid_amount": 50100.00, "paid_at": "2026-07-20T13:42:11" } ], "previous_financial": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-09-20", "principal_amortization_amount": 50000.00, "interest_amount": 2680.00, "installment_status": "pending" } ] }, "new_financial": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-10-20", "principal_amortization_amount": 49210.33, "interest_amount": 3470.22, "installment_status": "pending" }, { "installment_number": 4, "due_date": "2026-11-20", "principal_amortization_amount": 49563.87, "interest_amount": 3116.68, "installment_status": "pending" }, { "installment_number": 5, "due_date": "2026-12-20", "principal_amortization_amount": 49920.40, "interest_amount": 2760.15, "installment_status": "pending" } ] }, "charge_amount": 500.00 } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | --- | --- | --- | | `financial_base_date` | string (date) | Data base usada no cálculo, ecoada da requisição. | | `outstanding_balance` | number | Saldo devedor apurado na data base. | | `closing` | object | Resultado do fechamento contra o valor presente. | | `preserved_installments` | array | Parcelas que **não** entram na repactuação e são mantidas como estão. | | `previous_financial` | object | Taxa e cronograma vigentes antes do aditamento. | | `new_financial` | object | Taxa e cronograma resultantes da proposta. | | `charge_amount` | number | Valor da taxa do aditamento, conforme seu contrato. | **`closing`** | Campo | Tipo | Descrição | | --- | --- | --- | | `present_value` | number | Valor presente do título na data base. | | `difference` | number | Diferença entre o fluxo proposto e o valor presente. | | `tolerance` | number | Diferença máxima aceita. | | `passed` | boolean | `true` quando a diferença está dentro da tolerância. Um fluxo com `false` faria o aditamento nascer em `validation_failed`. | **`installments[]`** (em `preserved_installments`, `previous_financial` e `new_financial`) | Campo | Tipo | Descrição | | --- | --- | --- | | `installment_number` | integer | Número da parcela no cronograma. | | `due_date` | string (date) | Vencimento. | | `principal_amortization_amount` | number | Parcela de amortização do principal. | | `interest_amount` | number | Parcela de juros. | | `installment_status` | string | Estado da parcela. | | `paid_amount` | number | Valor pago. Presente apenas em parcelas com pagamento. | | `paid_at` | string (datetime) | Momento do pagamento. Presente apenas em parcelas pagas. | --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000001` | Título não encontrado para este tenant. | | 422 | `AMD000002` | Título não está ativo. | | 422 | `AMD000003` | Operação de origem não está finalizada. | | 422 | `AMD000004` | Título já liquidado. | | 422 | `AMD000005` | Data base retroativa. | | 422 | `AMD000013` | A simulação aceita apenas uma alteração de `financial_flow`. | | 422 | `AMD000020` | Parcela com pagamento já aplicado não pode ser renegociada. | O catálogo completo está em [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). ## Veja também - [Validar Aditamento](./validar-aditamento.md) - [Criar Aditamento](./criar-aditamento.md) - [Regras de Negócio](../regras-de-negocio.md) --- # Validar Aditamento URL: /en/documentation/escrituracao/aditamento/endpoints/validar-aditamento Este endpoint recebe **o mesmo corpo da criação** e devolve o que aconteceria, sem criar nada. Use-o como último passo antes de disparar o rito: ele confere a elegibilidade do título, resolve cada alteração contra o estado atual e informa em qual `status` o aditamento nasceria. Diferente da [simulação](./simular-aditamento.md), a validação aceita o **conjunto completo** de alterações, de qualquer tipo. --- ## **Request** ENDPOINT /security_amendment/amendment/validation MÉTODO POST ### **Request Body** Idêntico ao da [criação](./criar-aditamento.md). ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "signature_method": "certifiqi", "changes": [ { "type": "financial_flow", "operation": "modification", "new_value": { "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" } ] } }, { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001" } ] } ``` --- ## **Response** STATUS 200 Response Body ```json { "valid": true, "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "closing": { "present_value": 152340.55, "difference": 0.00, "tolerance": 0.01, "passed": true }, "resolved_changes": [ { "type": "financial_flow", "operation": "modification", "target_key": null, "previous_value": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" } }, "preserved_installments": [ { "installment_number": 1, "due_date": "2026-07-20", "principal_amortization_amount": 48000.00, "interest_amount": 2100.00, "installment_status": "paid" } ] }, { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001", "previous_value": { "collateral_type": "fiduciary_alienation_vehicle", "description": "Veículo dado em alienação fiduciária" } } ], "term_generation": "qi_generated", "next_status": "pending_term_generation" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | --- | --- | --- | | `valid` | boolean | `true` quando o aditamento pode ser criado como enviado. | | `financial_base_date` | string (date) | Data base ecoada da requisição. | | `outstanding_balance` | number | Saldo devedor apurado na data base. | | `closing` | object | Resultado do fechamento. Presente quando há alteração de `financial_flow`. | | `resolved_changes` | array | Cada alteração resolvida contra o estado atual do título. | | `term_generation` | string | Origem do termo. `qi_generated` quando a QI Tech gera; `tenant_supplied` quando você enviou o termo pronto. | | `next_status` | string | O `status` em que o aditamento nasceria se fosse criado agora. | **`resolved_changes[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `type` | string | Tipo da alteração. | | `operation` | string | Operação da alteração. | | `target_key` | string (UUID) | Registro endereçado, quando houver. | | `previous_value` | object | Estado atual do que será alterado. Ausente quando não há valor anterior (por exemplo, em `addition`). | | `preserved_installments` | array | Apenas em `financial_flow`: parcelas mantidas fora da repactuação. | :::tip Antecipe a aprovação manual O campo `next_status` é o principal motivo para validar antes de criar. Quando ele vem `pending_manual_approval`, o aditamento vai aguardar conferência da QI Tech sobre o termo que você enviou — e o prazo total muda. Veja [Regras de Negócio](../regras-de-negocio.md#o-termo-aditivo). ::: --- ## **Erros** A validação recusa pelos mesmos motivos da criação. Os mais comuns: | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000001` | Título não encontrado para este tenant. | | 422 | `AMD000002` | Título não está ativo. | | 422 | `AMD000003` | Operação de origem não está finalizada. | | 422 | `AMD000004` | Título já liquidado. | | 422 | `AMD000005` | Data base retroativa. | | 422 | `AMD000006` | Combinação de tipo e operação inexistente. | | 422 | `AMD000007` | `target_key` obrigatório e ausente. | | 422 | `AMD000008` | Garantia não suportada para este tipo de operação. | | 422 | `AMD000014` | Parte relacionada de papel imutável. | | 409 | `AMD000031` | O título já tem um aditamento em andamento. | O catálogo completo está em [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). ## Veja também - [Criar Aditamento](./criar-aditamento.md) - [Simular Aditamento](./simular-aditamento.md) - [Tipos de Alteração](../tipos-de-alteracao.md) --- # Exemplos URL: /en/documentation/escrituracao/aditamento/exemplos Casos completos, do primeiro ensaio ao aditamento aplicado. --- ## 1. Repactuar o fluxo de pagamento O cenário mais comum: o emissor pede mais prazo e as partes acordam uma taxa nova. ### Passo 1 — Simular Antes de qualquer compromisso, veja o efeito no fluxo e quanto custa o aditamento. ``` POST /security_amendment/amendment/simulation ``` ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ { "type": "financial_flow", "operation": "modification", "new_value": { "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ] } ``` Confira `closing.passed` na resposta. Se vier `false`, o fluxo proposto não fecha e o aditamento nasceria recusado — ajuste antes de seguir. ### Passo 2 — Validar Mesmo corpo da criação, sem criar. Confirme o `next_status`. ``` POST /security_amendment/amendment/validation ``` ### Passo 3 — Criar ``` POST /security_amendment/amendment ``` ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "signature_method": "certifiqi", "changes": [ { "type": "financial_flow", "operation": "modification", "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ] } ``` ### Passo 4 — Pagar a taxa Consulte o aditamento e pegue a linha digitável em `charges[].digitable_line`. O aditamento fica em `pending_charge_settlement` até a compensação. ``` GET /security_amendment/amendment/7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33 ``` ### Passo 5 — Coletar assinaturas Com a taxa paga, o termo vai para assinatura. Pegue os links: ``` GET /security_amendment/amendment/7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33/signers ``` ### Passo 6 — Acompanhar a aplicação Assinado o termo, o aditamento vai para `pending_application` e é aplicado na `financial_base_date`. Quando chega a `applied`, o campo `applied_at` é preenchido e `new_financial_key` aponta para o fluxo novo. --- ## 2. Substituir uma garantia Remover a garantia antiga e incluir a nova **no mesmo aditamento** — assim as duas alterações valem juntas, e o título nunca fica descoberto. ``` POST /security_amendment/amendment ``` ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001", "term_wording": "Fica liberada a garantia constituída sobre o veículo de placa ABC1D23." }, { "type": "collateral", "operation": "addition", "new_value": { "collateral_type": "fiduciary_alienation_vehicle", "description": "Veículo dado em substituição", "value": 92000.00 } } ] } ``` :::tip Tudo ou nada As alterações de um mesmo aditamento são aplicadas em conjunto. Em uma substituição, isso garante que a liberação da garantia antiga e a constituição da nova acontecem no mesmo ato. ::: --- ## 3. Incluir um avalista que assina o termo A parte incluída pelo aditamento também precisa assinar o termo aditivo — então ela traz o próprio grupo de assinatura. ``` POST /security_amendment/amendment ``` ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "signature_method": "certifiqi", "changes": [ { "type": "related_party", "operation": "addition", "is_term_signer": true, "new_value": { "person_type": "natural", "name": "Maria Oliveira", "document_number": "96969879003", "role_type": "surety", "street": "Avenida Brigadeiro Faria Lima", "number": "1234", "neighborhood": "Itaim Bibi", "city": "São Paulo", "state": "SP", "postal_code": "01451-001", "signer_group_list": [ { "minimum_required_signers": 1, "signers": [ { "name": "Maria Oliveira", "document_number": "969.698.790-03", "email": "maria.oliveira@exemplo.com.br", "is_group_mandatory": true } ] } ] } } ] } ``` :::caution E-mail com CertifiQI Com `signature_method: certifiqi`, o `email` de cada signatário é obrigatório. Sem ele, a criação é recusada com `AMD000042`. ::: --- ## 4. Enviar o termo já redigido Quando o escritório do emissor redige o termo, envie-o na criação. O aditamento entra em conferência da QI Tech antes de seguir. ``` POST /security_amendment/amendment ``` ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ { "type": "issue_number", "operation": "modification", "new_value": { "issue_number": 2 } } ], "documents": [ { "document_type": "amendment_term", "document_name": "termo-aditivo-002.pdf", "document_base64": "JVBERi0xLjQKJeLjz9MK..." } ] } ``` O aditamento nasce em `pending_manual_approval`. Acompanhe pelo `status`: aprovado, ele segue para a cobrança; recusado, vai para `canceled` com `status_reason: manual_approval_rejected`. --- ## 5. Desistir de um aditamento ``` PATCH /security_amendment/amendment/7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33/cancel ``` Sem corpo. Aceito até `pending_signature_confirmation`. O boleto em aberto é baixado e o envelope de assinatura é cancelado. ## Veja também - [Conceito](./conceito.md) - [Regras de Negócio](./regras-de-negocio.md) - [Tipos de Alteração](./tipos-de-alteracao.md) --- # Regras de Negócio — Aditamento URL: /en/documentation/escrituracao/aditamento/regras-de-negocio Esta página consolida as invariantes que governam a criação, a assinatura e a aplicação de um aditamento. Consulte-a sempre que as páginas de endpoints citarem um código de erro, um campo ou uma condição que precise de contexto adicional. ## Elegibilidade do título Antes de criar qualquer coisa, a QI Tech confere se o título aceita aditamento. Todas as condições abaixo precisam valer: - O título precisa existir e pertencer ao seu tenant — caso contrário, `AMD000001`. - O título precisa estar **ativo**. Título em outro estado é recusado com `AMD000002`, e a mensagem carrega o estado encontrado. - A operação de origem precisa estar **finalizada** (emitida). Operação ainda em cadastro ou análise é recusada com `AMD000003`. - O título **não pode estar liquidado** — não há o que aditar, e a recusa é `AMD000004`. - O título **não pode ter outro aditamento em andamento**. Um por vez: enquanto o anterior não chega a `applied`, `canceled` ou `validation_failed`, a criação é recusada com `AMD000031`, e a mensagem diz qual aditamento está ocupando o título. ## Data base (`financial_base_date`) A `financial_base_date` é **fornecida pelo integrador** e é a única referência temporal do aditamento. Ela define: - a data em que o saldo devedor (`outstanding_balance`) é apurado; - a data a partir da qual o novo fluxo passa a valer; - o momento em que as alterações são efetivamente aplicadas no título. **Data base retroativa é recusada** com `AMD000005`. A única exceção são operações com origem de tombamento, em que o histórico anterior à entrada na plataforma justifica a retroatividade. Quando a data base é **futura**, o aditamento permanece em `pending_application` após a coleta das assinaturas e é aplicado quando a data chega. Quando é **hoje**, a aplicação ocorre assim que a última assinatura é confirmada. ## Fechamento do fluxo (`closing`) Em alterações de `financial_flow`, a QI Tech confere se o cronograma proposto fecha contra o valor presente do título na data base. O resultado vem no objeto `closing`: | Campo | Significado | | --- | --- | | `present_value` | Valor presente do título na data base. | | `difference` | Diferença entre o fluxo proposto e o valor presente. | | `tolerance` | Diferença máxima aceita. | | `passed` | `true` quando a diferença está dentro da tolerância. | Um fluxo com `passed: false` faz o aditamento nascer diretamente em `validation_failed`: nada é cobrado e nada é enviado para assinatura. Use a [validação](./endpoints/validar-aditamento.md) antes de criar para não gastar uma tentativa. ### A variável livre O cálculo do novo fluxo resolve **uma variável livre**. O que você envia determina o que a QI Tech calcula: - **Enviou apenas datas** (`installments[].due_date`) — os valores das parcelas são recalculados, mantida a taxa vigente. - **Enviou nova taxa** (`interest_rate`) — os valores são recalculados com a taxa nova, mantidas as datas informadas. - **Enviou valores** (`installments[].amount`) — a taxa é derivada. Enviar **taxa e valores juntos** é recusado, porque sobredetermina o sistema. Dentro de uma mesma parcela, `amount` e `principal_amortization_percentage` também são excludentes. ### Parcelas preservadas Envie **apenas a cauda renegociada**. Parcelas já pagas não entram no payload — a QI Tech as preserva automaticamente e as devolve em `preserved_installments` na simulação. Uma parcela **parcialmente paga não pode ser renegociada**: a recusa é `AMD000020`, com o número e o estado da parcela na mensagem. ## O termo aditivo O termo pode nascer de dois jeitos, e a escolha muda o caminho do aditamento. **Gerado pela QI Tech** — o comportamento padrão. Você não envia nenhum documento do tipo `amendment_term` na criação; a QI Tech monta o termo a partir dos dados do aditamento e o aditamento segue direto para a cobrança. **Enviado pronto pelo integrador** — você inclui um documento do tipo `amendment_term` no array `documents` da criação. Nesse caso o aditamento entra em `pending_manual_approval`. :::info Conferência da QI Tech Quando o termo é enviado pronto, a QI Tech confere o documento antes de seguir. Essa etapa é executada internamente pela equipe da QI Tech e **não tem endpoint no seu contrato de integração** — acompanhe pelo `status`. Aprovado, o aditamento segue para a cobrança. Recusado, ele vai para `canceled` com `status_reason: manual_approval_rejected`. ::: Cada alteração aceita ainda o campo `term_wording` (até 10.000 caracteres): o texto que o termo deve carregar para aquela alteração específica, no lugar da redação padrão da plataforma. ## Cobrança O aditamento tem uma taxa de serviço, cobrada por boleto emitido no momento em que o termo fica pronto. O valor segue a configuração comercial do seu contrato e é devolvido na simulação, em `charge_amount`. **O pagamento do boleto é o que libera o envio para assinatura.** Enquanto a compensação não ocorre, o aditamento permanece em `pending_charge_settlement`. A linha digitável fica em `charges[].digitable_line` na consulta. Boleto vencido sem pagamento não trava o aditamento em definitivo: a QI Tech substitui o boleto vencido por um novo quando o fluxo é retomado. Um boleto dentro do prazo continua válido, com a mesma linha digitável. ## Assinatura Com a taxa paga, a QI Tech monta o envelope e o envia aos signatários. - Os signatários vêm dos **grupos de assinatura cadastrados na operação**. Uma operação sem grupo de assinatura ativo para o emissor é recusada com `AMD000022`. - Uma **parte relacionada incluída pelo próprio aditamento** pode ser eleita signatária do termo com `is_term_signer: true`. Nesse caso ela precisa trazer `signer_group_list` no `new_value` — sem isso, `AMD000041`. - Em remoções, os grupos vêm do cadastro da operação. Uma parte sem grupo de assinatura não pode assinar: `AMD000043`. - `is_term_signer` só existe em alterações do tipo `related_party` — em qualquer outro tipo, `AMD000040`. - O método de assinatura vai em `signature_method` na criação. Quando omitido, vale `qi_sign`. Com `certifiqi`, **o e-mail do signatário é obrigatório** — sem ele, `AMD000042`. Consulte o andamento pelo endpoint de [signatários](./endpoints/consultar-signatarios.md), que devolve quem já assinou, quem falta e o link de assinatura de cada um. ## Aplicação Coletadas as assinaturas — e chegada a data base — a QI Tech aplica as alterações no título. A aplicação é **conjunta**: as alterações de um mesmo aditamento valem todas ou nenhuma. Cada alteração carrega o próprio `status` e o `applied_at`. Uma alteração que falha registra o motivo em `failure_reason` e leva o aditamento para `application_failed`. :::caution Alterações de `term_clause` Uma alteração do tipo `term_clause` não altera dado estruturado no título — o efeito dela vive na redação do termo assinado. Ela é registrada e aplicada como as demais, mas não produz mudança consultável fora do documento. ::: ## Cancelamento Você pode desistir do aditamento enquanto ele não entrou em aplicação. O cancelamento é aceito nos status `created`, `pending_manual_approval`, `pending_term_generation`, `pending_charge_settlement`, `pending_signature` e `pending_signature_confirmation`. A partir de `pending_application` o cancelamento **não é mais aceito** — a recusa é `AMD000012`. Nos estados terminais (`applied`, `canceled`, `validation_failed`) também não. O cancelamento tem dois efeitos fora do aditamento: **baixa o boleto em aberto**, se houver, e **cancela o envelope de assinatura**, se já tiver sido enviado. Um boleto já pago não é baixado. O motivo registrado é `withdrawn_by_tenant`, visível em `status_history[].status_reason`. ## Veja também - [Conceito](./conceito.md) - [Tipos de Alteração](./tipos-de-alteracao.md) - [Criar Aditamento](./endpoints/criar-aditamento.md) - [Exemplos](./exemplos.md) - [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Tipos de Alteração URL: /en/documentation/escrituracao/aditamento/tipos-de-alteracao Cada item do array `changes` descreve uma alteração. Esta página detalha o formato de `new_value` para cada `type`. ## O envelope da alteração Todos os tipos compartilham a mesma estrutura externa: ```json { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001", "new_value": null, "term_wording": "Texto livre para o termo, no lugar da redação padrão.", "is_term_signer": false } ``` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `type` | string | Sim | Dimensão alterada. Valores: `financial_flow`, `collateral`, `related_party`, `issue_number`, `term_clause`. | | `operation` | string | Sim | Valores: `addition`, `modification`, `removal`. Nem toda combinação existe — veja a matriz abaixo. | | `target_key` | string (UUID) | Condicional | Registro existente endereçado pela alteração. Obrigatório em `modification` e `removal` de `collateral` e `related_party`. | | `new_value` | object | Condicional | Conteúdo da alteração. O formato depende do `type`. Ausente em `removal`. | | `term_wording` | string | Não | Até 10.000 caracteres. Redação específica que o termo deve carregar para esta alteração. | | `is_term_signer` | boolean | Não | Apenas em `related_party`: a parte endereçada assina o termo aditivo. | ## Matriz de combinações | `type` | `addition` | `modification` | `removal` | | --- | --- | --- | --- | | `financial_flow` | — | Sim, sem `target_key` | — | | `collateral` | Sim, sem `target_key` | Sim, `target_key` obrigatório | Sim, `target_key` obrigatório | | `related_party` | Sim, sem `target_key` | Sim, `target_key` obrigatório | Sim, `target_key` obrigatório | | `issue_number` | — | Sim, sem `target_key` | — | | `term_clause` | Sim | Sim | Sim — nenhum exige `target_key` | Combinação inexistente é recusada com `AMD000006`, e a mensagem carrega o par tentado. `target_key` faltando onde é exigido retorna `AMD000007`. --- ## `financial_flow` — repactuação do fluxo Reperfilamento do cronograma de pagamento. Aceita apenas `modification`. ```json { "type": "financial_flow", "operation": "modification", "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ``` ### `new_value` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `interest_rate` | object | Condicional | Nova taxa. Ausente, mantém a taxa vigente do título. | | `installments` | array | Condicional | Somente a cauda renegociada. Mínimo 1 item. | Pelo menos um dos dois precisa estar presente. **`interest_rate`** | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `interest_base` | string | Sim | Base de contagem. Valores: `calendar_days`, `calendar_days_365`, `workdays`. | | `annual_rate` | number | Condicional | Taxa anual. | | `monthly_rate` | number | Condicional | Taxa mensal. | | `daily_rate` | number | Condicional | Taxa diária. | Informe **exatamente uma** entre `annual_rate`, `monthly_rate` e `daily_rate`. **`installments[]`** | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `installment_number` | integer (≥ 1) | Sim | Número da parcela no cronograma do título. | | `due_date` | string (date) | Sim | Novo vencimento, em `YYYY-MM-DD`. | | `amount` | number (> 0) | Não | Novo valor da parcela. | | `principal_amortization_percentage` | number | Não | Percentual de amortização do principal. | :::caution Uma variável livre por vez `amount` e `principal_amortization_percentage` são **excludentes** dentro da mesma parcela. E enviar `interest_rate` junto com `amount` nas parcelas sobredetermina o cálculo e é recusado — escolha o que a QI Tech deve calcular. ::: Parcelas já pagas não entram no array; a QI Tech as preserva. Uma parcela parcialmente paga não pode ser renegociada (`AMD000020`). --- ## `collateral` — garantias Inclusão ou remoção de garantia. Disponível apenas para operações do tipo `commercial_paper` e `debenture` — em qualquer outro tipo, `AMD000008`. **Inclusão** — o `new_value` carrega a garantia completa, no mesmo formato aceito no cadastro da operação. O campo `collateral_type` discrimina o formato: ```json { "type": "collateral", "operation": "addition", "new_value": { "collateral_type": "fiduciary_alienation_vehicle", "description": "Veículo dado em alienação fiduciária", "value": 85000.00 } } ``` **Remoção** — endereça a garantia existente e não leva `new_value`: ```json { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001" } ``` ### Tipos de garantia aceitos `bank_surety` · `contract` · `fiduciary_alienation_aircraft` · `fiduciary_alienation_artwork` · `fiduciary_alienation_equipment` · `fiduciary_alienation_property` · `fiduciary_alienation_securities` · `fiduciary_alienation_vehicle` · `fiduciary_assignment_shares` · `guarantor` · `insurance` · `monitoring_guarantee` · `mortgage_property` · `mortgage_ship` · `surety` · `vehicle_stock` O formato de cada tipo é o mesmo do [cadastro de garantia](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) na emissão. Garantias que exigem documentos precisam trazê-los — a falta é recusada com `AMD000015`. --- ## `related_party` — partes relacionadas Inclusão, alteração ou remoção de avalista, devedor solidário, fiel depositário e demais papéis. ```json { "type": "related_party", "operation": "addition", "is_term_signer": true, "new_value": { "person_type": "natural", "name": "Maria Oliveira", "document_number": "96969879003", "role_type": "surety", "street": "Avenida Brigadeiro Faria Lima", "number": "1234", "neighborhood": "Itaim Bibi", "city": "São Paulo", "state": "SP", "postal_code": "01451-001", "signer_group_list": [ { "minimum_required_signers": 1, "signers": [ { "name": "Maria Oliveira", "document_number": "969.698.790-03", "email": "maria.oliveira@exemplo.com.br", "is_group_mandatory": true } ] } ] } } ``` ### Papéis (`role_type`) `cosigner` · `fiduciary_debtor` · `solidary_debtor` · `surety` :::caution Papéis imutáveis `issuer` e `investor` **não podem ser aditados** — a recusa é `AMD000014`. Emissor e investidor são determinados na emissão do título. ::: ### Eleger a parte como signatária Com `is_term_signer: true`, a parte assina o termo aditivo: - Em `addition` e `modification`, o `new_value` precisa trazer `signer_group_list` — sem ele, `AMD000041`. - Em `removal`, os grupos vêm do cadastro da operação. Parte sem grupo de assinatura não pode assinar: `AMD000043`. - Com `signature_method: certifiqi`, o `email` de cada signatário é **obrigatório** — sem ele, `AMD000042`. - `is_term_signer` em qualquer outro `type` é recusado com `AMD000040`. --- ## `issue_number` — número da emissão Correção do número da emissão. Aceita apenas `modification`. ```json { "type": "issue_number", "operation": "modification", "new_value": { "issue_number": 2 } } ``` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `issue_number` | integer (≥ 1) | Sim | Novo número da emissão. | Um número já usado por outra operação ativa do mesmo emissor é recusado com `AMD000044`. --- ## `term_clause` — cláusulas do termo Regeração do documento com campos livres. Não existe cláusula endereçável: o que muda é o template e o mapa de campos que ele consome. ```json { "type": "term_clause", "operation": "modification", "new_value": { "document_type": "commercial_paper", "extra_fields": { "clausula_decima": "As partes acordam que...", "foro_eleito": "Comarca de São Paulo - SP" } } } ``` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `document_type` | string | Sim | Valores: `commercial_paper`, `adhesion_term`. | | `extra_fields` | object | Sim | Mapa plano de texto para texto, consumido pelo template. Mínimo 1 chave. | | `template_key` | string (UUID) | Não | Template específico a ser usado. | :::info Efeito documental Uma alteração de `term_clause` não muda dado estruturado no título — o efeito dela vive na redação do termo assinado. ::: ## Veja também - [Regras de Negócio](./regras-de-negocio.md) - [Criar Aditamento](./endpoints/criar-aditamento.md) - [Exemplos](./exemplos.md) --- # Extraordinary Amortization URL: /en/documentation/escrituracao/amortizacao-extraordinaria/conceito ## Overview Extraordinary amortization is the process of reducing the outstanding balance of an issuance outside the ordinary schedule — when the issuer prepays, settles instalments ahead of their due date, or refinances part of the debt. QI Tech receives this request via API, validates the amounts and registers the event for later settlement, without interfering with the ordinary amortizations generated on each `due_date`. Typical scenarios involve early payoff by the issuer, early payment of one or more instalments, and partial refinancing operations. In all of these cases the integrator starts the flow on demand, informing which instalment (or set of instalments) is being amortized and for what amount. You use this API whenever you need to change the outstanding balance outside the ordinary payment schedule. The result is always a traceable event, with its own `status` and financial record. Creation is fire-and-forget: QI Tech orchestrates settlement, finalization and cancellation internally, without the integrator having to call additional endpoints. ## Ordinary vs extraordinary amortization Ordinary amortization is generated automatically by QI Tech: on each `due_date`, the instalment settlement process is created internally with no action from the integrator. Extraordinary amortization, on the other hand, is always started on demand, through an explicit API call. The two coexist — registering an extraordinary amortization does not cancel or replace the ordinary ones still to fall due; it only adds a new settlement event on the asset. ## Amortization types The seven supported types live in the `amortization_type` field. In all of them `installment_list` defines the target instalments; the type defines how `amount` is distributed across them: - `equal_amount` (proportional amounts) — proportionally distributes the informed amount across the selected instalments, overdue ones first and then the future ones. - `first_installments` (first instalments) — applies the amount sequentially to the first N selected instalments (by due date) until it is exhausted. - `present_amount` (present value) — the integrator chooses the instalments and may inform `total_discount`; the distribution order is interest → penalty → principal. - `matured_installments` (matured instalments) — applies the amount exclusively to instalments that have already fallen due. - `early_amortization` (early amortization) — brings forward the payment of a future instalment. - `nominal_amount` (nominal value) — settles future instalments at their nominal value (principal + interest at maturity), without bringing them to Present Value; does not accept overdue instalments. - `full_amortization` (full settlement) — splits `amount` across **every** selected instalment proportionally to Present Value, with no cascade, and settles each one in full at liquidation even when the received share is lower than its Present Value; the difference is recorded as each instalment's `discount_amount`. Only `early_amortization` and `nominal_amount` allow partial payment — the other five require full coverage of the declared amount within the tolerance. ## Key concepts - **`event_conciliation`** — corresponds to the conciliation event of a specific instalment. Responsible for the act of conciliating payments and/or extraordinary amortizations of instalments of a security. - **`reference_date`** — reference date provided by the caller on every creation (it must match the payoff date). QI Tech never uses `date.today()`: all date-related logic (maturity classification, Present Value projection, discrimination between overdue and upcoming instalments) starts from this field. - **Present Value** — calculated internally and consumed during event creation. The integrator does not need to calculate Present Value on their side. - **Tolerance (`tolerance_amount`)** — maximum accepted difference between the settlement amount and the expected instalment amount. Defaults to R$ 0.01. Differences above the tolerance cause the settlement to be rejected. - **Derived partial state** — when `paid_amount > 0` and `paid_amount < expected_amount`, the instalment is considered partially paid. There is no new status: the state is DERIVED from the `paid_amount` and `expected_amount` columns. The `pending_conciliation` status covers both "not yet paid" and "partially paid"; `paid` only appears when the accumulated amount covers the expected one within the tolerance. ## Next steps Move on to the [Integration Guide](../roteiro-integracao/roteiro-integracao-padrao.md) to see the step-by-step flow. For the scenario in which a new operation repurchases open extraordinary amortizations, see [Amortization with Repurchase](./recompra-de-operacao.md). --- # Query Extraordinary Amortization URL: /en/documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao This endpoint returns a specific extraordinary amortization by its key (`extraordinary_event_conciliation_key`). Use it to follow the conciliation status of the event — from `pending_conciliation` (not yet paid or partially paid) through to the terminal state (`paid` or `canceled`) defined by QI Tech's internal orchestration. The query is date-agnostic and does not trigger any status transition: it only reflects the current state of the event and of each linked instalment. --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event/ EXTRAORDINARY-EVENT-CONCILIATION-KEY METHOD GET ### **Path Params** | Field | Type | Required | Description | |----------------------------------------|---------------|----------|----------------------------------------------------------------------| | `extraordinary_event_conciliation_key` | string (UUID) | Yes | Unique key of the extraordinary amortization event to be queried. | Example call: ``` GET /event_conciliation/extraordinary_event/11111111-1111-4111-8111-111111111111 ``` --- ## **Response** STATUS 200 Response Body ```json { "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111", "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "44444444-4444-4444-8444-444444444444", "amortization_type": "early_amortization", "total_expected_amount": 1500.00, "total_discount_amount": 0, "total_paid_amount": 0.0, "status": "pending_conciliation", "reference_date": "2026-04-24", "due_date": "2026-04-24", "paid_at": null, "event_conciliation_list": [ { "event_conciliation_key": "22222222-2222-4222-8222-222222222222", "installment_key": "33333333-3333-4333-8333-333333333333", "event_conciliation_status": "pending_conciliation", "event_conciliation_type": "extraordinary_event" } ] } ``` ### **Response Body Params** | Field | Type | Description | |----------------------------------------|-----------------|----------------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key` | string (UUID) | Key of the extraordinary amortization event queried. | | `security_key` | string (UUID) | Key of the asset (`security`) the event belongs to. | | `investment_key` | string (UUID) | Key of the investment targeted by the event. | | `amortization_type` | string | Amortization type of the event — echoes the value used on creation. | | `total_expected_amount` | number | Total expected amount of the event (sum distributed across the instalments) in BRL. | | `total_discount_amount` | number | Total discount applied. Different from zero only for `present_amount`. | | `total_paid_amount` | number | Amount already conciliated for the event (in BRL). `0` while no payment has been confirmed; `> 0` on partial payment. | | `status` | string | Current status of the event: `pending_conciliation`, `paid` or `canceled`. | | `reference_date` | string (date) | Reference date informed on creation. | | `due_date` | string (date) | Target settlement date informed on creation. | | `paid_at` | string (date) | Date on which the event was settled. `null` while it is not `paid`. | | `event_conciliation_list` | array | List of `event_conciliation` (conciliation event of each instalment) of the event. **[event_conciliation_list object](#event_conciliation_list-object)**. | ### **event_conciliation_list object** | Field | Type | Description | |-----------------------------|-----------------|-------------------------------------------------------------------------------------------| | `event_conciliation_key` | string (UUID) | Key of the instalment conciliation event (`event_conciliation`). | | `installment_key` | string (UUID) | Key of the instalment affected by this conciliation event. | | `event_conciliation_status` | string | Current status of the instalment conciliation event (`pending_conciliation`, `paid`, `canceled`). | | `event_conciliation_type` | string | Type of the `event_conciliation`. Always `extraordinary_event` for events created by this flow. | :::info The `status` (and each instalment's `event_conciliation_status`) reflects the current state at the moment of the query. The transition to `paid` or `canceled` is performed by QI Tech's internal orchestration — the integrator does not need to call any endpoint for that. ::: --- ## **Errors** | Code | HTTP | Meaning | |------------|------|----------------------------------------------------------------------------------------------------------| | EVC100011 | 404 | No extraordinary amortization found for the informed `extraordinary_event_conciliation_key`. | Refer to the [Error catalog](/documentation/escrituracao/catalogo-erros/catalogo-erros) for complete resolution. --- ## **See also** - [Create Extraordinary Amortization](./criar-amortizacao.md) - [Simulate Present Value of the Extraordinary Amortization](./simular-valor-presente.md) - [Concept](../conceito.md) - [Integration Guide](../../roteiro-integracao/roteiro-integracao-padrao.md) - [Business Rules](../regras-de-negocio.md) - [Examples](../exemplos.md) --- # Create Extraordinary Amortization URL: /en/documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao This endpoint creates an extraordinary amortization over one or more `installment` of an issuance. The event-conciliation-service groups the instalments into a single extraordinary amortization event, distributes the declared `amount` according to the informed `amortization_type` and obtains the Present Value via security-service — the integrator does not calculate Present Value on their side. The `reference_date` is provided by the caller in the extraordinary amortization request and is the only temporal reference used by the service when classifying overdue instalments and applying the pro-rata discount. --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event METHOD POST ### **Request Body** `installment_list` (an array of `installment_number`, integers ≥ 1) is required for every type: it defines the target instalments and the `amortization_type` defines how the `amount` is distributed across them. The numbers sent in `installment_list` are resolved by the service against the `installment_number` of the corresponding `security`. Example — `early_amortization` (a single future instalment): ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "early_amortization", "amount": 1500.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [1] } ``` Example — `equal_amount` (proportional across the selected instalments): ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "equal_amount", "amount": 5000.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [1, 2, 3, 4] } ``` Example — `nominal_amount` (future instalments at nominal value): ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "nominal_amount", "amount": 18670.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [3, 4] } ``` ### **Request Body Params** | Field | Type | Required | Description | |---------------------------|-----------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | Yes | Unique key of the asset (`security`) to which the amortization will be applied. | | `investment_key` | string (UUID) | Yes | Key of the target investment. Used by security-service as the proportional basis in the Present Value calculation. | | `amortization_type` | string | Yes | Distribution strategy. Values: `equal_amount`, `first_installments`, `present_amount`, `matured_installments`, `early_amortization`, `nominal_amount`, `full_amortization`. | | `amount` | number | Yes | Total amount to be amortized (in BRL). Distributed across the selected instalments according to the `amortization_type`. | | `reference_date` | string (date) | Yes | Reference date in `YYYY-MM-DD` format. **Provided by the caller** — the service uses it as "today" to classify overdue instalments and apply the pro-rata Present Value discount. | | `due_date` | string (date) | Yes | Target settlement date (typically the same as `reference_date`). | | `installment_list` | array of integers (≥ 1) | Yes | List of `installment_number` (not UUIDs) of the target instalments, with `minItems: 1`. Required for every type — omitting it returns `EVC100002`. The service resolves each number against the `installment_number` of the `security`; non-existent numbers return `EVC000007`. The legacy `installment_key_list` has been removed — clients still sending the field receive `QIT000001` (400). | | `total_discount` | number | No | Used only with `present_amount` — distributes the discount in the order interest → penalty → principal. | | `number_of_installments` | integer | Conditional | Required with `first_installments`: how many of the selected instalments, by due date, receive the amount. | --- ## **Response** STATUS 201 Response Body ```json { "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111", "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "amortization_type": "early_amortization", "total_expected_amount": 1500.00, "total_discount_amount": 0, "status": "pending_conciliation", "reference_date": "2026-04-24", "due_date": "2026-04-24", "event_conciliation_list": [ { "event_conciliation_key": "22222222-2222-4222-8222-222222222222", "installment_key": "33333333-3333-4333-8333-333333333333", "expected_amount": 1500.00, "discount_amount": 0, "due_date": "2026-04-24", "status": "pending_conciliation", "event_conciliation_type": "extraordinary" } ] } ``` ### **Response Body Params** | Field | Type | Description | |---------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key`| string (UUID) | Key of the general extraordinary amortization event created. | | `security_key` | string (UUID) | Key of the asset — echoes the value sent. | | `amortization_type` | string | Chosen amortization type — echoes the value sent. | | `total_expected_amount` | number | Sum distributed across the `event_conciliation` (instalment conciliation events) by the engine of the chosen type. | | `total_discount_amount` | number | Total discount applied. Different from zero only for `present_amount`. | | `status` | string | Initial status of the extraordinary event. Always `pending_conciliation` on creation. | | `reference_date` | string (date) | Reference date sent in the request (it must match the payoff date). | | `due_date` | string (date) | Target settlement date sent in the request. | | `event_conciliation_list` | array | List of `event_conciliation` (instalment conciliation event) generated. **[event_conciliation_list object](#event_conciliation_list-object)**. | ### **event_conciliation_list object** | Field | Type | Description | |--------------------------|-----------------|-------------------------------------------------------------------------------------------| | `event_conciliation_key` | string (UUID) | Key of the instalment conciliation event (`event_conciliation`). | | `installment_key` | string (UUID) | Key of the instalment affected by this conciliation event. | | `expected_amount` | number | Amount assigned to this instalment conciliation event by the distribution engine. | | `discount_amount` | number | Share of the `total_discount` allocated to this instalment conciliation event (`present_amount`) or difference between the instalment's Present Value and the received share (`full_amortization`). | | `due_date` | string (date) | Due date of the associated instalment. | | `status` | string | Initial status of the instalment conciliation event. Always `pending_conciliation` on creation. | | `event_conciliation_type`| string | Type of the `event_conciliation`. Always `extraordinary` for instalment conciliation events created by this flow. | --- ## **Errors** | Code | HTTP | Meaning | |------------|------|----------------------------------------------------------------------------------------------------------| | EVC100001 | 400 | Invalid `amortization_type`. Use one of the seven supported values. | | EVC100002 | 400 | `installment_list` is required (and non-empty) for every amortization type. | | EVC100003 | 400 | `number_of_installments` is required for `first_installments`. | | EVC100004 | 400 | Some informed instalment does not belong to the target `security`. | | EVC000007 | 404 | Some integer in `installment_list` does not match any `installment_number` of the `security` (`InstallmentNumberNotFound`). | | QIT000001 | 400 | Schema failure — for example, sending the legacy `installment_key_list` (removed) or an `installment_list` item that is not an integer ≥ 1. | | EVC100005 | 400 | `amount` does not cover all the selected instalments (not applicable to `early_amortization`). | | EVC100006 | 400 | `total_discount` exceeds the sum of the Present Value of the selected instalments. | | EVC100007 | 400 | For `matured_installments`, all the selected instalments must be overdue. | | EVC100008 | 400 | There is already a pending extraordinary amortization for the instalment — cancel it before creating another. | | EVC100013 | 424 | Security API unavailable (Failed Dependency). Transient — retry once it is restored. | | EVC100015 | 400 | `early_amortization` requires exactly 1 instalment in `installment_list`. | | EVC100016 | 400 | The target instalment of `early_amortization` must not be overdue. | | EVC100017 | 400 | In `early_amortization`, `amount` must be less than or equal to the Present Value of the instalment. | | EVC100030 | 400 | In `nominal_amount`, every selected instalment must be a future one (not overdue on the `reference_date`). | | EVC100031 | 400 | In `nominal_amount`, `amount` must be less than or equal to the sum of the nominal values of the selected instalments. | | EVC100032 | 400 | No selected instalment would receive a positive `expected_amount` — the event is not created. | | EVC100033 | 400 | The sum of the distributed `expected_amount` differs from the declared `amount` by more than R$ 0.01. | | EVC100034 | 400 | A selected instalment would end with an `expected_amount` of zero — select only instalments the `amount` covers. | | EVC100035 | 400 | `amount` exceeds the sum of the selected instalments' Present Values (Present-Value-priced types). | Refer to the [Error catalog](/documentation/escrituracao/catalogo-erros/catalogo-erros) for complete resolution. --- ## **See also** - [Simulate Present Value of the Extraordinary Amortization](./simular-valor-presente.md) - [Query Extraordinary Amortization](./consultar-amortizacao.md) - [Concept](../conceito.md) - [Integration Guide](../../roteiro-integracao/roteiro-integracao-padrao.md) - [Business Rules](../regras-de-negocio.md) - [Examples](../exemplos.md) --- # Simulate the Present Value of an Extraordinary Amortization URL: /en/documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente This endpoint simulates an extraordinary amortization of type `present_amount` without creating any event — it is a pure calculation, with no side effects. From the installments provided in `installment_list`, the service calculates and returns the total `amount` (Present Value) of the extraordinary event that would be created, plus the Present Value of each `event_conciliation` (type `extraordinary`) per installment — the integrator does not calculate Present Value on their side. `amortization_type` is not sent in the request: since this is a Present Value simulation, the type is always `present_amount`. `amount` is not sent either — it is the result of the calculation. The `reference_date` is provided by the caller and is the only temporal reference used by the service to classify overdue installments and apply the pro-rata Present Value discount; in the simulation, the `due_date` is assumed to be equal to the `reference_date`. The response is the ready-to-use creation payload: just remove the `event_conciliation_list` field — which is informational only — and send it as the body of [Create Extraordinary Amortization](./criar-amortizacao) to execute the simulated amortization. --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event/present_value_simulation METHOD POST ### **Request Body** ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "reference_date": "2026-04-24", "installment_list": [1, 2] } ``` ### **Request Body Params** | Field | Type | Required | Description | |--------------------|--------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | Yes | Unique key of the asset (`security`) on which the amortization will be simulated. | | `investment_key` | string (UUID) | Yes | Key of the target investment. Used as the proportional basis for the Present Value calculation. | | `reference_date` | string (date) | Yes | Reference date in `YYYY-MM-DD` format. **Provided by the caller** — the service uses it as "today" to classify overdue installments and apply the pro-rata Present Value discount. In the simulation, it is also used as the `due_date`. | | `installment_list` | array of integers (≥ 1) | Yes | List of `installment_number` (not UUIDs) of the target installments, with `minItems: 1`. The service resolves each number against the `security`'s `installment_number`; non-existent numbers return `EVC000007`. | Unlike creation, `amortization_type`, `amount`, and `due_date` **are not sent**: the type is always `present_amount`, the `amount` is calculated by the service, and the `due_date` is assumed to be equal to the `reference_date`. --- ## **Response** STATUS 200 Response Body ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "present_amount", "amount": 4750.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [1, 2], "event_conciliation_list": [ { "installment_number": 1, "amount": 2400.00 }, { "installment_number": 2, "amount": 2350.00 } ] } ``` ### **Response Body Params** | Field | Type | Description | |---------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | Asset key — echoes the value sent. | | `investment_key` | string (UUID) | Target investment key — echoes the value sent. | | `amortization_type` | string | Always `present_amount` — filled in by the service to compose the creation payload. | | `amount` | number | Total Present Value calculated for the extraordinary event (sum of the `amount` fields in `event_conciliation_list`). | | `reference_date` | string (date) | Reference date — echoes the value sent. | | `due_date` | string (date) | Target settlement date — equal to the `reference_date` sent. | | `installment_list` | array of integers | Target installments — echoes the value sent. | | `event_conciliation_list` | array | Present Value per installment of the `event_conciliation` (type `extraordinary`) that would be generated. **For visualization only — not part of the creation payload.** **[Object event_conciliation_list](#object-event_conciliation_list)**. | :::info The `event_conciliation_list` field is **for visualization only** — it shows the Present Value simulation for each installment and **must not be included** in the creation payload of the extraordinary event. To execute the simulated amortization, send the response **without** `event_conciliation_list` as the body of [Create Extraordinary Amortization](./criar-amortizacao). ::: ### **Object event_conciliation_list** | Field | Type | Description | |----------------------|---------|----------------------------------------------------------------------------------------------------------------| | `installment_number` | integer | Number of the installment (`installment_number`) this conciliation event refers to. | | `amount` | number | Present Value calculated for the `event_conciliation` (type `extraordinary`) of this installment. | --- ## **Errors** | Code | HTTP | Meaning | |------------|------|-------------------------------------------------------------------------------------------------------------------------------------------| | EVC100002 | 400 | `installment_list` is required and cannot be empty. | | EVC100004 | 400 | One of the provided installments does not belong to the target `security`. | | EVC000007 | 404 | An integer in `installment_list` does not match any `installment_number` of the `security` (`InstallmentNumberNotFound`). | | QIT000001 | 400 | Schema failure — for example, an `installment_list` item that is not an integer ≥ 1. | | EVC100008 | 400 | There is already a pending extraordinary amortization for the installment — cancel it before simulating/creating another. | | EVC100013 | 424 | Dependency temporarily unavailable (Failed Dependency). Transient — retry once it is restored. | `EVC100005` (insufficient `amount`) does not apply to the simulation — the `amount` is calculated by the service, not sent. See the [Error catalog](/documentation/escrituracao/catalogo-erros/catalogo-erros) for complete resolution. --- ## **See also** - [Create Extraordinary Amortization](./criar-amortizacao) - [Get Extraordinary Amortization](./consultar-amortizacao) - [Concept](../conceito) - [Integration Guide](../../roteiro-integracao/roteiro-integracao-padrao) - [Business Rules](../regras-de-negocio) - [Examples](../exemplos) --- # Examples — Extraordinary Amortization URL: /en/documentation/escrituracao/amortizacao-extraordinaria/exemplos This page presents two creation scenarios. The integrator's interaction is **fire-and-forget**: it only makes the creation call and QI Tech orchestrates settlement, finalization and cancellation internally. There is no tenant-facing webhook dedicated to the status transitions of the extraordinary `event_conciliation`; confirmation of the operation's effect is observed through the reports and webhooks that already exist for the underlying operation (e.g. `commercial_paper.operation_status_change`). ## Scenario 1: partial early payoff of an instalment (early_amortization) Covers a single future instalment, with partial payment allowed. `POST /event_conciliation/extraordinary_event` ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "early_amortization", "amount": 1500.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [3] } ``` Response: `201 Created` ```json { "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111", "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "amortization_type": "early_amortization", "total_expected_amount": 1500.00, "total_discount_amount": 0, "status": "pending_conciliation", "reference_date": "2026-04-24", "due_date": "2026-04-24", "event_conciliation_list": [ { "event_conciliation_key": "22222222-2222-4222-8222-222222222222", "installment_key": "33333333-3333-4333-8333-333333333333", "expected_amount": 1500.00, "discount_amount": 0, "due_date": "2026-04-24", "status": "pending_conciliation", "event_conciliation_type": "extraordinary" } ] } ``` From this 201 onward the integration is complete on the integrator's side. When the payment of R$ 1,500.00 reaches the corresponding settlement account, QI Tech (account-liquidation-api) settles the instalment conciliation event internally and updates the `paid_amount`; when the sum covers `total_expected_amount - tolerance_amount`, the parent transitions to `paid`. If the payment does not come in, the event is cancelled or finalized by the security-service daily settlement routine. ## Scenario 2: full payoff with discount (present_amount with 2 installments) Creates an amortization with a consolidated discount covering two instalments. `POST /event_conciliation/extraordinary_event` ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "present_amount", "amount": 5000.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [1, 2], "total_discount": 100.00 } ``` Response `201 Created` — two instalment conciliation events are generated with the amounts distributed according to the `present_amount` engine (interest → penalty → principal). See [Create Extraordinary Amortization](./endpoints/criar-amortizacao.md) for the complete response shape. From the 201 onward the integrator's interaction is the same as in Scenario 1: QI Tech settles each instalment conciliation event when the corresponding payments come in, and finalizes or cancels the event internally if the amounts do not arrive within the settlement window. ## Scenario 3: settling future instalments at nominal value (nominal_amount) The issuer wants to settle instalments 3 and 4 before maturity by paying the nominal value of each (principal + interest at maturity), with no Present Value discount. The `reference_date` precedes both due dates. ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "nominal_amount", "amount": 18670.00, "reference_date": "2026-02-08", "due_date": "2026-06-06", "installment_list": [3, 4] } ``` Response `201 Created` — one instalment conciliation event per instalment, with `expected_amount` equal to the nominal value of each (`9360.00` and `9310.00` in this example). If the `amount` were lower than the sum, instalment 3 would be covered first and instalment 4 would receive the remainder. Overdue instalments return `EVC100030`; an `amount` above the sum of the nominal values returns `EVC100031`. Settlement accepts partial payment, as in `early_amortization`. ## Scenario 4: full settlement for a negotiated amount (full_amortization) Issuer and investor agree to settle instalments 1 and 2 for R$ 10,000.00, although their Present Values on the `reference_date` are R$ 9,460.00 and R$ 9,410.00. The `amount` is split proportionally to Present Value and each instalment is settled in full at liquidation. ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "full_amortization", "amount": 10000.00, "reference_date": "2026-02-08", "due_date": "2026-02-08", "installment_list": [1, 2] } ``` Response `201 Created` — two instalment conciliation events with `expected_amount` `5013.25` and `4986.75` (the sum equals the `amount`) and `discount_amount` `4446.75` and `4423.25`. An `amount` above the sum of the Present Values returns `EVC100035`; an `amount` too small to give every instalment a positive share returns `EVC100034`. ## Troubleshooting The most common error codes when calling creation. For the complete list, refer to the [Error catalog](/documentation/escrituracao/catalogo-erros/catalogo-erros). - **`EVC100015`** (400, EarlyAmortizationRequiresSingleInstallment) — `early_amortization` accepts exactly one instalment in `installment_list`. Reduce it to 1. - **`EVC000007`** (404, InstallmentNumberNotFound) — some `installment_number` sent in `installment_list` does not exist in the target `security`. Check the numbers returned by `GET /security/security/{security_key}` before calling. - **`QIT000001`** (400) — schema rejected. Typical cause: sending the legacy `installment_key_list` field (removed) or non-integer items in `installment_list`. - **`EVC100016`** (400, EarlyAmortizationInstallmentOverdue) — the target instalment of `early_amortization` is overdue and is not eligible. Select a future instalment. - **`EVC100017`** (400, EarlyAmortizationAmountExceedsPresentValue) — in `early_amortization`, the `amount` exceeded the Present Value of the instalment. Confirm the PV before calling. - **`EVC100030`** (400, InstallmentNotEligibleForNominalAmortization) — in `nominal_amount`, some instalment in `installment_list` is already overdue on the `reference_date`. Select only future instalments. - **`EVC100031`** (400, NominalAmountExceedsInstallmentsNominalValue) — in `nominal_amount`, the `amount` exceeded the sum of the nominal values (principal + interest) of the selected instalments. Lower the `amount`. - **`EVC100033`** (400, DistributionDoesNotMatchAmount) — the sum of the distributed `expected_amount` differs from the declared `amount` by more than R$ 0.01. For `present_amount`, send an `amount` equal to the sum of the Present Values minus `total_discount`. - **`EVC100034`** (400, DistributionWithZeroInstallment) — a selected instalment would end with an `expected_amount` of zero (for example, `total_discount` equal to the Present Value, or an `amount` exhausted before the last instalment). Select only instalments the `amount` covers. - **`EVC100035`** (400, AmountExceedsInstallmentsPresentValue) — the `amount` exceeds the sum of the selected instalments' Present Values. Lower the `amount`. - **`EVC100013`** (424, SecurityApiUnavailable) — Security API temporarily unavailable when fetching the Present Value; this is transient. Wait and repeat the call. - **`SEC000031`** (400, PostFixedSecurityNotSupported) — post-fixed assets (CDI, IPCA, IGPM) are not supported in V1. Use `pre_price` or `pre_sac` assets. ## See also - [Concept](./conceito.md) - [Integration Guide](../roteiro-integracao/roteiro-integracao-padrao.md) - [Business Rules](./regras-de-negocio.md) - [Create Extraordinary Amortization](./endpoints/criar-amortizacao.md) - [Query Extraordinary Amortization](./endpoints/consultar-amortizacao.md) - [Operation Repurchase](./recompra-de-operacao.md) - [Error catalog](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Amortization with Repurchase URL: /en/documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao ## Overview **Repurchase** is the flow in which a **new** commercial note operation is issued to "repurchase" one or more open extraordinary amortizations of an existing operation. The typical scenario: the debtor has an open operation and, together with the investor, decides to repurchase it — through refinancing or for any other negotiated reason. Instead of paying off the debt with their own funds, they structure a new operation whose disbursement automatically settles the chosen extraordinary amortizations. The new operation is issued by the **same debtor** (`issuer`) as the events being repurchased. The repurchase may cover: - **A single extraordinary amortization** — the most common case, repurchasing one operation. - **Multiple assets** — by passing several `extraordinary_event_conciliation_key`, including from different `security`, when the debtor wants to repurchase more than one asset in the same new operation. Repurchase is not a separate API call: it is declared **at the moment the new operation is created**, by informing the list of keys of the extraordinary events to be repurchased. ## Prerequisite Each extraordinary amortization to be repurchased must **already exist** — previously created through the [extraordinary amortization](./endpoints/criar-amortizacao.md) flow — and be in `pending_conciliation` at the moment the new operation is created. It is these keys (`extraordinary_event_conciliation_key`) that you reference in the repurchase. :::warning Dates must match the disbursement The `reference_date` and `due_date` informed **when creating the extraordinary event** must correspond to the **disbursement date** of the new repurchase operation. If these dates do not match the disbursement, the events **are not disbursed correctly and are automatically cancelled** — the repurchase does not take effect. Plan the extraordinary event's `reference_date`/`due_date` already taking into account when the new operation will be disbursed. ::: ## How to trigger it Repurchase is declared in the [Commercial Note Operation Registration](../emissao-de-notas/cadastro-operacao/criar-operacao.md) (`POST /commercial_paper/operation`): simply send, together with the normal operation creation fields, the `extraordinary_event_conciliation_key_list` field with the keys of the extraordinary events you wish to repurchase. ```json { "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_bank_account": { "account_number": "4464541", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" }, "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "issue_date": "2025-01-23", "financial": { "interest_type": "pre_price_days", "financial_base_date": "2025-01-23", "released_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee" } ] }, "extraordinary_event_conciliation_key_list": [ "11111111-1111-4111-8111-111111111111" ] } ``` The `extraordinary_event_conciliation_key_list` is the **only** addition compared to a common operation registration — all other fields follow the [operation creation contract](../emissao-de-notas/cadastro-operacao/criar-operacao.md). Refer to that page for the complete reference of each field (`issuer_key`, `issuer_bank_account`, `investors`, `issue_date`, `financial`). ### Field | Field | Type | Required | Description | |--------------------------------------------|--------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key_list`| array of string (UUID) | No | List of keys of the extraordinary amortizations to be repurchased. Unique items; one key per repurchased asset. May span multiple `security`. Omit the field in operations without repurchase. | ## Amount rule The amount of the new operation must be sufficient to cover what is being repurchased. The rule applied at **operation creation** is: > The sum of the `expected_amount` of all events referenced in `extraordinary_event_conciliation_key_list` must be **less than or equal to** the `released_amount` of the new operation. Otherwise, creation is rejected with **`COM000050`** (400). :::info `released_amount` and fees `released_amount` is the **issuance amount net of financed fees**. Therefore, in practice, the issuance amount of the new operation must cover at least the amount of the repurchased events **+ fees** — only then does the resulting `released_amount` reach the sum of the `expected_amount`. ::: ## Disbursement > **Internal orchestration.** The repurchase itself happens at the disbursement of the new operation and is executed internally by QI Tech — the integrator **does not call** any additional endpoint at this stage. When the new operation is disbursed: 1. The referenced extraordinary amortizations are **automatically settled**, transitioning from `pending_conciliation` to `paid`. 2. The **remainder** — `released_amount − Σ expected_amount`, when positive — is **passed on to the debtor**. That is, part of the disbursement pays off the repurchased events and whatever is left goes to the debtor, in a single operation. ## See also - [Concept](./conceito.md) - [Create Extraordinary Amortization](./endpoints/criar-amortizacao.md) - [Query Extraordinary Amortization](./endpoints/consultar-amortizacao.md) - [Business Rules](./regras-de-negocio.md) - [Examples](./exemplos.md) - [Integration Guide](../roteiro-integracao/roteiro-integracao-padrao.md) - [Error catalog](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Business Rules — Extraordinary Amortization URL: /en/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio This page consolidates the invariants that govern the creation, settlement and cancellation of an extraordinary amortization. Refer to it whenever the endpoint pages cite an error code, a field or a condition that needs additional context. ## Reference date (`reference_date`) The `reference_date` is **provided by the caller** in the creation request and is the only temporal reference used by the service — the system **never uses** `date.today()`. All date-dependent logic (classification of overdue instalments, pro-rata Present Value discount, selection of instalments eligible for `early_amortization` and `nominal_amount`) starts from this field. The Present Value lookup on security-service receives this same `reference_date`. ## Amortization types The 7 supported types and how each distributes the `amount` across the instalments in `installment_list`: | Type | Distribution rule across the selected instalments | Allows partial payment | |------------------------|----------------------------------------------------------------------------------------------------|------------------------| | `equal_amount` | Proportional to the Present Value, overdue first and then future | No | | `first_installments` | Sequential across the first N selected instalments (by due date), N = `number_of_installments` | No | | `present_amount` | Explicit per instalment; discount orders interest → penalty → principal | No | | `matured_installments` | Only instalments already fallen due, by due date | No | | `early_amortization` | A single future instalment, up to its Present Value | **Yes** | | `nominal_amount` | Future instalments at nominal value (principal + interest), by due date, without Present Value | **Yes** | | `full_amortization` | Proportional to Present Value across every selected instalment, no cascade; each instalment is settled in full | No | `installment_list` (an array of integer `installment_number`) is **required for every type** — omitting it returns `EVC100002`. The service resolves each `installment_number` to the corresponding instalment of the `security` and fetches the Present Value per selected instalment; the `amortization_type` only defines how the `amount` is distributed across those instalments. ## Early amortization (`early_amortization`) `early_amortization` allows partial payment (as does `nominal_amount`). All of the following conditions apply: - Exactly **1** instalment in `installment_list` — otherwise, `EVC100015`. - The target instalment **must not be overdue** — otherwise, `EVC100016`. - The `amount` must be **≤ the Present Value** of the instalment — otherwise, `EVC100017`. - **Partial payment is allowed.** The state `paid_amount > 0 AND paid_amount = total_expected_amount - tolerance_amount`. ## Nominal value amortization (`nominal_amount`) `nominal_amount` settles future instalments at their nominal value — principal plus interest at maturity — without bringing them to the Present Value of the `reference_date`. All of the following conditions apply: - Every instalment in `installment_list` must have a `due_date` on or after the `reference_date` — an overdue instalment returns `EVC100030`. - The `amount` is distributed by due date, covering each instalment at its nominal value until it is exhausted; the last instalment reached may receive a partial amount. - The `amount` must be **≤ the sum of the nominal values** of the selected instalments — otherwise, `EVC100031`. - **Partial payment is allowed** at settlement, with the same derived state described for `early_amortization`. ## Full settlement (`full_amortization`) `full_amortization` uses the declared `amount` to settle **every** instalment in `installment_list`, regardless of each one's Present Value: - The `amount` is split across the instalments proportionally to their Present Value on the `reference_date`, with no cascade — no instalment is left without a share. - Each `event_conciliation` is created with `expected_amount` equal to its share and `discount_amount` equal to the difference between the Present Value and the share. - The `amount` cannot exceed the sum of the selected instalments' Present Values — otherwise, `EVC100035`. - At liquidation, paying the share settles the instalment **in full** on security-service: the paid amount is recorded as paid and the difference as the instalment's discount. The same applies to `present_amount`. ## Consistency between `amount` and the distribution After distributing the `amount`, the service validates the result for **every** type, in this order: 1. `amount` greater than the sum of the distributed instalments' Present Values → `EVC100035` (Present-Value-priced types; `early_amortization` and `nominal_amount` keep `EVC100017` and `EVC100031`). 2. Any selected instalment would end with an `expected_amount` of zero → `EVC100034`. No event is created with zero-valued children; select only instalments the `amount` covers. 3. The sum of the distributed `expected_amount` differs from `amount` by more than R$ 0.01 → `EVC100033`. For `present_amount`, `amount` must equal the sum of the Present Values minus `total_discount`. The `expected_amount` values are stored in cents, with the rounding residual on the last instalment, so the event's `total_expected_amount` always equals the sum of its children. ## Settlement flow > **Internal orchestration.** Settlement of extraordinary events is executed by QI Tech (account-liquidation-api) upon detecting the payment — the integrator **does not call** any endpoint at this stage, nor receives a webhook dedicated to the status transitions. The rules below describe the internal behaviour so you understand what happens after creation. **Ordinary settlement emits the full total (rule 4).** Ordinary settlement on the `due_date` continues to emit the instalment's full `total_amount` via SQS; there is no subtraction of `paid_amount`. The event reconciles the partially-paid state in its own `early_amortization` engine. ## Cancellation and finalization > **Internal orchestration.** Cancellation and finalization are triggered by a daily routine — the integrator **does not call** any endpoint to cancel or finalize an extraordinary amortization, and there is no tenant-facing webhook dedicated to these transitions. The description below is informative. ## See also - [Concept](./conceito.md) - [Integration Guide](../roteiro-integracao/roteiro-integracao-padrao.md) - [Create Extraordinary Amortization](./endpoints/criar-amortizacao.md) - [Query Extraordinary Amortization](./endpoints/consultar-amortizacao.md) - [Operation Repurchase](./recompra-de-operacao.md) - [Examples](./exemplos.md) - [Error catalog](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Error Catalog URL: /en/documentation/escrituracao/catalogo-erros/catalogo-erros ## Error formatting All APIs in the bookkeeping integration return API errors formatted according to the following description: Error Response Body ```json { "title": "HTTP Status code name", "description": "An english description of the error", "translation": "Uma descrição em português do erro", "code": "ERROR_UNIQUE_CODE" } ``` --- ## Table of possible errors in the issuer approval process | HTTP Code | Error Code | Title | Description (eng) | Translation (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | ISS000003 | Bad Request | Issuer already exists in database. | Emissor já existe na base de dados. | | 404 | ISS000004 | Not Found | Issuer representative not found. | Representante do emissor não encontrado. | | 404 | ISS000005 | Not Found | Bank account not found. | Conta bancária não encontrada. | | 404 | ISS000006 | Not Found | Issuer document not found. | Documento do emissor não encontrado. | | 404 | ISS000007 | Not Found | Issuer representative document not found. | Documento do representante do emissor não encontrado. | | 404 | ISS000008 | Not Found | Issuer contact information not found. | Contato do emissor não encontrado. | | 404 | ISS000009 | Not Found | Issuer not found. | Emissor não encontrado. | | 404 | ISS0000010 | Not Found | Signer Group not found. | Grupo de assinantes não encontrado. | | 400 | ISS0000011 | Bad Request | Issuer must be in status in_filling to allow this action. | Emissor deve estar no estado in_filling para permitir esta ação. | | 400 | ISS0000018 | Bad Request | Document sent is invalid or quality is low. | Documento enviado é inválido ou de baixa qualidade. | | 400 | ISS0000012 | Bad Request | Deleting the main account is not allowed, please set a new main account first. | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. | | 400 | ISS0000013 | Bad Request | Deleting the main contact is not allowed, please set a new main contact first. | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. | | 400 | ISS0000014 | Bad Request | Issuer must have at least one contact information. | Emissor precisa ter ao menos uma informação de contato. | | 400 | ISS0000015 | Bad Request | Tenant already has access to this issuer. | Acesso aos dados do emissor já foi concedido. | | 400 | ISS0000016 | Bad Request | Failed trying to contact issuer, please retry. | Falha ao enviar mensagem ao emissor, tente novamente. | | 400 | ISS0000017 | Bad Request | Invalid link. | Link inválido. | ## Table of possible errors in the investor approval process | HTTP Code | Error Code | Title | Description (eng) | Translation (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | INV000003 | Bad Request | Investor already exists in database. | Emissor já existe na base de dados. | | 404 | INV000004 | Not Found | Investor representative not found. | Representante do emissor não encontrado. | | 404 | INV000005 | Not Found | Bank account not found. | Conta bancária não encontrada. | | 404 | INV000006 | Not Found | Investor document not found. | Documento do emissor não encontrado. | | 404 | INV000007 | Not Found | Investor representative document not found. | Documento do representante do emissor não encontrado. | | 404 | INV000008 | Not Found | Investor contact information not found. | Contato do emissor não encontrado. | | 404 | INV000009 | Not Found | Investor not found. | Emissor não encontrado. | | 404 | INV0000010 | Not Found | Signer Group not found. | Grupo de assinantes não encontrado. | | 400 | INV0000011 | Bad Request | Investor must be in status in_filling to allow this action. | Emissor deve estar no estado in_filling para permitir esta ação. | | 400 | INV0000018 | Bad Request | Document sent is invalid or quality is low. | Documento enviado é inválido ou de baixa qualidade. | | 400 | INV0000012 | Bad Request | Deleting the main account is not allowed, please set a new main account first. | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. | | 400 | INV0000013 | Bad Request | Deleting the main contact is not allowed, please set a new main contact first. | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. | | 400 | INV0000014 | Bad Request | Investor must have at least one contact information. | Emissor precisa ter ao menos uma informação de contato. | | 400 | INV0000015 | Bad Request | Tenant already has access to this investor. | Acesso aos dados do emissor já foi concedido. | | 400 | INV0000016 | Bad Request | Failed trying to contact investor, please retry. | Falha ao enviar mensagem ao emissor, tente novamente. | | 400 | INV0000017 | Bad Request | Invalid link. | Link inválido. | ## Table of possible errors in the commercial paper issuance process | HTTP Code | Error Code | Title | Description (eng) | Translation (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | COM000001 | Bad Request | Document is not valid. | Documento fornecido não é válido. | | 400 | COM000002 | Bad Request | Tenant must be configured before use this endpoint. | Tenant precisa ser configurado antes de utilizar este endpoint. | | 409 | COM000003 | Conflict | Tenant configuration already exists. | Configuração para este tenant já existe. | | 400 | COM000004 | Bad Request | Investor with key (investor_key) is not allowed. Please check. | Investidor com a chave (investor_key) não permitido. Cheque o cadastro. | | 400 | COM000005 | Bad Request | Issuer with key (issuer_key) is not allowed. Please check. | Emissor com a chave (issuer_key) não permitido. Cheque o cadastro. | | 400 | COM000006 | Bad Request | Operation with more than one investor functionality not available yet. | Operação com mais de um investidor não disponível ainda. | | 404 | COM000007 | Not Found | Operation (operation_key) not found. | Operação (operation_key) não encontrada. | | 403 | COM000008 | Forbidden | Operation (operation_key) does not belong to tenant. | Operação (operation_key) não pertence ao tenant. | | 400 | COM000010 | Bad Request | Operations cannot be updated outside of in_filling status. | Operação não pode ser atualizada fora do status in_filling. | | 404 | COM000011 | Not Found | Related party not found. | Parte relacionada não encontrada. | | 400 | COM000012 | Bad Request | Related party (related_party_key) is not associated with operation (operation_key). | A parte relacionada (related_party_key) não está associada com a operação (operation_key). | | 404 | COM000013 | Not Found | Signer Group not found. | Grupo de assinantes não encontrado. | | 400 | COM000014 | Bad Request | Signer group (signer_group_key) is not associated with related party (related_party_key). | O grupo de assinantes (signer_group_key) não está associado com a parte relacionada (related_party_key). | | 400 | COM000015 | Bad Request | Signer list does not match minimum required signers field. | Lista de assinantes não é compatível com o mínimo de assinantes enviado. | | 404 | COM000016 | Not Found | Document not found. | Documento não encontrado. | | 400 | COM000017 | Bad Request | Document (document_key) is not associated with related party (related_party_key). | O documento (document_key) não está associado com a parte relacionada (related_party_key). | | 400 | COM000018 | Bad Request | Document sent is invalid or quality is low. | Documento enviado é inválido ou de baixa qualidade. | | 400 | COM000019 | Bad Request | Delete issuer or investor is not allowed. | Não é possível deletar o emissor ou investidor. | | 400 | COM000020 | Bad Request | Operation is in a final status and cannot be modified. | Operação já está em um estado final e não pode ser atualizada. | | 400 | COM000021 | Bad Request | Operation is not in analysis. | Operação não está em análise. | | 400 | COM000022 | Bad Request | Document not signed yet. | Documento ainda não foi assinado. | | 400 | COM000023 | Bad Request | Document not available yet. | Documento ainda não foi gerado. | | 400 | COM000024 | Bad Request | Failed to send document to signature, please retry. | Falha ao enviar documento para assinatura, tente novamente. | | 404 | COM000025 | Not Found | Collateral not found. | Garantia não encontrada. | | 400 | COM000026 | Bad Request | Collateral (collateral_key) is not associated with operation (operation_key). | A garantia (collateral_key) não está associada com a operação (operation_key). | | 400 | COM000027 | Bad Request | Metadata not found. | Metadado não encontrado. | | 400 | COM000028 | Bad Request | Operation is canceled and cannot be modified. | Operação está cancelada e não pode ser atualizada. | | 400 | COM000061 | Bad Request | Third-party disbursement slip amount does not match the operation's `released_amount`. | Valor do boleto do desembolso a terceiro diferente do `released_amount` da operação. | | 400 | COM000062 | Bad Request | Third-party disbursement is not enabled. | Tenant não habilitado para desembolso a terceiro. | | 400 | COM000063 | Bad Request | Third-party disbursement beneficiary document is invalid. | Documento do beneficiário do desembolso a terceiro inválido. | | 400 | COM000071 | Bad Request | Third-party disbursement `pix_key` of type `cpf`/`cnpj` has invalid check digits. | A `pix_key` de tipo `cpf`/`cnpj` do desembolso a terceiro tem dígito verificador inválido. | | 400 | COM000072 | Bad Request | The operation uses external signature and `p7s_base64` was not sent. | A operação usa assinatura externa e o `p7s_base64` não foi enviado. | | 400 | COM000073 | Bad Request | The signature file could not be read as a CMS structure, or exceeds the accepted size. | O arquivo de assinatura não pôde ser lido como estrutura CMS, ou excede o tamanho aceito. | | 422 | COM000074 | Unprocessable Entity | The signature does not match the document issued by QI Tech. | A assinatura não corresponde ao documento emitido pela QI Tech. | | 409 | COM000075 | Conflict | The document already had a signature accepted. | O documento já teve uma assinatura aceita. | | 400 | COM000077 | Bad Request | Operation issuer is not enabled for auto signature. | Emissor da operação não está habilitado para auto-assinatura. | ## Table of possible errors in the quota integration process | HTTP Code | Error Code | Title | Description (eng) | Translation (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | INT000001 | Bad Request | Document is not valid. | Documento fornecido não é válido. | | 404 | INT000002 | Not Found | Integralization process (integralizaion_key) not found. | Processo de integralização (integralizaion_key) não encontrado. | | 403 | INT000003 | Forbidden | Integralization process (integralizaion_key) does not belong to tenant. | Processo de integralização (integralizaion_key) não pertence ao tenant. | | 404 | INT000004 | Not Found | Subscription (subscription_key) not found. | Subscrição (subscription_key) não encontrada. | | 400 | INT000005 | Bad Request | Subscription (subscription_key) is not associated with integralization process (integralizaion_key). | A subscrição (subscription_key) não está associada com o processo de integralização (integralizaion_key). | | 404 | INT000006 | Not Found | Subscription payment not found. | Pagamento de subscrição não encontrado. | | 400 | INT000007 | Bad Request | Subscription payment (subscription_payment_key) is not associated with subscription (subscription_key). | O pagamento de subscrição (subscription_payment_key) não está associado com a subscrição (subscription_key). | | 400 | INT000008 | Bad Request | Subscription payment already analyzed. | Pagamento de subscrição já foi analisado. | | 409 | INT000009 | Conflict | Integralization process for (operation_key) already exists. | Já existe um processo de integralização para a operação (operation_key). | | 400 | INT000010 | Bad Request | Subscripted quantity (subscripted_quantity) is bigger than the available quantity (available_quantity). | A quantidade de cotas subscritas (subscripted_quantity) é maior do que a quantidade disponível (available_quantity). | | 400 | INT000011 | Bad Request | Subscription is not waiting payment yet. | Subscrição ainda não está aguardando pagamento. | | 400 | INT000012 | Bad Request | Subscription is in a final state and cannot be canceled. | Subscrição já está em um status final e não pode ser cancelada. | | 400 | INT000013 | Bad Request | Subscription is not waiting payment yet. | Subscrição não está aguardando pagamento ainda. | | 400 | INT000014 | Bad Request | Document not signed yet. | Documento ainda não foi assinado. | | 400 | INT000015 | Bad Request | Integralization canceled. | Integralização cancelada. | | 400 | INT000016 | Bad Request | Integralization cancellation denied. There are integralized quantities. | Cancelamento de integralização negado. Existem cotas integralizadas. | | 400 | INT000017 | Bad Request | Creation of subscriptions for an ongoing operation is not available yet. | Ainda não é possível criar subscrições para operações em andamento. | | 400 | INT000018 | Bad Request | To create a signature with data different from the original, you must define a recalculation method using the recalculation_method field. | Para criar uma subscrição com data diferente da original é preciso definir um método de recálculo através do campo recalculation_method. | --- # Webhook Configuration URL: /en/documentation/escrituracao/configuracao-webhooks The Webhook Configuration API allows managing webhook endpoints to receive real-time notifications about bookkeeping events. Each tenant can have multiple webhook configurations, allowing events to be sent to different destinations. --- ## Data Model ### Webhook Configuration ```json { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "headers": { "Authorization": "Bearer token", "X-Custom-Header": "value" }, "hmac_signature_key": "secret-key" } ``` --- ## Create Webhook Configuration (POST) ### Request ENDPOINT /outgoing_webhook/webhook_configuration METHOD POST ### Request Body ```json { "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "hmac_signature_key": "your-secret-key", "headers": { "Authorization": "Bearer token", "X-Custom-Header": "value" } } ``` ### Request Body Params | Field | Type | Description | | ---------------------- | ------ | --------------------------------------------------------- | | `tenant_key`* | string | Tenant UUID (UUID v4). | | `url`* | string | Destination URL to receive webhooks. | | `hmac_signature_key`* | string | Secret key for HMAC signature of webhooks. | | `headers` | object | Custom headers to include in requests. | --- ### Response STATUS 201 Response Body ```json { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "headers": { "Authorization": "Bearer token", "X-Custom-Header": "value" }, "hmac_signature_key": "your-secret-key" } ``` ### Response Body Params | Field | Type | Description | | ---------------------- | ------ | --------------------------------------------------------- | | `configuration_key` | string | Unique webhook configuration key (UUID v4). | | `tenant_key` | string | Tenant UUID. | | `url` | string | Configured destination URL. | | `headers` | object | Configured custom headers. | | `hmac_signature_key` | string | Secret key for HMAC signature. | --- ## List Webhook Configurations (GET) ### Request ENDPOINT /outgoing_webhook/webhook_configuration METHOD GET ### Query Params | Field | Type | Description | | ------------ | ------- | ---------------------------------------------- | | `tenant_key`* | string | Tenant UUID to filter configurations. | | `page` | integer | Page number (default: 1). | | `page_size` | integer | Items per page (default: 100). | --- ### Response STATUS 200 Response Body ```json { "data": [ { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "headers": { "Authorization": "Bearer token" }, "hmac_signature_key": "your-secret-key" } ], "pagination": { "current_page": 1, "page_size": 100, "total_rows": 15, "total_pages": 1 } } ``` ### Response Body Params | Field | Type | Description | | ---------------------- | ------- | --------------------------------------------------------- | | `data` | array | List of webhook configurations. | | `pagination` | object | **[Pagination Object](#pagination-object)**. | --- ## Get Webhook Configuration by Key (GET) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY METHOD GET ### Path Params | Field | Type | Description | Characters | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | Unique webhook configuration key (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "headers": { "Authorization": "Bearer token" }, "hmac_signature_key": "your-secret-key" } ``` ### Response Body Params | Field | Type | Description | | ---------------------- | ------- | --------------------------------------------------------- | | `configuration_key` | string | Unique webhook configuration key (UUID v4). | | `tenant_key` | string | Tenant UUID. | | `url` | string | Configured destination URL. | | `headers` | object | Configured custom headers. | | `hmac_signature_key` | string | Secret key for HMAC signature. | --- ## Update Webhook Configuration (PUT) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY METHOD PUT ### Path Params | Field | Type | Description | Characters | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | Unique webhook configuration key (UUID v4). | 36 | --- ### Request Body ```json { "url": "https://new-url.com/webhook", "headers": { "New-Header": "new-value" }, "hmac_signature_key": "new-secret-key" } ``` ### Request Body Params | Field | Type | Description | | --------------------- | ------ | --------------------------------------------------------- | | `url` | string | New destination URL to receive webhooks. | | `headers` | object | New custom headers to include in requests. | | `hmac_signature_key` | string | New secret key for HMAC signature of webhooks. | --- ### Response STATUS 200 Response Body ```json { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://new-url.com/webhook", "headers": { "New-Header": "new-value" }, "hmac_signature_key": "new-secret-key" } ``` ### Response Body Params | Field | Type | Description | | ---------------------- | ------- | --------------------------------------------------------- | | `configuration_key` | string | Unique webhook configuration key (UUID v4). | | `tenant_key` | string | Tenant UUID. | | `url` | string | Configured destination URL. | | `headers` | object | Configured custom headers. | | `hmac_signature_key` | string | Secret key for HMAC signature. | --- ## Delete Webhook Configuration (DELETE) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | Unique webhook configuration key (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json {} ``` --- # Register Underlying Asset (Lastro) URL: /en/documentation/escrituracao/emissao-cr/cadastro-lastro This endpoint registers the **underlying asset** (lastro) of a CR operation. The underlying asset represents the credit rights backing the securitization. The asset document is sent in base64 and its structured data accompanies the request. :::info The underlying asset is sent **after the operation is created**, in a separate request. Multiple underlying assets can be registered for the same operation. ::: --- ## **Request** ENDPOINT /cr/operation/ OPERATION-KEY /underlying_asset METHOD POST ### Path Params | Field | Type | Description | Characters | |-----------------|--------|------------------------------------|------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | --- ### Request Body Request Body ```json { "underlying_asset_type": "contract", "underlying_asset_base64": "image_b64", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Request Body Params | Field | Type | Description | Max Characters | |---------------------------|--------|------------------------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | Underlying asset type. | **[underlying_asset_type Enumerators](#underlying_asset_type-enumerators)** | | `underlying_asset_base64` * | string | Underlying asset document in base64. | - | | `underlying_asset_data` * | object | Underlying asset data (free-form). | - | ### underlying_asset_type Enumerators | Enum | Description | |------------|-------------| | `contract` | Contract. | ## **Response** STATUS 201 Response Body ```json { "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23", "underlying_asset_type": "contract", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Response Body Params | Field | Type | Description | |---------------------------|--------|------------------------------------| | `underlying_asset_key` * | string | Unique key of the registered asset.| | `underlying_asset_type` * | string | Underlying asset type. | | `underlying_asset_data` * | object | Underlying asset data. | --- --- # Register CR Operation URL: /en/documentation/escrituracao/emissao-cr/cadastro-operacao This endpoint creates a complete CR operation in a single request. :::info The `financial` object is **required** and must be sent already calculated, as this endpoint does not run the financial simulation. The issuer and its bank account must be previously registered. ::: --- ## **Request** ENDPOINT /cr/create_operation METHOD POST The request body ranges from a **payload with the required fields** (including the financial object) to a **complete payload** that also includes related parties. See both variations below. Payload with the required fields ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "issue_date": "2025-01-20", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] } } ``` Complete payload (with related parties) ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "contract_number": "CR-2025-0001", "issue_date": "2025-01-20", "signature_method": "certifiqi", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] }, "related_party_list": [ { "person_type": "legal", "name": "Garantidora S.A.", "document_number": "12.345.678/0001-90", "trading_name": "Garantidora", "cnae_code": "64.62-0-00", "company_type": "sa", "foundation_date": "2010-05-01", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "postal_code": "01310-100", "city": "São Paulo", "state": "SP", "role_type": "guarantor" }, { "person_type": "natural", "name": "João da Silva", "document_number": "123.456.789-00", "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "solidary_debtor", "is_pep": false } ] } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | | ------------------- | ------- | --------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Unique tenant key. | - | | `issuer_key` * | string | Unique issuer key (previously registered). | - | | `issue_number` * | integer | Issue number. | - | | `issue_series` * | integer | Issue series. | - | | `issue_date` * | string | Operation issue date (format "YYYY-MM-DD"). | - | | `signature_method` | string | Signature method used in the operation. Optional; when omitted, defaults to `certifiqi`. | **[signature_method Enumerators](#signature_method-enumerators)** | | `investors` * | array | List of involved investors. | **investors Object** | | `financial` * | object | Already-calculated operation financial data. | **financial Object** | | `contract_number` | string | Contract number. | - | | `related_party_list` | array | Operation related parties (guarantors, debtors, etc.). | **related_party Object** | ### investors Object | Field | Type | Description | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Unique investor key (previously registered). | | `bank_account` * | object | Investor bank account (**bank_account Object**). | | `subscription_percentage` | number | Subscription percentage. | | `subscription_quantity` | number | Subscribed quantity. | ### bank_account Object | Field | Type | Description | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Bank account number. | | `account_digit` * | string | Bank account digit. | | `account_branch` * | string | Bank account branch. | | `financial_institution_code_number` | string | Financial institution code. | | `financial_institution_ispb` * | string | Financial institution ISPB code. | | `account_type` * | string | Account type (`checking`, `savings`, `salary`, `payment`). | ### financial Object | Field | Type | Description | | --------------------------- | ------- | -------------------------------------------- | | `financial_base_date` * | string | Financial base date (format "YYYY-MM-DD"). | | `interest_type` * | string | Interest type. | | `issue_amount` | number | Total issued amount. | | `issue_quantity` | integer | Quantity of issued units. | | `unit_price` | number | Unit price of the issuance. | | `released_amount` | number | Net released amount. | | `cet` / `annual_cet` | number | Total Effective Cost (monthly and annual), in percentage. | | `number_of_installments` * | integer | Number of installments. | | `prefixed_interest_rate` * | object | Prefixed interest rate. | | `fine_delay_rate` | object | Delay fine rate. | | `contract_fine_rate` | number | Contractual fine in percentage. | | `fees` | array | List of fees. | | `installments` | array | List of already-calculated installments. | ### related_party Object Each item in `related_party_list` represents a party involved in the operation. | Field | Type | Description | | ----------------- | ------- | ------------------------------------------------------------ | | `person_type` * | string | Person type (`natural` for individuals, `legal` for companies). | | `name` * | string | Related party name. | | `document_number` * | string | CPF (individual) or CNPJ (company). | | `role_type` * | string | Party role in the operation. **[role_type Enumerators](#role_type-enumerators)** | | `street` * | string | Street. | | `number` * | string | Address number. | | `neighborhood` | string | Neighborhood. | | `postal_code` * | string | Postal code (format "00000-000"). | | `city` * | string | City. | | `state` * | string | State (2 letters). | | `complement` | string | Address complement. | | `is_pep` | boolean | (Individual) Whether the person is a Politically Exposed Person. | | `marital_status` | string | (Individual) Marital status. | | `property_system` | string | (Individual) Property regime. | | `birthdate` | string | (Individual) Date of birth. | | `mother_name` | string | (Individual) Mother's name. | | `occupation` | string | (Individual) Occupation. | | `trading_name` | string | (Company) Trading name. | | `cnae_code` | string | (Company) CNAE code (format "00.00-0-00"). | | `company_type` | string | (Company) Company type. | | `foundation_date` | string | (Company) Foundation date. | :::warning Attention Required fields vary by `person_type`: - **Individual (`natural`)**: in addition to the common fields, `is_pep` is required. - **Company (`legal`)**: in addition to the common fields, `trading_name`, `cnae_code`, `company_type` and `foundation_date` are required. ::: ### role_type Enumerators | Enum | Description | |------|-------------| | `issuer` | Issuer. | | `investor` | Investor. | | `cosigner` | Co-obligor. | | `fiduciary_debtor` | Fiduciary debtor. | | `solidary_debtor` | Joint debtor. | | `guarantor` | Guarantor (aval). | | `bonafide_depositary` | Bona fide depositary. | | `intervening_guarantor` | Intervening guarantor. | | `intervening_consentor` | Intervening consentor. | | `intervening_discharger` | Intervening discharger. | | `assignor` | Assignor. | | `endorser` | Endorser. | | `consulting` | Consulting. | | `fund_administrator` | Fund administrator. | | `fund_representative` | Fund representative. | | `company_representative` | Company representative. | | `attestant` | Attestant. | | `debtor` | Debtor. | | `bestowal` | Grantor. | | `manager` | Manager. | :::tip Collateral and underlying assets are sent through a **separate endpoint**, after the operation is created. See the **Register underlying asset** page in this section. ::: ### signature_method Enumerators | Enum | Description | |------|-------------| | `certifiqi` | Default value. The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). | | `qi_sign` | The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). Also allows querying the operation's signers. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "finished", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "issue_number": 10, "issue_series": 1, "related_party_list": [ ... ], "financial": { ... } } ``` The response returns the complete JSON of the created operation, including `operation_key`, the investor and related-party lists, and the calculated financial object. --- # Send Document URL: /en/documentation/escrituracao/emissao-cr/envio-documento This endpoint **uploads a document** and returns the `document_key` that identifies it. This `document_key` is used to reference documents in other operation endpoints whenever the key of a previously uploaded document is required. --- ## **Request** ENDPOINT /cr/upload METHOD POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Field | Type | Description | Required | |-------------------|--------|------------------------------------------|----------| | `document_base64` * | string | Base64 encoded content of the document. | Yes | | `document_name` | string | Document name. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |----------------|--------|----------------------------------------|----------------| | `document_key` * | string | Unique key of the uploaded document (UUID v4). | 36 | --- --- # Send Operation External Document URL: /en/documentation/escrituracao/emissao-cr/envio-documento-externo This endpoint allows sending externally signed documents to the bookkeeping system by sending a base64 that will be analyzed and approved by the bookkeeper. :::warning Warning This endpoint should only be used for operations that use the **client_side** signature type or for sending the approval minutes for SA or Cooperative companies. For the flow via QI Sign or Certifiqi, contracts are generated normally. ::: --- ## Send Signed Document (POST) ### Request ENDPOINT /cr/operation/ OPERATION-KEY /upload_signed_document METHOD POST ### Path Params | Field | Type | Description | Characters | |-----------------|--------|-------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | Field | Type | Description | Max Characters | |---------------------|--------|----------------------------|------------------------------------------------------------| | `contract_type` * | string | Type of signed document. | **[contract_type Enumerators](#contract_type-enumerators)** | | `contract_base64` * | string | Signed document in base64. | - | ### contract_type Enumerators | Enum | Description | |---------------------|--------------------------------------------| | `securitization_term` | CR securitization term. | | `adhesion_term` | CR adhesion term. | | `sa_minute` | CR issuance approval minutes for **SA** company. | | `ltda_minute` | CR issuance approval minutes for **LTDA** company. | | `cop_minute` | CR issuance approval minutes for **Cooperative**. | ### Response The response body is a complete JSON of the updated operation. --- --- # Register Underlying Asset (Lastro) URL: /en/documentation/escrituracao/emissao-cra/cadastro-lastro This endpoint registers the **underlying asset** (lastro) of a CRA operation. The underlying asset represents the credit rights backing the securitization. The asset document is sent in base64 and its structured data accompanies the request. :::info The underlying asset is sent **after the operation is created**, in a separate request. Multiple underlying assets can be registered for the same operation. ::: --- ## **Request** ENDPOINT /cra/operation/ OPERATION-KEY /underlying_asset METHOD POST ### Path Params | Field | Type | Description | Characters | |-----------------|--------|------------------------------------|------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | --- ### Request Body Request Body ```json { "underlying_asset_type": "contract", "underlying_asset_base64": "image_b64", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Request Body Params | Field | Type | Description | Max Characters | |---------------------------|--------|------------------------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | Underlying asset type. | **[underlying_asset_type Enumerators](#underlying_asset_type-enumerators)** | | `underlying_asset_base64` * | string | Underlying asset document in base64. | - | | `underlying_asset_data` * | object | Underlying asset data (free-form). | - | ### underlying_asset_type Enumerators | Enum | Description | |------------|-------------| | `contract` | Contract. | ## **Response** STATUS 201 Response Body ```json { "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23", "underlying_asset_type": "contract", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Response Body Params | Field | Type | Description | |---------------------------|--------|------------------------------------| | `underlying_asset_key` * | string | Unique key of the registered asset.| | `underlying_asset_type` * | string | Underlying asset type. | | `underlying_asset_data` * | object | Underlying asset data. | --- --- # Register CRA Operation URL: /en/documentation/escrituracao/emissao-cra/cadastro-operacao This endpoint creates a complete CRA operation in a single request. :::info The `financial` object is **required** and must be sent already calculated, as this endpoint does not run the financial simulation. The issuer and its bank account must be previously registered. ::: --- ## **Request** ENDPOINT /cra/create_operation METHOD POST The request body ranges from a **payload with the required fields** (including the financial object) to a **complete payload** that also includes related parties. See both variations below. Payload with the required fields ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "issue_date": "2025-01-20", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] } } ``` Complete payload (with related parties) ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "contract_number": "CRA-2025-0001", "issue_date": "2025-01-20", "signature_method": "certifiqi", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] }, "related_party_list": [ { "person_type": "legal", "name": "Garantidora S.A.", "document_number": "12.345.678/0001-90", "trading_name": "Garantidora", "cnae_code": "64.62-0-00", "company_type": "sa", "foundation_date": "2010-05-01", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "postal_code": "01310-100", "city": "São Paulo", "state": "SP", "role_type": "guarantor" }, { "person_type": "natural", "name": "João da Silva", "document_number": "123.456.789-00", "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "solidary_debtor", "is_pep": false } ] } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | | ------------------- | ------- | --------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Unique tenant key. | - | | `issuer_key` * | string | Unique issuer key (previously registered). | - | | `issue_number` * | integer | Issue number. | - | | `issue_series` * | integer | Issue series. | - | | `issue_date` * | string | Operation issue date (format "YYYY-MM-DD"). | - | | `signature_method` | string | Signature method used in the operation. Optional; when omitted, defaults to `certifiqi`. | **[signature_method Enumerators](#signature_method-enumerators)** | | `investors` * | array | List of involved investors. | **investors Object** | | `financial` * | object | Already-calculated operation financial data. | **financial Object** | | `contract_number` | string | Contract number. | - | | `related_party_list` | array | Operation related parties (guarantors, debtors, etc.). | **related_party Object** | ### investors Object | Field | Type | Description | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Unique investor key (previously registered). | | `bank_account` * | object | Investor bank account (**bank_account Object**). | | `subscription_percentage` | number | Subscription percentage. | | `subscription_quantity` | number | Subscribed quantity. | ### bank_account Object | Field | Type | Description | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Bank account number. | | `account_digit` * | string | Bank account digit. | | `account_branch` * | string | Bank account branch. | | `financial_institution_code_number` | string | Financial institution code. | | `financial_institution_ispb` * | string | Financial institution ISPB code. | | `account_type` * | string | Account type (`checking`, `savings`, `salary`, `payment`). | ### financial Object | Field | Type | Description | | --------------------------- | ------- | -------------------------------------------- | | `financial_base_date` * | string | Financial base date (format "YYYY-MM-DD"). | | `interest_type` * | string | Interest type. | | `issue_amount` | number | Total issued amount. | | `issue_quantity` | integer | Quantity of issued units. | | `unit_price` | number | Unit price of the issuance. | | `released_amount` | number | Net released amount. | | `cet` / `annual_cet` | number | Total Effective Cost (monthly and annual), in percentage. | | `number_of_installments` * | integer | Number of installments. | | `prefixed_interest_rate` * | object | Prefixed interest rate. | | `fine_delay_rate` | object | Delay fine rate. | | `contract_fine_rate` | number | Contractual fine in percentage. | | `fees` | array | List of fees. | | `installments` | array | List of already-calculated installments. | ### related_party Object Each item in `related_party_list` represents a party involved in the operation. | Field | Type | Description | | ----------------- | ------- | ------------------------------------------------------------ | | `person_type` * | string | Person type (`natural` for individuals, `legal` for companies). | | `name` * | string | Related party name. | | `document_number` * | string | CPF (individual) or CNPJ (company). | | `role_type` * | string | Party role in the operation. **[role_type Enumerators](#role_type-enumerators)** | | `street` * | string | Street. | | `number` * | string | Address number. | | `neighborhood` | string | Neighborhood. | | `postal_code` * | string | Postal code (format "00000-000"). | | `city` * | string | City. | | `state` * | string | State (2 letters). | | `complement` | string | Address complement. | | `is_pep` | boolean | (Individual) Whether the person is a Politically Exposed Person. | | `marital_status` | string | (Individual) Marital status. | | `property_system` | string | (Individual) Property regime. | | `birthdate` | string | (Individual) Date of birth. | | `mother_name` | string | (Individual) Mother's name. | | `occupation` | string | (Individual) Occupation. | | `trading_name` | string | (Company) Trading name. | | `cnae_code` | string | (Company) CNAE code (format "00.00-0-00"). | | `company_type` | string | (Company) Company type. | | `foundation_date` | string | (Company) Foundation date. | :::warning Attention Required fields vary by `person_type`: - **Individual (`natural`)**: in addition to the common fields, `is_pep` is required. - **Company (`legal`)**: in addition to the common fields, `trading_name`, `cnae_code`, `company_type` and `foundation_date` are required. ::: ### role_type Enumerators | Enum | Description | |------|-------------| | `issuer` | Issuer. | | `investor` | Investor. | | `cosigner` | Co-obligor. | | `fiduciary_debtor` | Fiduciary debtor. | | `solidary_debtor` | Joint debtor. | | `guarantor` | Guarantor (aval). | | `bonafide_depositary` | Bona fide depositary. | | `intervening_guarantor` | Intervening guarantor. | | `intervening_consentor` | Intervening consentor. | | `intervening_discharger` | Intervening discharger. | | `assignor` | Assignor. | | `endorser` | Endorser. | | `consulting` | Consulting. | | `fund_administrator` | Fund administrator. | | `fund_representative` | Fund representative. | | `company_representative` | Company representative. | | `attestant` | Attestant. | | `debtor` | Debtor. | | `bestowal` | Grantor. | | `manager` | Manager. | :::tip Collateral and underlying assets are sent through a **separate endpoint**, after the operation is created. See the **Register underlying asset** page in this section. ::: ### signature_method Enumerators | Enum | Description | |------|-------------| | `certifiqi` | Default value. The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). | | `qi_sign` | The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). Also allows querying the operation's signers. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "finished", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "issue_number": 10, "issue_series": 1, "related_party_list": [ ... ], "financial": { ... } } ``` The response returns the complete JSON of the created operation, including `operation_key`, the investor and related-party lists, and the calculated financial object. --- # Send Document URL: /en/documentation/escrituracao/emissao-cra/envio-documento This endpoint **uploads a document** and returns the `document_key` that identifies it. This `document_key` is used to reference documents in other operation endpoints whenever the key of a previously uploaded document is required. --- ## **Request** ENDPOINT /cra/upload METHOD POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Field | Type | Description | Required | |-------------------|--------|------------------------------------------|----------| | `document_base64` * | string | Base64 encoded content of the document. | Yes | | `document_name` | string | Document name. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |----------------|--------|----------------------------------------|----------------| | `document_key` * | string | Unique key of the uploaded document (UUID v4). | 36 | --- --- # Send Operation External Document URL: /en/documentation/escrituracao/emissao-cra/envio-documento-externo This endpoint allows sending externally signed documents to the bookkeeping system by sending a base64 that will be analyzed and approved by the bookkeeper. :::warning Warning This endpoint should only be used for operations that use the **client_side** signature type or for sending the approval minutes for SA or Cooperative companies. For the flow via QI Sign or Certifiqi, contracts are generated normally. ::: --- ## Send Signed Document (POST) ### Request ENDPOINT /cra/operation/ OPERATION-KEY /upload_signed_document METHOD POST ### Path Params | Field | Type | Description | Characters | |-----------------|--------|-------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | Field | Type | Description | Max Characters | |---------------------|--------|----------------------------|------------------------------------------------------------| | `contract_type` * | string | Type of signed document. | **[contract_type Enumerators](#contract_type-enumerators)** | | `contract_base64` * | string | Signed document in base64. | - | ### contract_type Enumerators | Enum | Description | |---------------------|--------------------------------------------| | `securitization_term` | CRA securitization term. | | `adhesion_term` | CRA adhesion term. | | `sa_minute` | CRA issuance approval minutes for **SA** company. | | `ltda_minute` | CRA issuance approval minutes for **LTDA** company. | | `cop_minute` | CRA issuance approval minutes for **Cooperative**. | ### Response The response body is a complete JSON of the updated operation. --- --- # Register Underlying Asset (Lastro) URL: /en/documentation/escrituracao/emissao-cri/cadastro-lastro This endpoint registers the **underlying asset** (lastro) of a CRI operation. The underlying asset represents the credit rights backing the securitization. The asset document is sent in base64 and its structured data accompanies the request. :::info The underlying asset is sent **after the operation is created**, in a separate request. Multiple underlying assets can be registered for the same operation. ::: --- ## **Request** ENDPOINT /cri/operation/ OPERATION-KEY /underlying_asset METHOD POST ### Path Params | Field | Type | Description | Characters | |-----------------|--------|------------------------------------|------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | --- ### Request Body Request Body ```json { "underlying_asset_type": "contract", "underlying_asset_base64": "image_b64", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Request Body Params | Field | Type | Description | Max Characters | |---------------------------|--------|------------------------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | Underlying asset type. | **[underlying_asset_type Enumerators](#underlying_asset_type-enumerators)** | | `underlying_asset_base64` * | string | Underlying asset document in base64. | - | | `underlying_asset_data` * | object | Underlying asset data (free-form). | - | ### underlying_asset_type Enumerators | Enum | Description | |------------|-------------| | `contract` | Contract. | ## **Response** STATUS 201 Response Body ```json { "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23", "underlying_asset_type": "contract", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Response Body Params | Field | Type | Description | |---------------------------|--------|------------------------------------| | `underlying_asset_key` * | string | Unique key of the registered asset.| | `underlying_asset_type` * | string | Underlying asset type. | | `underlying_asset_data` * | object | Underlying asset data. | --- --- # Register CRI Operation URL: /en/documentation/escrituracao/emissao-cri/cadastro-operacao This endpoint creates a complete CRI operation in a single request. :::info The `financial` object is **required** and must be sent already calculated, as this endpoint does not run the financial simulation. The issuer and its bank account must be previously registered. ::: --- ## **Request** ENDPOINT /cri/create_operation METHOD POST The request body ranges from a **payload with the required fields** (including the financial object) to a **complete payload** that also includes related parties. See both variations below. Payload with the required fields ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "issue_date": "2025-01-20", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] } } ``` Complete payload (with related parties) ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "contract_number": "CRI-2025-0001", "issue_date": "2025-01-20", "signature_method": "certifiqi", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] }, "related_party_list": [ { "person_type": "legal", "name": "Garantidora S.A.", "document_number": "12.345.678/0001-90", "trading_name": "Garantidora", "cnae_code": "64.62-0-00", "company_type": "sa", "foundation_date": "2010-05-01", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "postal_code": "01310-100", "city": "São Paulo", "state": "SP", "role_type": "guarantor" }, { "person_type": "natural", "name": "João da Silva", "document_number": "123.456.789-00", "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "solidary_debtor", "is_pep": false } ] } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | | ------------------- | ------- | --------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Unique tenant key. | - | | `issuer_key` * | string | Unique issuer key (previously registered). | - | | `issue_number` * | integer | Issue number. | - | | `issue_series` * | integer | Issue series. | - | | `issue_date` * | string | Operation issue date (format "YYYY-MM-DD"). | - | | `signature_method` | string | Signature method used in the operation. Optional; when omitted, defaults to `certifiqi`. | **[signature_method Enumerators](#signature_method-enumerators)** | | `investors` * | array | List of involved investors. | **investors Object** | | `financial` * | object | Already-calculated operation financial data. | **financial Object** | | `contract_number` | string | Contract number. | - | | `related_party_list` | array | Operation related parties (guarantors, debtors, etc.). | **related_party Object** | ### investors Object | Field | Type | Description | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Unique investor key (previously registered). | | `bank_account` * | object | Investor bank account (**bank_account Object**). | | `subscription_percentage` | number | Subscription percentage. | | `subscription_quantity` | number | Subscribed quantity. | ### bank_account Object | Field | Type | Description | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Bank account number. | | `account_digit` * | string | Bank account digit. | | `account_branch` * | string | Bank account branch. | | `financial_institution_code_number` | string | Financial institution code. | | `financial_institution_ispb` * | string | Financial institution ISPB code. | | `account_type` * | string | Account type (`checking`, `savings`, `salary`, `payment`). | ### financial Object | Field | Type | Description | | --------------------------- | ------- | -------------------------------------------- | | `financial_base_date` * | string | Financial base date (format "YYYY-MM-DD"). | | `interest_type` * | string | Interest type. | | `issue_amount` | number | Total issued amount. | | `issue_quantity` | integer | Quantity of issued units. | | `unit_price` | number | Unit price of the issuance. | | `released_amount` | number | Net released amount. | | `cet` / `annual_cet` | number | Total Effective Cost (monthly and annual), in percentage. | | `number_of_installments` * | integer | Number of installments. | | `prefixed_interest_rate` * | object | Prefixed interest rate. | | `fine_delay_rate` | object | Delay fine rate. | | `contract_fine_rate` | number | Contractual fine in percentage. | | `fees` | array | List of fees. | | `installments` | array | List of already-calculated installments. | ### related_party Object Each item in `related_party_list` represents a party involved in the operation. | Field | Type | Description | | ----------------- | ------- | ------------------------------------------------------------ | | `person_type` * | string | Person type (`natural` for individuals, `legal` for companies). | | `name` * | string | Related party name. | | `document_number` * | string | CPF (individual) or CNPJ (company). | | `role_type` * | string | Party role in the operation. **[role_type Enumerators](#role_type-enumerators)** | | `street` * | string | Street. | | `number` * | string | Address number. | | `neighborhood` | string | Neighborhood. | | `postal_code` * | string | Postal code (format "00000-000"). | | `city` * | string | City. | | `state` * | string | State (2 letters). | | `complement` | string | Address complement. | | `is_pep` | boolean | (Individual) Whether the person is a Politically Exposed Person. | | `marital_status` | string | (Individual) Marital status. | | `property_system` | string | (Individual) Property regime. | | `birthdate` | string | (Individual) Date of birth. | | `mother_name` | string | (Individual) Mother's name. | | `occupation` | string | (Individual) Occupation. | | `trading_name` | string | (Company) Trading name. | | `cnae_code` | string | (Company) CNAE code (format "00.00-0-00"). | | `company_type` | string | (Company) Company type. | | `foundation_date` | string | (Company) Foundation date. | :::warning Attention Required fields vary by `person_type`: - **Individual (`natural`)**: in addition to the common fields, `is_pep` is required. - **Company (`legal`)**: in addition to the common fields, `trading_name`, `cnae_code`, `company_type` and `foundation_date` are required. ::: ### role_type Enumerators | Enum | Description | |------|-------------| | `issuer` | Issuer. | | `investor` | Investor. | | `cosigner` | Co-obligor. | | `fiduciary_debtor` | Fiduciary debtor. | | `solidary_debtor` | Joint debtor. | | `guarantor` | Guarantor (aval). | | `bonafide_depositary` | Bona fide depositary. | | `intervening_guarantor` | Intervening guarantor. | | `intervening_consentor` | Intervening consentor. | | `intervening_discharger` | Intervening discharger. | | `assignor` | Assignor. | | `endorser` | Endorser. | | `consulting` | Consulting. | | `fund_administrator` | Fund administrator. | | `fund_representative` | Fund representative. | | `company_representative` | Company representative. | | `attestant` | Attestant. | | `debtor` | Debtor. | | `bestowal` | Grantor. | | `manager` | Manager. | :::tip Collateral and underlying assets are sent through a **separate endpoint**, after the operation is created. See the **Register underlying asset** page in this section. ::: ### signature_method Enumerators | Enum | Description | |------|-------------| | `certifiqi` | Default value. The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). | | `qi_sign` | The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). Also allows querying the operation's signers. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "finished", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "issue_number": 10, "issue_series": 1, "related_party_list": [ ... ], "financial": { ... } } ``` The response returns the complete JSON of the created operation, including `operation_key`, the investor and related-party lists, and the calculated financial object. --- # Send Document URL: /en/documentation/escrituracao/emissao-cri/envio-documento This endpoint **uploads a document** and returns the `document_key` that identifies it. This `document_key` is used to reference documents in other operation endpoints whenever the key of a previously uploaded document is required. --- ## **Request** ENDPOINT /cri/upload METHOD POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Field | Type | Description | Required | |-------------------|--------|------------------------------------------|----------| | `document_base64` * | string | Base64 encoded content of the document. | Yes | | `document_name` | string | Document name. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |----------------|--------|----------------------------------------|----------------| | `document_key` * | string | Unique key of the uploaded document (UUID v4). | 36 | --- --- # Send Operation External Document URL: /en/documentation/escrituracao/emissao-cri/envio-documento-externo This endpoint allows sending externally signed documents to the bookkeeping system by sending a base64 that will be analyzed and approved by the bookkeeper. :::warning Warning This endpoint should only be used for operations that use the **client_side** signature type or for sending the approval minutes for SA or Cooperative companies. For the flow via QI Sign or Certifiqi, contracts are generated normally. ::: --- ## Send Signed Document (POST) ### Request ENDPOINT /cri/operation/ OPERATION-KEY /upload_signed_document METHOD POST ### Path Params | Field | Type | Description | Characters | |-----------------|--------|-------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | Field | Type | Description | Max Characters | |---------------------|--------|----------------------------|------------------------------------------------------------| | `contract_type` * | string | Type of signed document. | **[contract_type Enumerators](#contract_type-enumerators)** | | `contract_base64` * | string | Signed document in base64. | - | ### contract_type Enumerators | Enum | Description | |---------------------|--------------------------------------------| | `securitization_term` | CRI securitization term. | | `adhesion_term` | CRI adhesion term. | | `sa_minute` | CRI issuance approval minutes for **SA** company. | | `ltda_minute` | CRI issuance approval minutes for **LTDA** company. | | `cop_minute` | CRI issuance approval minutes for **Cooperative**. | ### Response The response body is a complete JSON of the updated operation. --- --- # Operation disbursement account update. URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso This endpoint allows updating the disbursement account of an operation. --- ## **Operation disbursement account update (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /issuer_bank_account METHOD PUT ### **Path Params** | Field | Type | Description | Max Characters | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | Request Body ```json { "issuer_bank_account": { "account_number": "4464541", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ``` ### Request Body Params ### **issuer_bank_account object** | Field | Type | Description | | --------------------------------------- | ------ | ------------------------------------------ | | `account_number` * | string | Bank account number. | | `account_digit` * | string | Bank account digit. | | `account_branch` * | string | Bank account branch. | | `financial_institution_code_number` * | string | Financial institution code. | | `financial_institution_ispb` * | string | Financial institution ISPB code. | | `account_type` * | string | Account type (`checking`, `savings`). | ## **Response** STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74", "operation_type": "commercial_paper", "operation_status": "issued", "backoffice_analysis_status": "approved", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "issuer_onboarding_approved": true, "issue_number": 1, "issue_series": 1, "contract_number": "0000000001", "issue_date": "2025-02-03", "financial_base_date": "2025-02-03", "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9", "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8", "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f", "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c", "envelope_signature_status": "signed", "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b", "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a", "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files", "financial": { "financial_base_date": "2025-02-03", "issue_quantity": 1000000, "unit_price": 1.0, "issue_amount": 1000000.0, "released_amount": 1000000.0, "cet": 5.0, "annual_cet": 79.59, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0016053474, "annual_rate": 0.795856326, "monthly_rate": 0.05, "interest_base": "calendar_days_365" }, "fine_delay_rate": { "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "financial_index": null, "post_fixed_interest_rate": null, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 20000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 50000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_number": 1, "workdays": 20, "calendar_days": 30, "principal_amortization_unit_price": 0.18122484, "principal_amortization_amount": 181224.84138231, "interest_amount": 49298.45861769, "amount": 230523.3, "due_principal": 1000000.0, "due_interest": 0.0, "due_date": "2025-03-05", "has_interest": true }, { "installment_number": 2, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.19153595, "principal_amortization_amount": 191535.95353305, "interest_amount": 38987.34646695, "amount": 230523.3, "due_principal": 818775.15861769, "due_interest": 0.0, "due_date": "2025-04-03", "has_interest": true }, { "installment_number": 3, "workdays": 19, "calendar_days": 32, "principal_amortization_unit_price": 0.19748652, "principal_amortization_amount": 197486.52331007, "interest_amount": 33036.77668993, "amount": 230523.3, "due_principal": 627239.20508464, "due_interest": 0.0, "due_date": "2025-05-05", "has_interest": true }, { "installment_number": 4, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.21005991, "principal_amortization_amount": 210059.90840452, "interest_amount": 20463.39159548, "amount": 230523.3, "due_principal": 429752.68177457, "due_interest": 0.0, "due_date": "2025-06-03", "has_interest": true }, { "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.21969277, "principal_amortization_amount": 219692.77337005, "interest_amount": 10830.52662995, "amount": 230523.3, "due_principal": 219692.77337005, "due_interest": 0.0, "due_date": "2025-07-03", "has_interest": true } ] }, "tags": [], "investor_list": [ { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "subscription_percentage": 100.0, "subscription_quantity": 1000000, "investor_onboarding_approved": true, "bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "updated_at": null } ], "related_party_list": [ { "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c", "name": "Blue Logic", "document_number": "97.923.586/0001-06", "role_type": "issuer", "is_active": true, "updated_at": null, "trading_name": "Blue Logic", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5511988887777", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5516982399722", "document_number": "123.456.789-00", "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414" } ] }, { "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30", "name": "Ultimate Cascade", "document_number": "31.424.651/0001-32", "role_type": "investor", "is_active": true, "updated_at": null, "trading_name": "Ultimate Cascade", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5516982399722", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5511988887777", "document_number": "123.456.789-00", "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ] } ], "collateral_list": [ { "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "collateral_type": "fiduciary_alienation_property" } ], "metadata_list": [ { "metadata_key": "convenio", "metadata_value": "12398129038" } ], "signature_method": "qi_sign" } ``` ### **Response Body Params** | Field | Type | Description | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Unique tenant key. | | `operation_key` * | string | Unique operation key. | | `operation_status` * | string | Operation status. | | `issuer_key` * | string | Unique issuer key. | | `issuer_name` * | string | Issuer name. | | `issuer_document_number` * | string | Issuer document number. | | `financial` * | object | **[financial object](#financial-object-response)** | ### financial object response | Field | Type | Description | Max Characters | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Operation financial base date (format "YYYY-MM-DD"). | - | | `issue_amount` * | number | Total operation issued amount. | - | | `released_amount` * | number | Net amount released in the operation. | - | | `issue_quantity` * | integer | Total quantity of units issued. | - | | `unit_price` * | number | Unit price of the issuance. | - | | `cet` * | number | Total Effective Cost (CET) percentage. | - | | `annual_cet` * | number | Annual CET percentage. | - | | `number_of_installments` * | integer | Total number of installments. | - | | `prefixed_interest_rate` * | object | Object containing prefixed interest rate details. | **[prefixed_interest_rate object](#prefixed_interest_rate-object)** | | `fees` | array | List of fees associated with the operation. | **[fees object](#fees-object)** | | `installments` | array | List of installment details generated in the operation. | **[installments object](#installments-object)** | | `fine_delay_rate` * | object | Object containing late payment penalty details. | **[fine_delay_rate object](#fine_delay_rate-object)** | | `contract_fine_rate` * | number | Contract penalty applied as percentage. | - | ### prefixed_interest_rate object | Field | Type | Description | Max Characters | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Interest calculation basis. | **[interest_base enumerators](#interest_base-enumerators)** | | `monthly_rate` * | number | Applied monthly interest rate. | - | | `daily_rate` * | number | Applied daily interest rate. | - | | `annual_rate` * | number | Applied annual interest rate. | - | ### fees object | Field | Type | Description | Max Characters | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Fee percentage amount. | - | | `fee_amount` * | number | Monetary value corresponding to the fee. | - | | `amount_type` * | string | Fee amount type. | **[amount_type enumerators](#amount_type-enumerators)** | | `fee_type` * | string | Fee type. | **[fee_type enumerators](#fee_type-enumerators)** | | `type` * | string | Fee recipient. | **[fee_recipient enumerators](#fee_recipient-enumerators)** | ### installments object | Field | Type | Description | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Installment number. | | `workdays` * | integer | Business days until installment due date. | | `calendar_days` * | integer | Calendar days until installment due date. | | `principal_amortization_amount` * | number | Principal amortized amount. | | `principal_amortization_unit_price` * | number | Amortized amount per unit. | | `interest_amount` * | number | Interest amount applied to the installment. | | `amount` * | number | Total installment amount. | | `due_date` * | string | Installment due date (format "YYYY-MM-DD"). | --- # Financial Data Update in Operation URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros This endpoint allows updating the financial data in an operation, following the financial object pattern, which is also sent in the simulation endpoint. --- ## **Financial Data Update in Operation (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /financial METHOD PUT ### **Path Params** | Field | Type | Description | Max Characters | |-------------------|--------|-------------------------------------------------|----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | Request Body ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-02-03", "released_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ] } ``` ### Request Body Params | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|----------------| | `interest_type` * | string | Type of interest applied. | **[interest_type Enumerators](#interest_type-enumerators)** | | `financial_base_date` * | string | Operation base date (format "YYYY-MM-DD"). | - | | `released_amount` * | number | Total amount released in the operation. | - | | `number_of_installments` * | integer | Total number of installments. | - | | `prefixed_interest_rate` * | object | Object containing prefixed interest rate details. | **[prefixed_interest_rate Object](#prefixed_interest_rate-object)** | | `fine_delay_rate` * | object | Object containing delay penalty details. | **[fine_delay_rate Object](#fine_delay_rate-object)** | | `contract_fine_rate` * | number | Contract penalty applied as percentage. | - | | `fees` | array | List of fees associated with the operation. | **[fees Object](#fees-object)** | ### prefixed_interest_rate Object | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|----------------| | `interest_base` * | string | Calculation base for interest. | **[interest_base Enumerators](#interest_base-enumerators)** | | `monthly_rate` * | number | Monthly interest rate applied. | - | ### fine_delay_rate Object | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|----------------| | `interest_base` * | string | Base for penalty calculation. | **[interest_base Enumerators](#interest_base-enumerators)** | | `monthly_rate` * | number | Monthly penalty rate. | - | ### fees Object | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|----------------| | `amount` * | number | Fee amount applied. | - | | `amount_type` * | string | Type of fee amount. | **[amount_type Enumerators](#amount_type-enumerators)** | | `fee_type` * | string | Type of fee. | **[fee_type Enumerators](#fee_type-enumerators)** | | `type` * | string | Fee recipient. | **[fee_recipient Enumerators](#fee_recipient-enumerators)** | ### interest_type Enumerators | Enum | Description | |--------------------|----------------------------------------------| | `pre_price` | Prefixed interest in Price model. | | `pre_price_days` | Prefixed interest in Price model by calendar days. | | `pre_sac` | Prefixed interest in SAC model. | | `post_sac` | Post-fixed interest in SAC model. | ### interest_base Enumerators | Enum | Description | |--------------------|----------------------------------------------| | `calendar_days` | Calendar days base. | | `calendar_days_365`| 365 calendar days base. | | `workdays` | Business days base. | ### amount_type Enumerators | Enum | Description | |-------------|-------------------------------| | `percentage` | Percentage value. | | `absolute` | Absolute currency value. | ### fee_type Enumerators | Enum | Description | |-------------------------------------|---------------------------------------------| | `bookkeeping_fee` | Financed bookkeeping fee. | | `structuring_fee` | Financed structuring fee. | ### fee_recipient Enumerators | Enum | Description | |-----------|-----------------------------------------------------------| | `internal` | Fee paid to the bookkeeper. | | `external` | Rebate paid to the originator. | ## **Response** STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74", "operation_type": "commercial_paper", "operation_status": "issued", "backoffice_analysis_status": "approved", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "issuer_onboarding_approved": true, "issue_number": 1, "issue_series": 1, "contract_number": "0000000001", "issue_date": "2025-02-03", "financial_base_date": "2025-02-03", "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9", "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8", "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f", "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c", "envelope_signature_status": "signed", "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b", "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a", "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files", "financial": { "financial_base_date": "2025-02-03", "issue_quantity": 1000000, "unit_price": 1.0, "issue_amount": 1000000.0, "released_amount": 1000000.0, "cet": 5.0, "annual_cet": 79.59, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0016053474, "annual_rate": 0.795856326, "monthly_rate": 0.05, "interest_base": "calendar_days_365" }, "fine_delay_rate": { "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "financial_index": null, "post_fixed_interest_rate": null, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 20000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 50000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_number": 1, "workdays": 20, "calendar_days": 30, "principal_amortization_unit_price": 0.18122484, "principal_amortization_amount": 181224.84138231, "interest_amount": 49298.45861769, "amount": 230523.3, "due_principal": 1000000.0, "due_interest": 0.0, "due_date": "2025-03-05", "has_interest": true }, { "installment_number": 2, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.19153595, "principal_amortization_amount": 191535.95353305, "interest_amount": 38987.34646695, "amount": 230523.3, "due_principal": 818775.15861769, "due_interest": 0.0, "due_date": "2025-04-03", "has_interest": true }, { "installment_number": 3, "workdays": 19, "calendar_days": 32, "principal_amortization_unit_price": 0.19748652, "principal_amortization_amount": 197486.52331007, "interest_amount": 33036.77668993, "amount": 230523.3, "due_principal": 627239.20508464, "due_interest": 0.0, "due_date": "2025-05-05", "has_interest": true }, { "installment_number": 4, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.21005991, "principal_amortization_amount": 210059.90840452, "interest_amount": 20463.39159548, "amount": 230523.3, "due_principal": 429752.68177457, "due_interest": 0.0, "due_date": "2025-06-03", "has_interest": true }, { "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.21969277, "principal_amortization_amount": 219692.77337005, "interest_amount": 10830.52662995, "amount": 230523.3, "due_principal": 219692.77337005, "due_interest": 0.0, "due_date": "2025-07-03", "has_interest": true } ] }, "tags": [], "investor_list": [ { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "subscription_percentage": 100.0, "subscription_quantity": 1000000, "investor_onboarding_approved": true, "bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "updated_at": null } ], "related_party_list": [ { "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c", "name": "Blue Logic", "document_number": "97.923.586/0001-06", "role_type": "issuer", "is_active": true, "updated_at": null, "trading_name": "Blue Logic", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5511988887777", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5516982399722", "document_number": "123.456.789-00", "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414" } ] }, { "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30", "name": "Ultimate Cascade", "document_number": "31.424.651/0001-32", "role_type": "investor", "is_active": true, "updated_at": null, "trading_name": "Ultimate Cascade", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5516982399722", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5511988887777", "document_number": "123.456.789-00", "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ] } ], "collateral_list": [ { "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "collateral_type": "fiduciary_alienation_property" } ], "metadata_list": [ { "metadata_key": "convenio", "metadata_value": "12398129038" } ], } ``` ### **Response Body Params** | Field | Type | Description | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Unique tenant key. | | `operation_key` * | string | Unique operation key. | | `operation_status` * | string | Operation status. | | `issuer_key` * | string | Unique issuer key. | | `issuer_name` * | string | Issuer name. | | `issuer_document_number` * | string | Issuer document. | | `financial` * | object | **[financial Object](#financial-response-object)** | ### financial Response Object | Field | Type | Description | Max Characters | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Financial base date of the operation (format "YYYY-MM-DD"). | - | | `issue_amount` * | number | Total issued amount of the operation. | - | | `released_amount` * | number | Net amount released in the operation. | - | | `issue_quantity` * | integer | Total quantity of units issued. | - | | `unit_price` * | number | Unit price of the issue. | - | | `cet` * | number | Total Effective Cost (CET) as percentage. | - | | `annual_cet` * | number | Annual CET as percentage. | - | | `number_of_installments` * | integer | Total number of installments. | - | | `prefixed_interest_rate` * | object | Object containing prefixed interest rate details. | **[prefixed_interest_rate Object](#prefixed_interest_rate-object)** | | `fees` | array | List of fees associated with the operation. | **[fees Object](#fees-object)** | | `installments` | array | List of installment details generated in the operation. | **[installments Object](#installments-object)** | | `fine_delay_rate` * | object | Object containing delay penalty details. | **[fine_delay_rate Object](#fine_delay_rate-object)** | | `contract_fine_rate` * | number | Contract penalty applied as percentage. | - | ### prefixed_interest_rate Object | Field | Type | Description | Max Characters | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Calculation base for interest. | **[interest_base Enumerators](#interest_base-enumerators)** | | `monthly_rate` * | number | Monthly interest rate applied. | - | | `daily_rate` * | number | Daily interest rate applied. | - | | `annual_rate` * | number | Annual interest rate applied. | - | ### fees Object | Field | Type | Description | Max Characters | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Percentage value of the fee. | - | | `fee_amount` * | number | Monetary value corresponding to the fee. | - | | `amount_type` * | string | Type of fee amount. | **[amount_type Enumerators](#amount_type-enumerators)** | | `fee_type` * | string | Type of fee. | **[fee_type Enumerators](#fee_type-enumerators)** | | `type` * | string | Fee recipient. | **[fee_recipient Enumerators](#fee_recipient-enumerators)** | ### installments Object | Field | Type | Description | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Installment number. | | `workdays` * | integer | Business days until installment due date. | | `calendar_days` * | integer | Calendar days until installment due date. | | `principal_amortization_amount` * | number | Principal amortization amount. | | `principal_amortization_unit_price` * | number | Amortization amount per unit. | | `interest_amount` * | number | Interest amount applied in the installment. | | `amount` * | number | Total installment amount. | | `due_date` * | string | Installment due date (format "YYYY-MM-DD"). | --- # Signature Method Update in Operation URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura This endpoint allows updating the signature method in an operation. --- ## **Signature Method Update in Operation (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signature_method METHOD PUT ### **Path Params** | Field | Type | Description | Max Characters | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | Request Body ```json { "signature_method": "qi_sign" } ``` ### Request Body Params | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `signature_method` * | string | Signature system type. | certifiqi ou qi_sign | ## **Response** STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74", "operation_type": "commercial_paper", "operation_status": "issued", "backoffice_analysis_status": "approved", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "issuer_onboarding_approved": true, "issue_number": 1, "issue_series": 1, "contract_number": "0000000001", "issue_date": "2025-02-03", "financial_base_date": "2025-02-03", "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9", "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8", "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f", "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c", "envelope_signature_status": "signed", "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b", "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a", "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files", "financial": { "financial_base_date": "2025-02-03", "issue_quantity": 1000000, "unit_price": 1.0, "issue_amount": 1000000.0, "released_amount": 1000000.0, "cet": 5.0, "annual_cet": 79.59, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0016053474, "annual_rate": 0.795856326, "monthly_rate": 0.05, "interest_base": "calendar_days_365" }, "fine_delay_rate": { "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "financial_index": null, "post_fixed_interest_rate": null, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 20000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 50000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_number": 1, "workdays": 20, "calendar_days": 30, "principal_amortization_unit_price": 0.18122484, "principal_amortization_amount": 181224.84138231, "interest_amount": 49298.45861769, "amount": 230523.3, "due_principal": 1000000.0, "due_interest": 0.0, "due_date": "2025-03-05", "has_interest": true }, { "installment_number": 2, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.19153595, "principal_amortization_amount": 191535.95353305, "interest_amount": 38987.34646695, "amount": 230523.3, "due_principal": 818775.15861769, "due_interest": 0.0, "due_date": "2025-04-03", "has_interest": true }, { "installment_number": 3, "workdays": 19, "calendar_days": 32, "principal_amortization_unit_price": 0.19748652, "principal_amortization_amount": 197486.52331007, "interest_amount": 33036.77668993, "amount": 230523.3, "due_principal": 627239.20508464, "due_interest": 0.0, "due_date": "2025-05-05", "has_interest": true }, { "installment_number": 4, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.21005991, "principal_amortization_amount": 210059.90840452, "interest_amount": 20463.39159548, "amount": 230523.3, "due_principal": 429752.68177457, "due_interest": 0.0, "due_date": "2025-06-03", "has_interest": true }, { "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.21969277, "principal_amortization_amount": 219692.77337005, "interest_amount": 10830.52662995, "amount": 230523.3, "due_principal": 219692.77337005, "due_interest": 0.0, "due_date": "2025-07-03", "has_interest": true } ] }, "tags": [], "investor_list": [ { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "subscription_percentage": 100.0, "subscription_quantity": 1000000, "investor_onboarding_approved": true, "bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "updated_at": null } ], "related_party_list": [ { "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c", "name": "Blue Logic", "document_number": "97.923.586/0001-06", "role_type": "issuer", "is_active": true, "updated_at": null, "trading_name": "Blue Logic", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5511988887777", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5516982399722", "document_number": "123.456.789-00", "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414" } ] }, { "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30", "name": "Ultimate Cascade", "document_number": "31.424.651/0001-32", "role_type": "investor", "is_active": true, "updated_at": null, "trading_name": "Ultimate Cascade", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5516982399722", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5511988887777", "document_number": "123.456.789-00", "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ] } ], "collateral_list": [ { "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "collateral_type": "fiduciary_alienation_property" } ], "metadata_list": [ { "metadata_key": "convenio", "metadata_value": "12398129038" } ], "signature_method": "qi_sign" } ``` ### **Response Body Params** | Field | Type | Description | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Unique tenant key. | | `operation_key` * | string | Unique operation key. | | `operation_status` * | string | Operation status. | | `issuer_key` * | string | Unique issuer key. | | `issuer_name` * | string | Issuer name. | | `issuer_document_number` * | string | Issuer document. | | `financial` * | object | **[financial object](#financial-object-response)** | ### Financial object response | Field | Type | Description | Max Characters | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Financial base date of the operation (format "YYYY-MM-DD"). | - | | `issue_amount` * | number | Total issued amount of the operation. | - | | `released_amount` * | number | Net amount released in the operation. | - | | `issue_quantity` * | integer | Total quantity of units issued. | - | | `unit_price` * | number | Unit price of the issue. | - | | `cet` * | number | Total Effective Cost (CET) in percentage. | - | | `annual_cet` * | number | Annual CET in percentage. | - | | `number_of_installments` * | integer | Total number of installments. | - | | `prefixed_interest_rate` * | object | Object containing prefixed interest rate details. | **[prefixed_interest_rate object](#prefixed_interest_rate-object)** | | `fees` | array | List of fees associated with the operation. | **[fees object](#fees-object)** | | `installments` | array | List of installment details generated in the operation. | **[installments object](#installments-object)** | | `fine_delay_rate` * | object | Object containing late fee details. | **[fine_delay_rate object](#fine_delay_rate-object)** | | `contract_fine_rate` * | number | Contract fine applied in percentage. | - | ### Prefixed_interest_rate object | Field | Type | Description | Max Characters | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Base for interest calculation. | **[interest_base enumerators](#interest_base-enumerators)** | | `monthly_rate` * | number | Monthly interest rate applied. | - | | `daily_rate` * | number | Daily interest rate applied. | - | | `annual_rate` * | number | Annual interest rate applied. | - | ### Fees object | Field | Type | Description | Max Characters | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Fee percentage amount. | - | | `fee_amount` * | number | Monetary value corresponding to the fee. | - | | `amount_type` * | string | Fee amount type. | **[amount_type enumerators](#amount_type-enumerators)** | | `fee_type` * | string | Fee type. | **[fee_type enumerators](#fee_type-enumerators)** | | `type` * | string | Fee recipient. | **[fee_recipient enumerators](#fee_recipient-enumerators)** | ### Installments object | Field | Type | Description | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Installment number. | | `workdays` * | integer | Workdays until installment due date. | | `calendar_days` * | integer | Calendar days until installment due date. | | `principal_amortization_amount` * | number | Principal amortization amount. | | `principal_amortization_unit_price` * | number | Amortization value per unit. | | `interest_amount` * | number | Interest amount applied to the installment. | | `amount` * | number | Total installment amount. | | `due_date` * | string | Installment due date (format "YYYY-MM-DD"). | --- # Sending Collateral in an Operation URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia This set of endpoints allows the **addition of collaterals** associated with an operation. The **collateral will be submitted for signature along with the operation documents**. Each type of collateral contains its own rules for required documents and all collateral types are covered here in this documentation. --- ## **Send Collateral (POST)** ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | --- The collateral system enables the addition of different types of instruments, each with its own configuration of additional documents. In this section, we cover all available collateral models and their respective payloads. ### **Collateral Types** **[1 - Fiduciary alienation of property](#fiduciary-alienation-of-property)** **[2 - Fiduciary alienation of vehicle](#fiduciary-alienation-of-vehicle)** **[3 - Fiduciary alienation of aircraft](#fiduciary-alienation-of-aircraft)** **[4 - Fiduciary alienation of equipment/products/stock](#fiduciary-alienation-of-equipment-products-and-stock)** **[5 - Fiduciary alienation of artwork](#fiduciary-alienation-of-artwork)** **[6 - Fiduciary alienation of securities](#fiduciary-alienation-of-securities)** **[7 - Fiduciary alienation of shares and quotas](#fiduciary-alienation-of-shares-and-quotas)** **[8 - Fiduciary alienation of credit rights](#fiduciary-alienation-of-credit-rights)** **[9 - Property mortgage](#property-mortgage)** **[10 - Ship mortgage](#ship-mortgage)** **[11 - Guarantee](#guarantee)** **[12 - Guarantor](#guarantor)** **[13 - Bank surety](#bank-surety)** **[14 - Card receivables](#card-receivables)** **[15 - Stock guarantee](#stock-guarantee)** **[16 - Collateral monitoring](#collateral-monitoring)** **[17 - Other collaterals](#other-collaterals)** ## **Fiduciary alienation of property** Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_property", "additional_documents": [ { "document_type": "property_appraisal_report", "document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff" }, { "document_type": "property_registration_updated", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_full_content_certificate", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "property_insurance_policy", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `property_appraisal_report`** | Property Appraisal Report. | | `property_registration_updated`** | Updated registration. | | `property_full_content_certificate`** | Full Content Certificate of Registration. | | `property_insurance_policy` | Insurance Policy (if required in contract). | | `others` | Other documents. | :::warning (**) Required for fiduciary alienation of property ::: ## **Fiduciary alienation of vehicle** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_vehicle", "additional_documents": [ { "document_type": "vehicle_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "vehicle_inspection_report", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "vehicle_crv_certificate", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `vehicle_appraisal_report`** | Vehicle Appraisal Report (maximum 30-day lag) or FIPE Table. | | `vehicle_inspection_report`** | Inspection report. | | `vehicle_crv_certificate`** | Updated Vehicle Registration Certificate (CRLV). | | `others` | Other documents. | :::warning (**) Required for fiduciary alienation of vehicle ::: ## **Fiduciary alienation of aircraft** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_aircraft", "additional_documents": [ { "document_type": "aircraft_certificate_anac", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "aircraft_rab_consult", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "aircraft_insurance_policy", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" }, { "document_type": "aircraft_appraisal_report", "document_key": "df608f78-5293-4f96-ab60-31185633b52c" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `aircraft_certificate_anac`** | Registration Certificate - ANAC. | | `aircraft_rab_consult`** | Aircraft Consultation in Brazilian Aeronautical Registry. | | `aircraft_insurance_policy`** | Insurance Policy - Fund as Beneficiary. | | `aircraft_appraisal_report`** | Aircraft Appraisal Report. | | `others` | Other documents. | :::warning (**) Required for fiduciary alienation of aircraft ::: ## **Fiduciary alienation of equipment products and stock** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_equipment", "additional_documents": [ { "document_type": "equipment_purchase_invoice", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "fiduciary_depositary_declaration", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "equipment_appraisal_report", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" }, { "document_type": "equipment_insurance_policy", "document_key": "df608f78-5293-4f96-ab60-31185633b52c" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `equipment_purchase_invoice`** | Invoice - Purchase Record. | | `equipment_appraisal_report`** | Equipment Appraisal Report (maximum 30-day lag). | | `equipment_insurance_policy` | Equipment Insurance Policy (if required in contract). | | `fiduciary_depositary_declaration` | Faithful Depositary Declaration. | | `others` | Other documents. | :::warning (**) Required for fiduciary alienation of equipment/product/stock ::: ## **Fiduciary alienation of artwork** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_artwork", "additional_documents": [ { "document_type": "artwork_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "artwork_storage_certificate", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `artwork_appraisal_report`** | Artwork Appraisal Report. | | `artwork_storage_certificate`** | Storage Location with Adequacy Certificate. | | `artwork_insurance_policy` | Insurance Policy (if required in contract). | | `others` | Other documents. | :::warning (**) Required for fiduciary alienation of artwork ::: ## **Fiduciary alienation of securities** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_securities", "additional_documents": [ { "document_type": "securities_negotiation_block", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `securities_negotiation_block`** | Trading Block with Custodian. | | `securities_registration_gravame` | Storage Location with Adequacy Certificate. | | `others` | Other documents. | :::warning (**) Required for fiduciary alienation of securities. ::: ## **Fiduciary alienation of shares and quotas** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_assignment_shares", "additional_documents": [ { "document_type": "share_registration_book", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `share_registration_book`** | Nominative Shares Registration Book with Lien Annotation. | | `others` | Other documents. | :::warning (**) Required for fiduciary alienation/pledge of shares/quotas ::: ## **Fiduciary alienation of credit rights** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_assignment_shares", } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `others` | Other documents. | ## **Property mortgage** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "mortgage_property", "additional_documents": [ { "document_type": "property_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_registration", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "property_insurance_policy", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" }, { "document_type": "property_full_content_certificate", "document_key": "df608f78-5293-4f96-ab60-31185633b52c" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `property_appraisal_report`** | Property Appraisal Report. | | `property_registration`** | Updated Property Registration. | | `property_full_content_certificate`** | Full Content Certificate of Registration. | | `property_insurance_policy` | Insurance Policy (if required in contract). | | `others` | Other documents. | :::warning (**) Required for property mortgage. ::: ## **Ship mortgage** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "mortgage_ship", "additional_documents": [ { "document_type": "ship_registration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "ship_appraisal_report", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "ship_insurance_policy", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `ship_registration`** | Updated Ship Property Registration. | | `ship_appraisal_report`** | Ship Appraisal Report (maximum 3-month lag). | | `ship_insurance_policy` | Ship Insurance Policy (if required in contract). | | `others` | Other documents. | :::warning (**) Required for ship mortgage. ::: ## **Guarantee** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "guarantor", "additional_documents": [ { "document_type": "guarantor_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "guarantor_personal_document", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `guarantor_civil_status_declaration`** | Civil Status Declaration of Guarantor. | | `guarantor_personal_document`** | Personal document of Guarantor. | | `guarantor_income_tax_declaration` | Income Tax Declaration of Guarantor. | | `others` | Other documents. | :::warning (**) Required for Guarantee. ::: ## **Guarantor** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "surety", "additional_documents": [ { "document_type": "surety_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "surety_personal_document", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "surety_income_tax_declaration", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `surety_civil_status_declaration`** | Civil Status Declaration of Guarantor. | | `surety_personal_document`** | Personal document of Guarantor. | | `surety_income_tax_declaration` | Income Tax Declaration of Guarantor. | | `others` | Other documents. | :::warning (**) Required for Guarantor. ::: ## **Bank surety** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "bank_surety", "additional_documents": [ { "document_type": "others", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `others` | Other documents. | ## **Card receivables** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "card_receivables", "additional_documents": [ { "document_type": "others", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `others` | Other documents. | ## **Stock guarantee** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "stock_guarantee", "additional_documents": [ { "document_type": "others", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `others` | Other documents. | ## **Collateral monitoring** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "monitoring_guarantee", "additional_documents": [ { "document_type": "guarantee_contract", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "guarantee_agent_contract", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" } ] } ``` ### **Document Types** | Enum | Description | |-----------------|-----------------------------------| | `guarantee_contract`** | Guarantee Contract. | | `guarantee_agent_contract`** | Guarantee Agent Contract. | | `others` | Other documents. | :::warning (**) Required for Collateral Monitoring. ::: --- ## **Request Body Params** | Field | Type | Description | Required | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `collateral_document_key` * | string | Collateral instrument key. | Yes | | `collateral_type` * | string | Collateral type. | **[collateral_type Enums](#collateral_type-enums)** | | `collateral_data` | object | Metadata structure related to collateral. | Yes | | `additional_documents` | list | Documents related to collateral. | - | ### **additional_documents list** | Field | Type | Description | Required | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `document_key` * | string | Collateral instrument key. | Yes | | `document_type` * | string | Collateral document type. | Yes | ### **collateral_type Enums** | Enum | Description | |-----------------|-----------------------------------| | `fiduciary_alienation_property` | Fiduciary alienation of property. | | `fiduciary_alienation_vehicle` | Fiduciary alienation of vehicle. | | `fiduciary_alienation_aircraft` | Fiduciary alienation of aircraft. | | `fiduciary_alienation_equipment` | Fiduciary alienation of equipment/products/stock. | | `fiduciary_alienation_artwork` | Fiduciary alienation of artwork. | | `fiduciary_alienation_securities` | Fiduciary alienation of securities. | | `fiduciary_assignment_shares` | Fiduciary alienation/pledge of shares/quotas. | | `fiduciary_assignment_credit_rights` | Fiduciary alienation of credit rights. | | `mortgage_property` | Property mortgage. | | `mortgage_ship` | Ship mortgage. | | `guarantor` | Guarantee. | | `surety` | Guarantor. | | `bank_surety` | Bank surety. | | `card_receivables` | Card receivables. | | `stock_guarantee` | Stock guarantee. | | `monitoring_guarantee` | Collateral monitoring. | | `others` | Other collaterals. | --- # Collateral Removal from Operation URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia This endpoint allows the **removal of collaterals** associated with an operation. --- ## **Collateral Removal (DELETE)** ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral/ COLLATERAL-KEY METHOD DELETE ### **Path Params** | Field | Type | Description | Max Characters | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | | `COLLATERAL-KEY` * | string | Unique key of the collateral to be removed (UUID v4). | 36 | ## **Response** STATUS 204 **No content is returned in the response body.** --- # Document Upload URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento This endpoint allows uploading **documents** associated with an operation. Such documents can be used in the collateral system to add accessory documents, in addition to the collateral instrument itself. --- ## **Document Upload (POST)** ## **Request** ENDPOINT /commercial_paper/upload METHOD POST Request Body ```json { "document_base64": "sringb64", } ``` ### **Request Body Params** | Field | Type | Description | Required | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `document_base64` * | string | Document content encoded in Base64. | Yes | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ## **Response Body Params** | Field | Type | Description | Max Characters | |------------------|----------|----------------------------------------------|-----------------| | `document_key` * | string | Unique key of the added document (UUID v4). | 36 | --- --- # Operation Metadata Registration and Removal URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao This set of endpoints allows registering and removing metadata in an operation. --- ## **Operation Metadata Registration (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | Request Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | Metadata key. | 255 | | `metadata_value` * | string | Metadata value. | 1023 | ### **Response** STATUS 201 Response Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | Metadata key. | 255 | | `metadata_value` * | string | Metadata value. | 1023 | --- ## **Operation Metadata Removal (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata METHOD DELETE ### **Path Params** | Field | Type | Description | Max Characters | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | Request Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | Metadata key. | 255 | | `metadata_value` * | string | Metadata value. | 1023 | --- ### **Response** STATUS 204 **No content is returned in the response body.** --- # Related Party Representative Document Upload and Removal URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento This set of endpoints allows uploading and removing documents associated with related party representatives to an operation. --- ## **Representative Document Upload (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | |---------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Unique related party key (UUID v4). | 36 | Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | |------------------|----------|-----------------------------------------------------------------|-----------------| | `document_base64` * | string | Document file content encoded in Base64. | - | | `document_type` * | string | Type of document being uploaded. | **[document_type Enumerators](#document_type-enumerators)** | ## **Response** STATUS 201 Response Body ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_identity", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |------------------|----------|----------------------------------------------|-----------------| | `document_key` * | string | Unique identifier of the uploaded document. | 36 | | `document_type` * | string | Type of uploaded document. | **[document_type Enumerators](#document_type-enumerators)** | | `ocr_key` | string | OCR key associated with the uploaded document. | 36 | --- ## **Representative Document Removal (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document/ DOCUMENT-KEY METHOD DELETE ### **Path Params** | Field | Type | Description | Max Characters | |---------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Unique related party key (UUID v4). | 36 | | `DOCUMENT-KEY` * | string | Unique key of the document to be removed. | 36 | ### **Response** STATUS 204 **No content is returned in the response body.** ### **document_type Enumerators** | Enum | Description | |---------------------------|-----------------------------------------| | `danfe` | DANFE (Auxiliary Document of NF-e). | | `proof_of_address` | Proof of Address. | | `letter_of_attorney` | Power of Attorney. | | `company_statute` | Company Statute. | | `cnh` | National Driver's License (CNH). | | `cnh_front` | CNH Front. | | `cnh_back` | CNH Back. | | `cnh_digital` | Digital CNH. | | `rg_front` | ID Front. | | `rg_back` | ID Back. | --- # Related Party Representative Signer Group Upload and Removal URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes This set of endpoints allows uploading and removing signer groups associated with related party representatives to an operation. --- ## **Signer Group Upload (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | |-----------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Unique related party key (UUID v4). | 36 | Request Body ```json { "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "12345678901", "email": "joao.silva@example.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "98765432100", "email": "maria.souza@example.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | |------------------------------|----------|--------------------------------------------------------|-----------------| | `minimum_required_signers` * | integer | Minimum number of signers required in the group. | - | | `signers` * | array | List of group signers. | **[signers Object](#signers-object)** | --- ### **signers Object** | Field | Type | Description | Max Characters | |--------------------------|----------|-------------------------------------------------|-----------------| | `name` * | string | Full name of the signer. | 255 | | `document_number` * | string | Signer's CPF (11 digits). | 11 | | `email` * | string | Signer's email address. | 1023 | | `phone_number` * | string | Signer's phone number, including country code. | 20 | | `is_group_mandatory` * | boolean | Indicates if the signer is mandatory. | - | ## **Response** STATUS 201 Response Body ```json { "signer_group_key": "123e4567-e89b-12d3-a456-426614174000", "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "12345678901", "email": "joao.silva@example.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "98765432100", "email": "maria.souza@example.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |------------------------------|----------|-------------------------------------------------|-----------------| | `signer_group_key` * | string | Unique signer group key (UUID v4). | 36 | | `minimum_required_signers` * | integer | Minimum number of signers in the group. | - | | `signers` * | array | List of group signers. | **[signers Object](#signers-object)** | --- ## **Signer Group Removal (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group/ SIGNER-GROUP-KEY METHOD DELETE ### **Path Params** | Field | Type | Description | Max Characters | |-----------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Unique related party key (UUID v4). | 36 | | `SIGNER-GROUP-KEY` * | string | Unique signer group key. | 36 | ### **Response** STATUS 204 **No content is returned in the response body.** --- # Specific Document Related Party Registration and Removal URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento This set of endpoints allows registering and removing related parties to an operation for a specific document of the operation. --- ## **Add Related Party to Document (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document FORMALIZATION-DOCUMENT-KEY /related_party METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | | `FORMALIZATION-DOCUMENT-KEY` * | string | Unique operation document key (UUID v4). | 36 | Request Body ```json { "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | | --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `related_party_key` * | string | Related Party Key | | 36 ## **Response** STATUS 204 **No content is returned in the response body.** ## **Related Party Removal (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document/ FORMALIZATION-DOCUMENT-KEY /related_party METHOD DELETE ### **Path Params** | Field | Type | Description | Max Characters | | ----------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | | `FORMALIZATION-DOCUMENT-KEY` * | string | Unique operation document key (UUID v4). | 36 | Request Body ```json { "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Response** STATUS 204 **No content is returned in the response body.** --- # Related Party Registration and Removal URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada This set of endpoints allows registering and removing related parties to an operation. :::warning All related parties are added by default to the Constitutive Term (**commercial_paper**). If you want to add this related party to a specific document, fill the **related_document_key** field with the key of the desired document. ::: --- ## **Related Party Registration (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | :::info Important **Attention to person type when building the payload:** - **Natural Person**: `"person_type": "natural"` - **Legal Person**: `"person_type": "legal"` ::: Request Body - Natural Person ```json { "person_type": "natural", "name": "João da Silva", "document_number": "12345678901", "street": "Rua dos Exemplo", "neighborhood": "Centro", "number": "123", "postal_code": "01001000", "city": "São Paulo", "state": "SP", "role_type": "guarantor", "is_pep": false } ``` Request Body - Legal Person ```json { "person_type": "legal", "name": "João da Silva", "trading_name": "Padaria do João LTDA", "document_number": "92.123.456/0001-00", "street": "Rua dos Exemplo", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "guarantor", "cnae_code": "12.34-5-67", "company_type": "ltda", "foundation_date": "2025-01-01" } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | | --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `person_type` * | string | Person type. | **[person_type Enumerators](#person_type-enumerators)** | | `name` * | string | Related party name. | 255 | | `document_number` * | string | CPF (format "XXX.XXX.XXX-XX") or CNPJ (format "XX.XXX.XXX/XXXX-XX"). | 14 | | `street` * | string | Address street. | 500 | | `neighborhood` | string | Address neighborhood. | 100 | | `number` * | string | Address number. | 10 | | `postal_code` * | string | Address postal code (format "XXXXX-XXX"). | 8 | | `city` * | string | Address city. | 255 | | `state` * | string | State abbreviation (2 characters). | 2 | | `role_type` * | string | Related party role. | **[role_type Enumerators](#role_type-enumerators)** | | `related_document_key` | string | Document identification key (UUIDv4) | 36 ### **person_type Enumerators** | Enum | Description | | ----------- | ---------------- | | `natural` | Natural Person | | `legal` | Legal Person | ### **Additional fields for Natural Person** | Field | Type | Description | Max Characters | | ---------------------------------- | ------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------- | | `document_identification_number` | string | ID number (without formatting) | 20 | | `marital_status` | string | Marital status. | **[marital_status Enumerators](#marital_status-enumerators)** | | `property_system` | string | Property regime. | **[property_system Enumerators](#property_system-enumerators)** | | `birthdate` | string | Birth date (YYYY-MM-DD). | - | | `nationality` | string | Nationality. | 255 | | `mother_name` | string | Mother's name. | 255 | | `father_name` | string | Father's name. | 255 | | `occupation` | string | Occupation. | 255 | | `is_pep` * | boolean | Indicates if the related party is a Politically Exposed Person (PEP). | | ### **Additional fields for Legal Person** | Field | Type | Description | Max Characters | | --------------------- | ------ | -------------------------------------- | -------------------------------------------------------------- | | `trading_name` * | string | Company trade name. | 1023 | | `cnae_code` * | string | Company CNAE code (10 digits). | 10 | | `company_type` * | string | Company type. | **[company_type Enumerators](#company_type-enumerators)** | | `foundation_date` * | string | Foundation date (YYYY-MM-DD). | - | ### **role_type Enumerators** | Enum | Description | | -------------------------- | ------------------------ | | `cosigner` | Cosigner | | `fiduciary_debtor` | Fiduciary Debtor | | `solidary_debtor` | Solidary Debtor | | `surety` | Surety | | `guarantor` | Guarantor | | `bonafide_depositary` | Bona Fide Depositary | | `intervening_guarantor` | Intervening Guarantor | | `intervening_consentor` | Intervening Consenter | | `intervening_discharger` | Intervening Discharger | | `assignor` | Assignor | | `endorser` | Endorser | | `consulting` | Consultant | | `fund_administrator` | Fund Administrator | | `fund_representative` | Fund Representative | | `company_representative` | Company Representative | | `attestant` | Witness | | `debtor` | Debtor | | `bestowal` | Spousal Authorization | | `manager` | Manager | ### marital_status Enumerators | Enum | Description | | ----------- | ---------------- | | `single` | Single | | `married` | Married | | `divorced` | Divorced | | `widowed` | Widowed | | `separated` | Separated | | `stable_union`| Stable Union | ### property_system Enumerators | Enum | Description | | --------------------------------- | -------------------------------------- | | `total_communion_of_goods` | Total Community of Property | | `partial_communion_of_goods` | Partial Community of Property | | `total_separation_of_goods` | Total Separation of Property | | `final_participation_of_acquisitions` | Final Participation in Acquisitions | | `compulsory_separation_of_goods` | Compulsory Separation of Property | ### company_type Enumerators | Enum | Description | | ------------------- | ---------------------------- | | `ltda` | Limited Liability Company | | `sa` | Corporation | | `cop` | Cooperative | ## **Response** STATUS 201 Response Body ```json { "related_party_key": "c642a117-ea6e-4da7-a8fd-451f556e5c38", "name": "João da Silva", "document_number": "12345678901", "role_type": "guarantor", "is_active": true, "updated_at": null, "person_type": "natural", "street": "Rua dos Exemplo", "neighborhood": "Centro", "number": "123", "postal_code": "01001000", "city": "São Paulo", "state": "SP", "signer_group_list": [], "document_list": [], "contact_information_list": [] } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | | ----------------------- | ------- | ---------------------------------------------------- | ------------------------------------------------------------ | | `related_party_key` * | string | Unique related party key. | 36 | | `name` * | string | Related party name. | 255 | | `document_number` * | string | Related party CPF/CNPJ. | 14 | | `role_type` * | string | Related party role. | 50 | | `is_active` * | boolean | Indicates if it is active. | - | | `updated_at` | string | Last update date (YYYY-MM-DD HH:mm:ss). | - | | `person_type` * | string | Person type. | **[person_type Enumerators](#person_type-enumerators)** | | `street` * | string | Street. | 500 | | `neighborhood` | string | Neighborhood. | 100 | | `number` * | string | Number. | 10 | | `postal_code` * | string | Postal code (numbers only). | 8 | | `city` * | string | City. | 255 | | `state` * | string | State abbreviation (2 characters). | 2 | --- ## **Related Party Removal (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY METHOD DELETE ### **Path Params** | Field | Type | Description | Max Characters | | ----------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Unique related party key. | 36 | ### **Response** STATUS 204 **No content is returned in the response body.** --- # Commercial Paper Operation Registration URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao This endpoint allows creating a new commercial paper operation based on financial and investor data. --- ## **Request** ENDPOINT /commercial_paper/operation METHOD POST Request Body ```json { "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_bank_account": { "account_number": "4464541", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" }, "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "issue_date": "2025-01-23", "signature_method": "certifiqi", "financial": { "interest_type": "pre_price_days", "financial_base_date": "2025-01-23", "released_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee" } ] } } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | | ------------------------- | ------ | ------------------------------------------------------ | ---------------------------------------------------------------- | | `issuer_key` * | string | Unique issuer key. | - | | `issuer_bank_account` * | object | Issuer bank account. | **[issuer_bank_account Object](#issuer_bank_account-object)** | | `investors` * | array | List of involved investors. | **[investors Object](#investors-object)** | | `issue_date` * | string | Operation issue date (format "YYYY-MM-DD"). | - | | `signature_method` | string | Signature method used in the operation. Optional; when omitted, defaults to `certifiqi`. | **[signature_method Enumerators](#signature_method-enumerators)** | | `financial` * | object | Operation financial data. | **[financial Object](#financial-object)** | | `third_party_disbursement` | object | Third-party disbursement instruction. Optional; requires prior enablement. | **[third_party_disbursement Object](#third_party_disbursement-object)** | ### **issuer_bank_account Object** | Field | Type | Description | | --------------------------------------- | ------ | ------------------------------------------ | | `account_number` * | string | Bank account number. | | `account_digit` * | string | Bank account digit. | | `account_branch` * | string | Bank account branch. | | `financial_institution_code_number` * | string | Financial institution code. | | `financial_institution_ispb` * | string | Financial institution ISPB code. | | `account_type` * | string | Account type (`checking`, `savings`). | ### **investors Object** | Field | Type | Description | | ----------------------------- | ------ | ------------------------------ | | `investor_key` * | string | Unique investor key. | | `subscription_percentage` * | number | Subscription percentage. | | `bank_account` * | object | Investor bank account. | ### **financial Object** | Field | Type | Description | | ---------------------------- | ------- | -------------------------------------------- | | `interest_type` * | string | Interest type. | | `financial_base_date` * | string | Financial base date (format "YYYY-MM-DD"). | | `released_amount` * | number | Released amount. | | `number_of_installments` * | integer | Number of installments. | | `prefixed_interest_rate` * | object | Prefixed interest rate. | | `fine_delay_rate` * | object | Delay fine rate. | | `contract_fine_rate` * | number | Contractual fine in percentage. | | `fees` | array | List of fees. | ### **third_party_disbursement Object** Optional instruction stating that the released amount will be paid to a third-party beneficiary instead of the issuer's settlement account. The object does not accept fields beyond the ones listed (`additionalProperties: false`) and the two tracks — TED and bank slip — are mutually exclusive. | Field | Type | Description | Max Characters | | ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `payment_method` * | string | Payment track used in the disbursement (`ted`, `bank_slip`, `pix`). | - | | `target_account` | object | Beneficiary bank account. Required when `payment_method` is `ted`; forbidden on the other tracks. | **[target_account Object](#target_account-object)** | | `digitable_line` | string | Digitable line of the beneficiary's bank slip, digits only (pattern `^[0-9]{47}$`). Required when `payment_method` is `bank_slip`; forbidden on the other tracks. | 47 | | `pix_key` | string | Beneficiary's Pix key, **unformatted** for CPF and CNPJ. Required when `payment_method` is `pix`; forbidden on the other tracks. | 77 | | `pix_key_type` | string | Declared type of the Pix key (`cpf`, `cnpj`, `phone`, `email`, `evp`). Required when `payment_method` is `pix`; forbidden on the other tracks. | - | | `beneficiary` | object | Qualification of the third-party beneficiary. **Required** when `payment_method` is `pix`; optional on `ted` and `bank_slip`. | **[Third-party disbursement](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro)** | :::info Feature available on request Sending `third_party_disbursement` requires prior enablement by QI Tech; without it the creation is refused with `COM000062`. The complete rules — including the bank slip amount check, the Pix key types and the `beneficiary` object fields — are in [Third-party disbursement on the operation](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro). ::: ### **target_account Object** | Field | Type | Description | Max Characters | | ----------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------- | | `account_branch` * | string | Beneficiary bank account branch, digits only (exactly 4). | 4 | | `account_number` * | string | Beneficiary bank account number, digits only (1 to 20). | 20 | | `account_digit` * | string | Beneficiary bank account digit, digits only (exactly 1). | 1 | | `financial_institution_ispb` * | string | ISPB code of the beneficiary's financial institution, digits only (exactly 8). Determines the TED routing. | 8 | | `financial_institution_code_number` | string or `null` | Code of the beneficiary's financial institution, digits only (3). Optional and not used for routing. | 3 | | `account_type` * | string | Beneficiary account type (`checking`, `savings`, `salary`, `payment`). | - | | `owner_document_number` * | string | CPF or CNPJ of the account holder, **formatted** (`000.000.000-00` or `00.000.000/0000-00`). The check digits are validated. | 18 | | `owner_name` * | string | Account holder name (1 to 50 characters). | 50 | ### signature_method Enumerators | Value | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `certifiqi` | Default value. The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). | | `qi_sign` | The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). Also allows querying the operation's signers. | | `client_side` | The documents are signed outside the QI Tech platform and sent through the **[send signed documents endpoint](/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados)**. No signature URL is generated. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "in_filling", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "financial": { ... } } ``` ### **Response Body Params** | Field | Type | Description | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Unique tenant key. | | `operation_key` * | string | Unique operation key. | | `operation_status` * | string | Operation status. | | `issuer_key` * | string | Unique issuer key. | | `issuer_name` * | string | Issuer name. | | `issuer_document_number` * | string | Issuer document. | | `financial` * | object | **[financial Object](#financial-object-response)** | ### financial Object Response | Field | Type | Description | Max Characters | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Operation financial base date (format "YYYY-MM-DD"). | - | | `issue_amount` * | number | Total issued amount of the operation. | - | | `released_amount` * | number | Net amount released in the operation. | - | | `issue_quantity` * | integer | Total quantity of units issued. | - | | `unit_price` * | number | Unit price of the issuance. | - | | `cet` * | number | Total Effective Cost (CET) in percentage. | - | | `annual_cet` * | number | Annual CET in percentage. | - | | `number_of_installments` * | integer | Total number of installments. | - | | `prefixed_interest_rate` * | object | Object containing prefixed interest rate details. | **[prefixed_interest_rate Object](#prefixed_interest_rate-object)** | | `fees` | array | List of fees associated with the operation. | **[fees Object](#fees-object)** | | `installments` | array | List of installment details generated in the operation. | **[installments Object](#installments-object)** | | `fine_delay_rate` * | object | Object containing delay fine details. | **[fine_delay_rate Object](#fine_delay_rate-object)** | | `contract_fine_rate` * | number | Contractual fine applied in percentage. | - | ### prefixed_interest_rate Object | Field | Type | Description | Max Characters | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Calculation base for interest. | **[interest_base Enumerators](#interest_base-enumerators)** | | `monthly_rate` * | number | Applied monthly interest rate. | - | | `daily_rate` * | number | Applied daily interest rate. | - | | `annual_rate` * | number | Applied annual interest rate. | - | ### fees Object | Field | Type | Description | Max Characters | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Percentage value of the fee. | - | | `fee_amount` * | number | Monetary value corresponding to the fee. | - | | `amount_type` * | string | Type of fee value. | **[amount_type Enumerators](#amount_type-enumerators)** | | `fee_type` * | string | Type of fee. | **[fee_type Enumerators](#fee_type-enumerators)** | | `type` * | string | Fee recipient. | **[fee_recipient Enumerators](#fee_recipient-enumerators)** | ### installments Object | Field | Type | Description | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Installment number. | | `workdays` * | integer | Business days until installment due date. | | `calendar_days` * | integer | Calendar days until installment due date. | | `principal_amortization_amount` * | number | Principal amortized amount. | | `principal_amortization_unit_price` * | number | Amortized amount per unit. | | `interest_amount` * | number | Interest amount applied in the installment. | | `amount` * | number | Total installment amount. | | `due_date` * | string | Installment due date (format "YYYY-MM-DD"). | --- # Third-party disbursement on the operation URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro This endpoint sets or replaces the third-party disbursement instruction of an operation, stating that the released amount will be paid to a third-party beneficiary (a supplier, for example) instead of the issuer's settlement account. :::info Feature available on request Third-party disbursement is not enabled by default. Request the enablement from QI Tech before integrating — without it, the request is refused with `COM000062`. ::: :::warning Full replacement and change window The request **replaces the whole instruction** — there is no partial field update. The instruction can only be set or changed while the operation is in the `in_filling` status; outside that status the request is refused with `COM000010`. ::: --- ## **Third-party disbursement on the operation (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /third_party_disbursement METHOD PUT ### **Path Params** | Field | Type | Description | Max Characters | | ----------------- | ------ | ------------------------------- | -------------- | | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | Request Body — TED ```json { "payment_method": "ted", "target_account": { "account_branch": "0001", "account_number": "4464541", "account_digit": "3", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329", "account_type": "checking", "owner_document_number": "11.222.333/0001-81", "owner_name": "Fornecedor Exemplo LTDA" } } ``` Request Body — Bank slip ```json { "payment_method": "bank_slip", "digitable_line": "34191790010104351004791020150008291070100000000" } ``` Request Body — Pix ```json { "payment_method": "pix", "pix_key": "52998224725", "pix_key_type": "cpf", "beneficiary": { "person_type": "natural", "name": "João da Silva", "document_number": "529.982.247-25", "street": "Rua das Flores", "number": "100", "postal_code": "01234-567", "city": "São Paulo", "state": "SP", "is_pep": false } } ``` ### **Request Body Params** The body does not accept fields beyond the ones listed (`additionalProperties: false`). The three tracks are mutually exclusive and the exclusivity is enforced by the schema: sending the field of one track alongside another, omitting the required field of the chosen track, or sending an unknown field returns `QIT000001`. | Field | Type | Description | Max Characters | | ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `payment_method` * | string | Payment track used in the disbursement. | **[payment_method Enumerators](#payment_method-enumerators)** | | `target_account` | object | Beneficiary bank account. Required when `payment_method` is `ted`; forbidden on the other tracks. | **[target_account Object](#target_account-object)** | | `digitable_line` | string | Digitable line of the beneficiary's bank slip, digits only (pattern `^[0-9]{47}$`). Required when `payment_method` is `bank_slip`; forbidden on the other tracks. | 47 | | `pix_key` | string | Beneficiary's Pix key, **unformatted** for CPF and CNPJ. Required when `payment_method` is `pix`; forbidden on the other tracks. | 77 | | `pix_key_type` | string | Declared type of the Pix key. Required when `payment_method` is `pix`; forbidden on the other tracks. | **[pix_key_type Enumerators](#pix_key_type-enumerators)** | | `beneficiary` | object | Qualification of the third-party beneficiary. **Required** when `payment_method` is `pix`; optional on `ted` and `bank_slip`. | **[beneficiary Object](#beneficiary-object)** | ### **payment_method Enumerators** | Value | Description | | ----------- | -------------------------------------------------------------- | | `ted` | Payment by TED to the account given in `target_account`. | | `bank_slip` | Payment of the bank slip given in `digitable_line`. | | `pix` | Pix payment to the key given in `pix_key`. | ### **pix_key_type Enumerators** | Value | Description | | -------- | ------------------------------------------------------------ | | `cpf` | CPF, 11 digits, unpunctuated. | | `cnpj` | CNPJ, 14 digits, unpunctuated. | | `phone` | Phone number as `+55` followed by 10 or 11 digits. | | `email` | Email address, up to 77 characters. | | `evp` | Random key (lowercase UUID). | The key **format** is validated by the schema according to the declared `pix_key_type` — out of format, `QIT000001`. For `cpf` and `cnpj` the **check digits** are verified afterwards: right format with wrong check digits returns `COM000071`. ### **target_account Object** | Field | Type | Description | Max Characters | | ----------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | `account_branch` * | string | Beneficiary bank account branch, digits only (exactly 4). | 4 | | `account_number` * | string | Beneficiary bank account number, digits only (1 to 20). | 20 | | `account_digit` * | string | Beneficiary bank account digit, digits only (exactly 1). | 1 | | `financial_institution_ispb` * | string | ISPB code of the beneficiary's financial institution, digits only (exactly 8). Determines the TED routing. | 8 | | `financial_institution_code_number` | string or `null` | Code of the beneficiary's financial institution, digits only (3). Optional and not used for routing. | 3 | | `account_type` * | string | Beneficiary account type. | **[account_type Enumerators](#account_type-enumerators)** | | `owner_document_number` * | string | CPF or CNPJ of the account holder, **formatted** (`000.000.000-00` or `00.000.000/0000-00`). The check digits are validated. | 18 | | `owner_name` * | string | Account holder name (1 to 50 characters). | 50 | ### **account_type Enumerators** | Value | Description | | ---------- | ---------------- | | `checking` | Checking account. | | `savings` | Savings account. | | `salary` | Salary account. | | `payment` | Payment account. | ### **beneficiary Object** Identifies the third party receiving the amount. Required on the `pix` track — a Pix key does not say who is being paid — and optional on `ted` and `bank_slip`. It travels with the instruction, is signed together with the operation, and is used in the corporate minute that formalises the payment to the third party. **Only `name` and `document_number` are required.** Every other field is optional and serves to enrich the beneficiary's qualification in the minute. | Field | Type | Description | Required | | ----- | ---- | ------------- | -------- | | `person_type` | string | `natural` (individual) or `legal` (company). | Optional | | `name` * | string | Beneficiary name. | Always | | `document_number` * | string | CPF or CNPJ, **formatted** (`000.000.000-00` or `00.000.000/0000-00`). | Always | | `street` | string | Street. | Optional | | `number` | string | Address number. | Optional | | `postal_code` | string | Postal code as `00000-000`. | Optional | | `city` | string | City. | Optional | | `state` | string | State, two uppercase letters. | Optional | | `is_pep` | boolean | Whether the person is a Politically Exposed Person. | Optional | | `trading_name` | string | Trading name. | Optional | | `cnae_code` | string | CNAE as `00.00-0-00`. | Optional | | `company_type` | string | Company type. | Optional | | `foundation_date` | string | Foundation date (`YYYY-MM-DD`). | Optional | | `neighborhood` | string | Neighborhood. | Optional | | `complement` | string | Address complement. | Optional | | `document_identification_number` | string | ID document number. | Optional | | `marital_status` | string | Marital status. | Optional | | `property_system` | string | Marital property system. | Optional | | `birthdate` | string | Date of birth (`YYYY-MM-DD`). | Optional | | `nationality` | string | Nationality. | Optional | | `mother_name` | string | Mother's name. | Optional | | `father_name` | string | Father's name. | Optional | | `occupation` | string | Occupation. | Optional | :::tip The more you send, the fuller the minute With `person_type`, the minute gains the beneficiary's **qualification**. With `street`, `number`, `postal_code`, `city` and `state` — all five —, it gains the formatted **address**. Sending only name and document, the minute names the beneficiary without qualifying or addressing it: nothing fails, the document is simply leaner. ::: :::warning TED — check the ISPB The destination institution of the TED is determined by the `financial_institution_ispb`. A wrong ISPB sends the money to the wrong institution even if the `financial_institution_code_number` is correct. ::: :::warning Bank slip — the amount must match the released amount The bank slip amount is read from the **last 10 digits of the digitable line, in cents**, and must be equal to the operation's `financial.released_amount`. Any difference is refused with `COM000061`. Because the calculated `released_amount` differs from the requested amount due to fees, the practical path is: create the operation, read the `released_amount` from the response, and only then attach a bank slip for that exact amount. **Do not rewrite the amount of a real digitable line** — that invalidates its check digits and the bank slip stops being payable. One commercial paper pays exactly one beneficiary, for the full amount: payment splitting is not supported. ::: ## **Response** STATUS 200 The response carries the full operation object, in the same shape returned by the [operation query by key](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave). Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_type": "commercial_paper", "operation_status": "in_filling", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28.980.395/0001-55", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "financial": { ... } } ``` ### **Response Body Params** | Field | Type | Description | | -------------------------- | ------ | ----------------------- | | `tenant_key` * | string | Unique tenant key. | | `operation_key` * | string | Unique operation key. | | `operation_status` * | string | Operation status. | | `issuer_key` * | string | Unique issuer key. | | `issuer_name` * | string | Issuer name. | | `issuer_document_number` * | string | Issuer document number. | | `financial` * | object | Operation financial data. | :::info The instruction appears in the operation object as `third_party_disbursement`, in the same shape it was sent. When the operation has no third-party disbursement, the key is **omitted** from the response — it is not returned as `null`. ::: --- ## **Errors** The codes below are also described in the [error catalog](/documentation/escrituracao/catalogo-erros/catalogo-erros). | Code | HTTP | Description | | ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `QIT000001` | 400 | Schema failure — for example, `payment_method` missing or outside the enum, an invalid combination of `target_account` and `digitable_line`, a `digitable_line` outside the 47-digit pattern, or an unknown field in the body. | | `COM000010` | 400 | Operation cannot be updated outside the `in_filling` status. | | `COM000061` | 400 | Bank slip amount differs from the operation's `released_amount`. | | `COM000062` | 400 | Third-party disbursement is not enabled. | | `COM000063` | 400 | Beneficiary document is invalid. | | `COM000071` | 400 | `pix_key` of type `cpf`/`cnpj` has invalid check digits. | | `COM000007` | 404 | Operation not found. | | `COM000008` | 403 | Operation does not belong to the requesting tenant. | --- # Extra Fields URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields This set of endpoints allows you to query the extra fields available in a document template and to save custom values for those fields in an operation. :::warning To use extra fields, the document template must already have been defined. Otherwise, generate a draft preview before using these endpoints. ::: :::info Important Extra fields are organized by document type (`document_type`). When saving extra fields via POST, the previous values for that `document_type` are **entirely replaced** — no merge with existing values is performed. ::: --- ## **Query Available Extra Fields (GET)** Returns the extra fields available in the template associated with the operation's document type. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields METHOD GET ### **Path Params** | Field | Type | Description | Max. Characters | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Unique key of the operation (UUID v4). | 36 | ### **Query Params** | Field | Type | Description | Max. Characters | | ------------------- | ------ | ------------------------------------- | ---------------- | | `document_type` * | string | Document type. | **[document_type enumerators](#document_type-enumerators)** | ### **Response** STATUS 200 Response Body ```json { "operation_key": "550e8400-e29b-41d4-a716-446655440000", "document_type": "commercial_paper", "template_key": "660e8400-e29b-41d4-a716-446655440001", "extra_fields": [ { "field_key": "warranty_description", "field_label": "Descrição da Garantia", "field_type": "string" }, { "field_key": "special_conditions", "field_label": "Condições Especiais", "field_type": "string" }, { "field_key": "additional_clause", "field_label": "Cláusula Adicional", "field_type": "string" } ] } ``` ### **Response Body Params** | Field | Type | Description | Max. Characters | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `operation_key` * | string | Unique key of the operation (UUID v4). | 36 | | `document_type` * | string | Document type queried. | **[document_type enumerators](#document_type-enumerators)** | | `template_key` * | string | Unique key of the associated template (UUID v4). | 36 | | `extra_fields` * | array | List of extra fields available in the template. | - | ### **Fields of the extra_fields object** | Field | Type | Description | Max. Characters | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `field_key` * | string | Unique identifier of the extra field. | 255 | | `field_label` * | string | Descriptive label of the extra field. | 255 | | `field_type` * | string | Data type of the extra field (e.g. `string`). | 50 | --- ## **Save Extra Fields (POST)** Saves the values of the extra fields for a specific document type in an operation. The values sent entirely replace the previous extra fields for the informed `document_type`. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields METHOD POST ### **Path Params** | Field | Type | Description | Max. Characters | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Unique key of the operation (UUID v4). | 36 | Request Body ```json { "document_type": "commercial_paper", "extra_fields": { "warranty_description": "Garantia prestada pelo avalista", "special_conditions": "Condição especial de vencimento antecipado", "additional_clause": "Cláusula de cross default" } } ``` ### **Request Body Params** | Field | Type | Description | Max. Characters | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `document_type` * | string | Document type. | **[document_type enumerators](#document_type-enumerators)** | | `extra_fields` * | object | Object containing the extra fields and their values. The keys must match the `field_key` returned by the GET query. All values must be strings. | - | :::warning The keys sent in the `extra_fields` object must match exactly the `field_key` available in the template. Invalid keys will result in an error. ::: ### **Response** STATUS 201 Response Body ```json { "operation_key": "550e8400-e29b-41d4-a716-446655440000", "document_type": "commercial_paper", "extra_fields": { "warranty_description": "Garantia prestada pelo avalista", "special_conditions": "Condição especial de vencimento antecipado", "additional_clause": "Cláusula de cross default" } } ``` ### **Response Body Params** | Field | Type | Description | Max. Characters | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `operation_key` * | string | Unique key of the operation (UUID v4). | 36 | | `document_type` * | string | Document type. | **[document_type enumerators](#document_type-enumerators)** | | `extra_fields` * | object | Object containing the saved extra fields with their respective values. | - | --- ## **document_type enumerators** | Enum | Description | | -------------------- | ---------------------- | | `commercial_paper` | Constitutive Term | | `adhesion_term` | Adhesion Term | --- ## **Errors** | Code | HTTP | Description | | ---------- | ---- | -------------------------------------------------------------------------------------------------------- | | `COM000007` | 404 | Operation not found. | | `COM000008` | 403 | Operation does not belong to the requesting tenant. | | `COM000044` | 400 | Template not defined for the document type. Generate a draft preview before proceeding. | | `COM000045` | 400 | Extra field keys not available in the template. | --- # Client acceptance log upload URL: /en/documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite This endpoint attaches a PDF holding the client acceptance log to an operation — the record of the evidence that the end client accepted the operation's terms. It exists for the **auto signature** flow: when QI Tech signs the Termo Constitutivo on the issuer's behalf using the private certificate released in CertifiQI, no signature link is generated for the client, and the acceptance log is what documents their consent. :::info Optional upload The upload is **not mandatory** and no issuance step depends on it. The operation moves through analysis, signature and issuance normally without an acceptance log — the document is kept as evidence attached to the operation. ::: :::warning Requires an issuer enabled for auto signature The upload is only accepted when the operation's issuer has the auto signature enablement in `enabled` on the issuer system. An issuer with no enablement, or with an enablement in any other status (`pending_term_generation`, `pending_signature`, `reproved`, `canceled`), is refused with `COM000077` and nothing is stored. The upload is also only accepted while the operation is in the `in_filling` status; outside that status the request is refused with `COM000010`. ::: --- ## **Client acceptance log upload (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /acceptance_log METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | | ----------------- | ------ | ------------------------------- | -------------- | | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | Request Body ```json { "document_base64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..." } ``` ### **Request Body Params** The body accepts no fields beyond the one listed (`additionalProperties: false`) — an unknown field, or a missing `document_base64`, returns `QIT000001`. | Field | Type | Description | Max Characters | | ------------------- | ------ | ----------------------------------------------------------------------------------------------- | -------------- | | `document_base64` * | string | Client acceptance log PDF, base64-encoded, with no `data:` prefix and no line breaks. | — | ## **Response** STATUS 201 Response Body ```json { "document_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "created_at": "2026-09-10T14:30:00.000000+00:00" } ``` ### **Response Body Params** | Field | Type | Description | | ----------------- | ------ | ------------------------------------------------------------ | | `document_key` * | string | Unique document key generated by this upload (UUID v4). | | `operation_key` * | string | Unique key of the operation the document was attached to. | | `created_at` * | string | Upload date and time, in UTC. | :::info How to confirm what was attached The operation starts exposing the `acceptance_log_document_key` field on the [operation retrieval by key](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave), filled from the most recent upload. Before the first upload the field returns `null`. ::: :::warning A new upload replaces the previous document A new upload for the same operation generates a new `document_key` and becomes the current acceptance log — the previous reference stops being pointed at by the operation. There is no partial update and there is no deletion endpoint. ::: --- ## **Errors** The codes below are also described in the [error catalog](/documentation/escrituracao/catalogo-erros/catalogo-erros). | Code | HTTP | Description | | ----------- | ---- | -------------------------------------------------------------------- | | `QIT000001` | 400 | Schema failure — `document_base64` missing or unknown field in the body. | | `COM000010` | 400 | Operation cannot be updated outside the `in_filling` status. | | `COM000077` | 400 | The operation's issuer is not enabled for auto signature. | | `COM000007` | 404 | Operation not found. | | `COM000008` | 403 | Operation does not belong to the requesting tenant. | --- # Cancel Operation URL: /en/documentation/escrituracao/emissao-de-notas/cancelar-operacao This endpoint allows changing the status of an operation to "canceled", final status for cases where the operation will no longer be completed by the client. --- ## Cancel Operation (PATCH) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY METHOD PATCH ### Path Params | Field | Type | Description | Characters | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Request Body ```json { "operation_status": "canceled" } ``` ### Request Body Params | Field | Type | Description | Required | |--------------------|----------|-----------------------------------------------------------|----------| | `operation_status` | string | Operation status. Must be set as `canceled`. | Yes | --- ### Response The response body is a complete JSON of the updated operation. --- --- # Query Signed Contract Link via QI SIGN of the Operation URL: /en/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign This endpoint allows you to query all signed documents of a specific operation via QI SIGN, using its unique key. --- :::warning Attention The signed contract link is valid for 24 hours. After that, it is necessary to renew the link by making a new request through the endpoint. ::: ## Query Operation Signed Link (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signed_url METHOD GET ### Path Params | Field | Type | Description | Characters | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce", "status": "signed", "documents": [ { "document_type": "ncom_pre_price", "signed_url": "https://qisign-dossiers.com/7bcf5868-784a-4356-85fb-dd72fd53cd4a.pdf", "signers": [] }, { "document_type": "adhesion_term", "signed_url": "https://qisign-dossiers.com/7bcf5868-784a-4356-85fb-dd72fd53cd4a.pdf", "signers": [] } ] } ``` ### Response Body Params | Field | Type | Description | Max Characters | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `envelope_key` | string | Unique envelope key (UUID v4). | 36 | | `status` | string | Envelope status | [Status enumerators](#enumeradores-operation-status) | `documents` | list | List of envelope documents | - | ### document object | Field | Type | Description | Max Characters | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_type` | string | Document type. | [Document type enumerators](#enumeradores-document-type) | | `signed_url` | string | Signed contract URL for download | - | | `signers` | list | List of signers | - | ## **operation-status enumerators** | Enum | Description | |--------------------------------|----------------------------------------------------------------| | `waiting_signature` | Waiting for signatures from involved parties. | | `signed` | Signature completed. | | `signature_rejected` | Signature rejected. | | `canceled` | Operation canceled. | ## **document-type enumerators** | Enum | Description | |----------------------------------|------------------------------------------------------------------| | `contract` | Contract identifier. | | `ncom_pre_price` | Commercial note Pre price. | | `ncom_pre_price_days` | Commercial note Pre price days. | | `ncom_pre_sac` | Commercial note Pre sac. | | `ncom_post_sac_cdi` | Commercial note Post sac linked to CDI. | | `ncom_post_sac_ipca` | Commercial note Post sac linked to IPCA. | | `ncom_post_sac_igpm` | Commercial note Post sac linked to IGP-M. | | `ncom_post_price_cdi` | Commercial note Post price linked to CDI. | | `ncom_post_price_ipca` | Commercial note Post price linked to IPCA. | | `ncom_post_price_igpm` | Commercial note Post price linked to IGP-M. | | `ncom_post_price_days_cdi` | Commercial note Post price days linked to CDI. | | `ncom_post_price_days_ipca` | Commercial note Post price days linked to IPCA. | | `ncom_post_price_days_igpm` | Commercial note Post price days linked to IGP-M. | | `subscription_note` | Subscription bulletin. | | `adhesion_term` | Adhesion term. | --- # Query Signature Links via QI SIGN for Operation URL: /en/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign This endpoint allows querying all signature links for a specific operation via QI SIGN, using its unique key. --- ## Query Signature Link for Operation (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signers METHOD GET ### Path Params | Field | Type | Description | Characters | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | ### Query Params | Field | Type | Description | Required | |------------------------|---------|-------------------------------------------------------------------------|----------| | `exclude_qi_signers` | boolean | If `true`, hides QI signers from the response. Default: `false`. | No | --- ### Response STATUS 200 Response Body ```json { "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce", "status": "pending_signature", "documents": [ { "document_type": "adhesion_term", "signers": [ { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Emissor assinante", "email": "emissor@qitech.com.br", "status": "on_signature" }, { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Assinante QI CTVM", "email": "dtvm@qitech.com.br", "status": "on_signature" }, { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Assinante QI TECH", "email": "qi@qitech.com.br", "status": "on_signature" } ] }, { "document_type": "ncom_pre_price", "signers": [ { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Assinante QI TECH", "email": "qi@qitech.com.br", "status": "on_signature" }, { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Emissor assinante", "email": "emissor@qitech.com.br", "status": "on_signature" }, { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Assinante QI CTVM", "email": "dtvm@qitech.com.br", "status": "on_signature" } ] } ] } ``` ### Response Body Params | Field | Type | Description | Max Characters | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `envelope_key` | string | Unique envelope key (UUID v4). | 36 | | `status` | string | Envelope status | [operation status enumerators](#operation-status-enumerators) | `documents` | list | List of envelope documents | - | ### document object | Field | Type | Description | Max Characters | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_type` | string | Document type. | [document type enumerators](#document-type-enumerators) | | `signers` | list | List of signers | - | ### signer object | Field | Type | Description | Max Characters | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_number` | string | Signer's document. | 18 | | `signature_url` | string | Signer's link | - | | `status` | string | Signer's status. | [status enumerators](#status-enumerators) | | `name` | string | Signer's name | - | | `email` | string | Signer's email | - | ## **operation-status Enumerators** | Enum | Description | |--------------------------------|----------------------------------------------------------------| | `waiting_signature` | Waiting for signatures from involved parties. | | `signed` | Signature completed. | | `signature_rejected` | Signature rejected. | | `canceled` | Operation canceled. | ## **status Enumerators** | Enum | Description | |--------------------------------|----------------------------------------------------------------| | `on_signature` | Waiting for signatures from involved parties. | | `analyzed` | Signature completed via API. | | `signed` | Signature completed. | | `signature_rejected` | Signature rejected. | | `canceled` | Operation canceled. | | `created` | Signature created. | | `submitted` | Sent to signer. | | `sending_sign_receipt` | Sending simplified signature dossier. | | `analyzing` | Signers under analysis. | | `completed` | Signature completed. | | `expired` | Signature expired. | | `removed` | Signer removed. | | `failed_waiting_for_manual_fix` | Signature creation failed, manual QI action required. | ## **document-type Enumerators** | Enum | Description | |----------------------------------|------------------------------------------------------------------| | `contract` | Contract identifier. | | `ncom_pre_price` | Pre price commercial note. | | `ncom_pre_price_days` | Pre price days commercial note. | | `ncom_pre_sac` | Pre sac commercial note. | | `ncom_post_sac_cdi` | Post sac commercial note linked to CDI. | | `ncom_post_sac_ipca` | Post sac commercial note linked to IPCA. | | `ncom_post_sac_igpm` | Post sac commercial note linked to IGP-M. | | `ncom_post_price_cdi` | Post price commercial note linked to CDI. | | `ncom_post_price_ipca` | Post price commercial note linked to IPCA. | | `ncom_post_price_igpm` | Post price commercial note linked to IGP-M. | | `ncom_post_price_days_cdi` | Post price days commercial note linked to CDI. | | `ncom_post_price_days_ipca` | Post price days commercial note linked to IPCA. | | `ncom_post_price_days_igpm` | Post price days commercial note linked to IGP-M. | | `subscription_note` | Subscription bulletin. | | `adhesion_term` | Adhesion term. | --- # Consulta dos Documentos da Operação URL: /en/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao Estes endpoints devolvem, em base64, o termo constitutivo e o termo de adesão gerados para a operação. São eles que entregam o arquivo a ser assinado no fluxo de **assinatura externa**: o documento devolvido aqui é exatamente o que a QI Tech gerou na aprovação, e é sobre esses bytes que a assinatura precisa ser calculada. :::warning Atenção Os documentos só existem depois que a operação é aprovada na análise. Antes disso a consulta responde `404`. ::: --- ## Consulta do Termo Constitutivo (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /contract MÉTODO GET --- ## Consulta do Termo de Adesão (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /adhesion_term MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "document_base64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAo..." } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|--------------------------------------------|-----------------| | `document_base64` | string | Conteúdo do documento em base64. | - | --- ## Uso na assinatura externa Decodifique o `document_base64` e assine o arquivo resultante sem reprocessá-lo. A QI Tech compara o resumo SHA-256 do documento com o declarado dentro do `.p7s`, e reabrir o PDF em outra ferramenta para salvá-lo altera esse resumo. O envio da assinatura é feito pelo endpoint de **[envio de documentos assinados](/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados)**. --- # Operation Query by Key URL: /en/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave This endpoint allows querying the complete details of a specific operation using its unique key. --- ## Operation Query (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY METHOD GET ### Path Params | Field | Type | Description | Characters | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74", "operation_type": "commercial_paper", "operation_status": "issued", "backoffice_analysis_status": "approved", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "issuer_onboarding_approved": true, "issue_number": 1, "issue_series": 1, "contract_number": "0000000001", "issue_date": "2025-02-03", "financial_base_date": "2025-02-03", "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9", "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8", "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f", "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c", "envelope_signature_status": "signed", "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b", "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a", "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files", "financial": { "financial_base_date": "2025-02-03", "issue_quantity": 1000000, "unit_price": 1.0, "issue_amount": 1000000.0, "released_amount": 1000000.0, "cet": 5.0, "annual_cet": 79.59, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0016053474, "annual_rate": 0.795856326, "monthly_rate": 0.05, "interest_base": "calendar_days_365" }, "fine_delay_rate": { "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "financial_index": null, "post_fixed_interest_rate": null, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 20000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 50000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_number": 1, "workdays": 20, "calendar_days": 30, "principal_amortization_unit_price": 0.18122484, "principal_amortization_amount": 181224.84138231, "interest_amount": 49298.45861769, "amount": 230523.3, "due_principal": 1000000.0, "due_interest": 0.0, "due_date": "2025-03-05", "has_interest": true }, { "installment_number": 2, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.19153595, "principal_amortization_amount": 191535.95353305, "interest_amount": 38987.34646695, "amount": 230523.3, "due_principal": 818775.15861769, "due_interest": 0.0, "due_date": "2025-04-03", "has_interest": true }, { "installment_number": 3, "workdays": 19, "calendar_days": 32, "principal_amortization_unit_price": 0.19748652, "principal_amortization_amount": 197486.52331007, "interest_amount": 33036.77668993, "amount": 230523.3, "due_principal": 627239.20508464, "due_interest": 0.0, "due_date": "2025-05-05", "has_interest": true }, { "installment_number": 4, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.21005991, "principal_amortization_amount": 210059.90840452, "interest_amount": 20463.39159548, "amount": 230523.3, "due_principal": 429752.68177457, "due_interest": 0.0, "due_date": "2025-06-03", "has_interest": true }, { "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.21969277, "principal_amortization_amount": 219692.77337005, "interest_amount": 10830.52662995, "amount": 230523.3, "due_principal": 219692.77337005, "due_interest": 0.0, "due_date": "2025-07-03", "has_interest": true } ] }, "tags": [], "investor_list": [ { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "subscription_percentage": 100.0, "subscription_quantity": 1000000, "investor_onboarding_approved": true, "bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "updated_at": null } ], "related_party_list": [ { "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c", "name": "Blue Logic", "document_number": "97.923.586/0001-06", "role_type": "issuer", "is_active": true, "updated_at": null, "trading_name": "Blue Logic", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5511988887777", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5516982399722", "document_number": "123.456.789-00", "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414" } ] }, { "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30", "name": "Ultimate Cascade", "document_number": "31.424.651/0001-32", "role_type": "investor", "is_active": true, "updated_at": null, "trading_name": "Ultimate Cascade", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5516982399722", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5511988887777", "document_number": "123.456.789-00", "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ] } ], "collateral_list": [ { "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "collateral_type": "real_estate", "collateral_data": { "value": 999 } } ], "metadata_list": [ { "metadata_key": "convenio", "metadata_value": "12398129038" } ], "integralization_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "security_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ``` ### Response Body Params | Field | Type | Description | Max Characters | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `tenant_key` * | string | Unique tenant key (UUID v4). | 36 | | `operation_key` * | string | Unique operation key (UUID v4). | 36 | | `operation_type` * | string | Operation type. `commercial_paper` | - | | `operation_status` * | string | Operation status. | [operation_status enumerators](#operation_status-enumerators) | | `issuer_key` * | string | Unique issuer key (UUID v4). | 36 | | `issuer_name` * | string | Issuer name. | - | | `issuer_document_number` * | string | Issuer document number (CNPJ). | 18 | | `issuer_bank_account` * | object | Issuer banking data. | [bank_account object](#bank_account-object) | | `issuer_onboarding_approved` * | boolean | Indicates if issuer onboarding was approved. | - | | `issue_number` * | integer | Issue number. | - | | `issue_series` * | integer | Issue series. | - | | `contract_number` * | string | Contract number. | - | | `issue_date` * | string | Issue date (ISO 8601 format). | - | | `financial_base_date` * | string | Operation financial base date (ISO 8601 format). | - | | `commercial_paper_template_key` * | string | Unique commercial paper template key. | 36 | | `commercial_paper_document_key` * | string | Commercial paper document key. | - | | `adhesion_term_template_key` * | string | Unique adhesion term template key. | 36 | | `adhesion_term_document_key` * | string | Adhesion term document key. | - | | `investor_list` * | object | Investor list. | [investor object](#investor-object) | ### bank_account object | Field | Type | Description | Max Characters | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_type` * | string | Account type (e.g. checking). | - | | `account_digit` * | string | Bank account digit. | - | | `account_branch` * | string | Bank branch. | - | | `account_number` * | string | Bank account number. | - | | `financial_institution_ispb` * | string | Financial institution ISPB code. | - | | `financial_institution_code_number` * | string | Financial institution code. | - | ### financial object | Field | Type | Description | Max Characters | |-------------------------------------|----------|-----------------------------------------------------------------|-----------------------------------------------------------------| | `financial_base_date` * | string | Operation financial base date (ISO 8601 format). | - | | `issue_quantity` * | integer | Total quantity of issued units. | - | | `unit_price` * | float | Issue unit price. | - | | `issue_amount` * | float | Total issue amount. | - | | `released_amount` * | float | Total released amount. | - | | `cet` * | float | Total Effective Cost of the operation (%). | - | | `annual_cet` * | float | Annualized Total Effective Cost (%). | - | | `number_of_installments` * | integer | Total number of operation installments. | - | | `prefixed_interest_rate` * | object | Prefixed interest rate. | [prefixed_interest_rate object](#prefixed_interest_rate-object) | | `fine_delay_rate` * | object | Delay fine rate | [fine_delay_rate object](#fine_delay_rate-object). | | `contract_fine_rate` * | float | Contractual fine rate (%). | - | | `financial_index` | string | Financial reference index (if exists). | - | | `post_fixed_interest_rate` | object | Post-fixed interest rate (if applicable). | - | | `fees` * | array | List of applicable fees.| [fees object](#fees-object) | | `installment_list` * | array | Installment list. | [installment object](#installment-object) | ### prefixed_interest_rate object | Field | Type | Description | Max Characters | |-----------------------|--------|------------------------------------------------------------|-----------------| | `daily_rate` * | float | Daily interest rate (%). | - | | `annual_rate` * | float | Annualized interest rate (%). | - | | `monthly_rate` * | float | Monthly interest rate (%). | - | | `interest_base` * | string | Interest rate calculation base (`calendar_days_365`). | - | ## fine_delay_rate object | Field | Type | Description | Max Characters | |---------------------|--------|--------------------------------------------------|-----------------| | `monthly_rate` * | float | Monthly delay fine rate (%). | - | | `interest_base` * | string | Interest rate calculation base (`calendar_days_365`). | - | ## fees object | Field | Type | Description | Max Characters | |---------------|---------|------------------------------------------------|-----------------| | `type` * | string | Fee type (`internal`, `external`). | - | | `amount` * | float | Applied fee percentage. | - | | `fee_type` * | string | Fee type. | - | | `fee_amount` * | float | Absolute value of applied fee. | - | | `amount_type` * | string | Value type (`percentage`, `fixed`). | - | ## installment object | Field | Type | Description | Max Characters | |-------------------------------------------|---------|----------------------------------------------------------|-----------------| | `installment_number` * | integer | Installment number. | - | | `workdays` * | integer | Number of business days until maturity. | - | | `calendar_days` * | integer | Number of calendar days until maturity. | - | | `principal_amortization_unit_price` * | float | Principal amortization unit value. | - | | `principal_amortization_amount` * | float | Total principal amortization amount. | - | | `interest_amount` * | float | Total interest amount for the installment. | - | | `amount` * | float | Total installment amount. | - | | `due_principal` * | float | Principal amount due after the installment. | - | | `due_interest` * | float | Interest amount due after the installment. | - | | `due_date` * | string | Installment maturity date (ISO 8601 format). | - | | `has_interest` * | boolean | Indicates if the installment has interest charges. | - | ## investor object | Field | Type | Description | Max Characters | |--------------------------------|---------|----------------------------------------------------------------------|----------------------------------------------| | `investor_key` * | string | Unique investor key (UUID v4). | 36 | | `investor_name` * | string | Investor name. | - | | `investor_document_number` * | string | Investor document number (CNPJ/CPF). | 18 | | `subscription_percentage` * | float | Investor participation percentage in the operation. | - | | `subscription_quantity` * | integer | Number of units subscribed by the investor. | - | | `investor_onboarding_approved` * | boolean | Indicates if investor onboarding was approved. | - | | `bank_account` * | object | Investor banking information. | [bank_account object](#bank_account-object). | ## **operation_status enumerators** | Enum | Description | |--------------------------------|----------------------------------------------------------------| | `in_filling` | Operation in filling phase. | | `in_analysis` | Operation under analysis. | | `waiting_onboarding_approval` | Waiting for issuer onboarding approval. | | `pending_signature_submission` | Waiting to be sent for signature. | | `waiting_signature` | Waiting for signatures from involved parties. | | `issued` | Operation issued. | | `finished` | Operation completed. | | `signature_rejected` | Signature rejected. | | `onboarding_reproved` | Issuer onboarding rejected. | | `compliance_reproved` | Rejected by compliance. | | `canceled` | Operation canceled. | --- # Operation Query by Filters URL: /en/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros This endpoint allows querying **commercial paper** operations using optional filters. --- ## **Request** ENDPOINT /commercial_paper/operation METHOD GET ### **Query Params** | Field | Type | Description | Required | |----------------------------|----------|-----------------------------------------------|-------------| | `issuer_document_number` | string | Issuer document number (CNPJ). | No | | `investor_document_number` | string | Investor document number (CPF/CNPJ). | No | | `operation_status` | string | Operation status. | **[operation_status enumerators](#operation_status-enumerators)** | No | | `metadata_key` | array | Metadata key. | No | | `metadata_value` | array | Metadata value. | No | --- ## **Response** STATUS 200 Response Body ```json { "data": [ { "tenant_key": "13edaf06-9810-4689-b00b-2367274d1a14", "operation_key": "34bc5da7-89df-467d-93af-ed25184ab72e", "operation_type": "commercial_paper", "operation_status": "in_filling", "backoffice_analysis_status": "waiting_submission_for_analysis", "issuer_key": "7fbe9f89-b9ca-4445-85ac-6098da86bb56", "issuer_name": "Global Networks", "issuer_document_number": "73364815000123", "issue_number": 1, "contract_number": "0000000004" }, { "tenant_key": "13edaf06-9810-4689-b00b-2367274d1a14", "operation_key": "f456ee66-5844-4ebc-b69d-365ce6df7138", "operation_type": "commercial_paper", "operation_status": "in_filling", "backoffice_analysis_status": "waiting_submission_for_analysis", "issuer_key": "7fbe9f89-b9ca-4445-85ac-6098da86bb56", "issuer_name": "Global Networks", "issuer_document_number": "73364815000123", "issue_number": 2, "contract_number": "0000000005" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 2 } } ``` --- ### **Response Body Params** #### **Data Object** | Field | Type | Description | Max Characters | |------------------------------|----------|-----------------------------------------------------------|-----------------| | `tenant_key` * | string | Unique tenant key (UUID v4). | 36 | | `operation_key` * | string | Unique operation key (UUID v4). | 36 | | `operation_type` * | string | Operation type. Will always be `commercial_paper`. | 50 | | `operation_status` * | string | Current operation status. | **[operation_status enumerators](#operation_status-enumerators)** | 50 | | `backoffice_analysis_status` | string | Backoffice analysis status. | 50 | | `issuer_key` * | string | Unique key of the issuer associated with the operation (UUID v4). | 36 | | `issuer_name` * | string | Name of the issuer associated with the operation. | 255 | | `issuer_document_number` * | string | Issuer document number (CNPJ). | 14 | | `issue_number` * | integer | Issue number associated with the operation. | - | | `contract_number` * | string | Contract number associated with the operation. | 20 | #### **Pagination Object** | Field | Type | Description | |-------------------|----------|----------------------------------------------------------| | `current_page` * | integer | Current page of the query. | | `next_page` | integer | Next page, if it exists. | | `rows_per_page` * | integer | Number of records per page. | | `total_pages` * | integer | Total pages available. | | `total_rows` * | integer | Total records found for the applied filters. | --- ## **operation_status enumerators** | Enum | Description | |--------------------------------|----------------------------------------------------------------| | `in_filling` | Operation in filling phase. | | `in_analysis` | Operation under analysis. | | `waiting_onboarding_approval` | Waiting for issuer onboarding approval. | | `pending_signature_submission` | Waiting to be sent for signature. | | `waiting_signature` | Waiting for signatures from involved parties. | | `issued` | Operation issued. | | `finished` | Operation completed. | | `signature_rejected` | Signature rejected. | | `onboarding_reproved` | Issuer onboarding rejected. | | `compliance_reproved` | Rejected by compliance. | | `canceled` | Operation canceled. | --- # Next Issue Number Query by Issuer URL: /en/documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao This endpoint returns the next `issue_number` available for the issuer identified by `issuer_key`. The returned value considers the highest number already used in **non-canceled** operations of the issuer and the internal numbering control in the issuer configuration — the greater of the two is always returned. If no numbering configuration exists yet for the issuer, it is created automatically with `current_issue_number = 1` and that value is returned. --- ## **Request** ENDPOINT /commercial_paper/issuer/ ISSUER-KEY /issue_number METHOD GET ### **Path Params** | Field | Type | Description | Max Characters | |----------------|-------------|----------------------------------------------------------------------------|----------------| | `ISSUER-KEY` * | string/uuid | Unique identifier (UUID v4) of the issuer registered in Issuer Management. | 36 | --- ## **Response** STATUS 200 Response Body ```json { "issue_number": 42 } ``` --- ### **Response Body Params** | Field | Type | Description | Max Characters | |------------------|---------|-------------------------------------------------------------------------------------------------------------------|----------------| | `issue_number` * | integer | Next issue number suggested for a new operation of the issuer. Starts at `1` for issuers with no prior operations or configuration. | - | --- # Send Signed Approval Minutes URL: /en/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao This endpoint allows sending externally signed approval minutes for SA or Cooperative companies to the bookkeeping system by sending a base64 that will be analyzed and approved by the bookkeeper. --- ## Send Signed Operation (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document METHOD POST ### Path Params | Field | Type | Description | Characters | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "sa_minute" } ``` ### Request Body Params | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `contract_type` * | string | Type of signed contract | **[contract_type Enumerators](#contract_type-enumerators)** | | `contract_base64` * | string | Signed approval minutes in base64. | - | ### contract_type Enumerators | Enum | Description | |--------------------|------------------------------------------| | `sa_minute` | Commercial paper issuance approval minutes for **SA** company. | | `cop_minute` | Commercial paper issuance approval minutes for **COOPERATIVE** company. | ### Response The response body is a complete JSON of the updated operation. --- --- # Send Signed Operation Documents URL: /en/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados This endpoint receives the signatures of the formalization documents of operations whose `signature_method` is **client_side**. The issuer signs the documents at its own certificate authority and sends QI Tech only the signature file (`p7s_base64`), without the PDF. :::warning Warning Use this endpoint only for operations whose `signature_method` is **client_side**. In the **QI Sign** and **CertifiQI** flows the contracts are generated and signed by the platform itself. For the approval minutes use the **[approval minutes endpoint](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao)**. ::: --- ## Send Signed Document (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document METHOD POST ### Path Params | Field | Type | Description | Characters | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Unique key of the operation (UUID v4). | 36 | --- ### Request Body Signature of the constitutive term ```json { "contract_type": "commercial_paper", "p7s_base64": "MIIJugYJKoZIhvcNAQcCoIIJqzCCCacC..." } ``` Signature of a collateral ```json { "contract_type": "collateral", "collateral_key": "8f0b6f0a-1a2b-4c3d-9e8f-7a6b5c4d3e2f", "p7s_base64": "MIIJugYJKoZIhvcNAQcCoIIJqzCCCacC..." } ``` ### Request Body Params | Field | Type | Description | Max. Characters | |---------------------|--------|--------------------------------------------------------------------------------------------------------------|-----------------| | `contract_type` * | string | Type of the document being sent. | **[contract_type enumerators](#contract_type-enumerators)** | | `p7s_base64` * | string | CAdES signature in base64, detached or attached. | - | | `collateral_key` | string | Key of the collateral the signature refers to. Required when `contract_type` is `collateral`. | 36 | ### contract_type enumerators | Enum | Description | |---------------------|------------------------------------------------------------------------| | `commercial_paper` | Constitutive term of the commercial paper. | | `adhesion_term` | Adhesion term of the commercial paper. | | `collateral` | Collateral document of the operation. Requires `collateral_key`. | ### Response The response body is the complete JSON of the updated operation. --- ## Signature of the formalization documents The documents become available for download once the operation is approved in the analysis, through the **[operation documents endpoint](/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao)**. Each document accepts a single `.p7s` and is sent in its own request. Once every required document is accepted, the QI Tech signers sign and the operation is issued. :::danger Sign exactly the document you downloaded QI Tech compares the digest (SHA-256) declared inside the `.p7s` with the one of the document generated at approval. Tools that reprocess the PDF before signing, such as reopening and saving or recompressing, change that digest and the signature is rejected with `COM000074`. ::: ## **Errors** The codes below are also described in the [error catalogue](/documentation/escrituracao/catalogo-erros/catalogo-erros). | Code | HTTP | Description | |---------------|--------|------------------------------------------------------------------------------------------| | `COM000072` | 400 | The formalization document requires the signature file and `p7s_base64` was not sent. | | `COM000073` | 400 | The file could not be read as a CMS structure, or exceeds the accepted size. | | `COM000074` | 422 | The signature does not match the document issued by QI Tech. | | `COM000075` | 409 | The document already had a signature accepted. | --- # Send Operation for Analysis URL: /en/documentation/escrituracao/emissao-de-notas/envio-para-analise This endpoint allows changing an operation's status to "in analysis", sending it to the compliance validation process by the bookkeeper. --- ## Send Operation for Analysis (PATCH) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY METHOD PATCH ### Path Params | Field | Type | Description | Characters | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Request Body ```json { "operation_status": "in_analysis" } ``` ### Request Body Params | Field | Type | Description | Required | |--------------------|----------|------------------------------------------------------------|-------------| | `operation_status` | string | Operation status. Must be set to `in_analysis`. | Yes | --- ### Response The response body is a complete JSON of the updated operation. --- --- # Send Operation for Signature URL: /en/documentation/escrituracao/emissao-de-notas/envio-para-assinatura :::warning Warning Operations approved by compliance are automatically sent for signature periodically. This endpoint should only be used to perform an immediate send if necessary. ::: --- ## Send Operation for Signature (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /send_to_signature METHOD POST ### Path Params | Field | Type | Description | Characters | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Request Body No request body is required. --- ### Response The response body is a complete JSON of the updated operation. --- --- # Change Adhesion Term Template URL: /en/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta This endpoint allows changing the Adhesion Term template for a specific operation. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY METHOD PATCH ### **Path Params** | Field | Type | Description | Max Characters | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | --- Request Body ```json { "adhesion_term_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Field | Type | Description | Required | |--------------------------------------|----------|--------------------------------------------------|-------------| | `adhesion_term_template_key` * | string | Unique key of the new template to be used (UUID v4). | Yes | ## Response The response body is a complete JSON of the updated operation. --- # Change Commercial Paper Template URL: /en/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc This endpoint allows changing the Commercial Paper template for a specific operation. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY METHOD PATCH ### **Path Params** | Field | Type | Description | Max Characters | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | --- Request Body ```json { "commercial_paper_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Field | Type | Description | Required | |--------------------------------------|----------|--------------------------------------------------|-------------| | `commercial_paper_template_key` * | string | Unique key of the new template to be used (UUID v4). | Yes | ## Response The response body is a complete JSON of the updated operation. --- # Preview Adhesion Term URL: /en/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao This endpoint allows previewing an Adhesion Term draft for a specific operation using a predefined template. --- ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_adhesion_term METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | Request Body ```json { "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Field | Type | Description | Required | |--------------------------------------|----------|--------------------------------------------------|-------------| | `template_key` * | string | Unique key of the new template to be used (UUID v4). | Yes | ## **Response** STATUS 201 Response Body ```json { "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "document_type": "adhesion_term", "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0" } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |------------------|----------|------------------------------------------------|-----------------| | `operation_key` * | string | Unique operation key (UUID v4). | 36 | | `document_type` * | string | Type of generated document. Will always be `adhesion_term`. | 50 | | `document_base64` * | string | Generated document content, encoded in Base64. | - | --- # Preview Commercial Paper Term URL: /en/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato This endpoint allows generating a Commercial Paper Term draft for a specific operation using a predefined template. --- ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_commercial_paper METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | Request Body ```json { "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Field | Type | Description | Required | |--------------------------------------|----------|--------------------------------------------------|-------------| | `template_key` * | string | Unique key of the new template to be used (UUID v4). | Yes | ## **Response** STATUS 201 Response Body ```json { "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "document_type": "commercial_paper", "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0" } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |------------------|----------|------------------------------------------------|-----------------| | `operation_key` * | string | Unique operation key (UUID v4). | 36 | | `document_type` * | string | Type of generated document. Will always be `commercial_paper`. | 50 | | `document_base64` * | string | Generated document content, encoded in Base64. | - | --- # Introduction to Commercial Paper Issuance URL: /en/documentation/escrituracao/emissao-de-notas/inicio Commercial papers are financial instruments used by companies to raise funds directly in the market. This process involves several stages, from registering issuers and investors, through defining financial conditions, to the formal issuance of securities. Each stage is crucial to ensure regulatory compliance and efficiency in the fundraising process. --- ## Overview of the Issuance Process The commercial paper issuance process is structured in several stages that ensure transparency, security, and control. Below are the main steps of the process: 1. **Issuer and Investor Registration** Companies that want to issue commercial papers and investors interested in acquiring these securities need to be registered in the system. Registration includes detailed information, such as documents and bank accounts. 2. **Operation Conditions Definition** The issuer defines the financial conditions of the operation, including interest rates, number of installments, issuance and maturity dates, as well as any fees and charges. 3. **Simulation** Before formal issuance, a simulation is performed to calculate issuance values, installment flow, and other financial details. This stage allows adjusting operation conditions according to the needs of issuers and investors. 4. **Related Parties Registration and Documentation** Includes registering involved parties, such as guarantors and co-obligors, and sending relevant documents, such as contracts and terms. 5. **Document Generation and Signing** Drafts of main documents are generated, such as the **Adhesion Term** and **Constitutive Term**. After approval, documents are sent for electronic signature. 6. **Submission for Analysis and Approval** The operation is submitted for compliance and back-office analysis, ensuring that all regulatory and contractual requirements are met. 7. **Formal Issuance and Registration** After approval, commercial papers are formally issued and made available to investors. Starting from the next pages, we will explore in detail each stage of the commercial paper issuance process, including endpoints and practical examples to integrate your system with the API. --- # Financial Conditions Simulation URL: /en/documentation/escrituracao/emissao-de-notas/simulacao This endpoint allows simulating the financial conditions and payment flow of an operation. --- ## Request ENDPOINT /commercial_paper/simulation METHOD POST ### Request Body **Released Amount** ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-01-20", "released_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ] } ``` **Informing Installments** ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-01-20", "number_of_installments": 2, "installments": [ { "due_date": "2026-01-01", "amount": 500000 }, { "due_date": "2026-02-01", "amount": 502004.01 } ], "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "bookkeeping_fee" } ], } ``` ### Request Body Params | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_type` * | string | Applied interest type. | **[interest_type Enumerators](#interest_type-enumerators)** | | `financial_base_date` * | string | Operation base date (format "YYYY-MM-DD"). | - | | `released_amount` * | number | Total amount released in the operation. | - | | `number_of_installments` * | integer | Total number of installments. | - | | `prefixed_interest_rate` * | object | Object containing prefixed interest rate details. | **[prefixed_interest_rate Object](#prefixed_interest_rate-object)** | | `fine_delay_rate` * | object | Object containing delay fine details. | **[fine_delay_rate Object](#fine_delay_rate-object)** | | `contract_fine_rate` * | number | Contractual fine applied in percentage. | - | | `fees` | array | List of fees associated with the operation. | **[fees Object](#fees-object)** | ### prefixed_interest_rate Object | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Calculation base for interest. | **[interest_base Enumerators](#interest_base-enumerators)** | | `monthly_rate` * | number | Applied monthly interest rate. | - | ### fine_delay_rate Object | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Base for fine calculation. | **[interest_base Enumerators](#interest_base-enumerators)** | | `monthly_rate` * | number | Monthly fine rate. | - | ### fees Object | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `amount` * | number | Applied fee value. | - | | `amount_type` * | string | Fee value type. | **[amount_type Enumerators](#amount_type-enumerators)** | | `fee_type` * | string | Fee type. | **[fee_type Enumerators](#fee_type-enumerators)** | | `type` * | string | Fee recipient. | **[fee_recipient Enumerators](#fee_recipient-enumerators)** | ### interest_type Enumerators | Enum | Description | |--------------------|------------------------------------------| | `pre_price` | Prefixed interest in Price model. | | `pre_price_days` | Prefixed interest in Price model by calendar days. | | `pre_sac` | Prefixed interest in SAC model. | | `post_sac` | Post-fixed interest in SAC model. | ### interest_base Enumerators | Enum | Description | |--------------------|------------------------------------------| | `calendar_days` | Calendar days base. | | `calendar_days_365`| 365 calendar days base. | | `workdays` | Business days base. | ### amount_type Enumerators | Enum | Description | |-------------|---------------------------| | `percentage` | Percentage value. | | `absolute` | Absolute value in currency. | ### Enumeradores fee_type | Enum | Descrição | |-------------------------------------|-------------------------------------------| | `bookkeeping_fee` | Taxa de escrituração financiada. | | `structuring_fee` | Taxa de estruturação financiada. | ### fee_recipient Enumerators | Enum | Description | |-----------|-------------------------------------------------------| | `internal` | Fee paid to the bookkeeper. | | `external` | Rebate paid to the originator. | ## Response STATUS 200 Response Body ```json { "financial_base_date": "2025-01-20", "issue_amount": 1075268.82, "released_amount": 1000000.0, "issue_quantity": 1075268, "unit_price": 1.00000076, "cet": 7.7, "annual_cet": 143.55, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }, { "amount": 5.0, "fee_amount": 53763.44, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ], "installments": [ { "installment_number": 1, "workdays": 23, "calendar_days": 31, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 0.17976244, "interest_amount": 54820.37344366, "amount": 248113.17, "due_principal": 1075268.82, "due_interest": 0.0, "due_date": "2025-02-20", "has_interest": true }, { "installment_number": 2, "workdays": 18, "calendar_days": 28, "principal_amortization_amount": 207597.32873049, "principal_amortization_unit_price": 0.19306566, "interest_amount": 40515.84126951, "amount": 248113.17, "due_principal": 881976.02344366, "due_interest": 0.0, "due_date": "2025-03-20", "has_interest": true }, { "installment_number": 3, "workdays": 21, "calendar_days": 33, "principal_amortization_amount": 211453.91638185, "principal_amortization_unit_price": 0.19665229, "interest_amount": 36659.25361815, "amount": 248113.17, "due_principal": 674378.69471317, "due_interest": 0.0, "due_date": "2025-04-22", "has_interest": true }, { "installment_number": 4, "workdays": 19, "calendar_days": 28, "principal_amortization_amount": 226847.52746545, "principal_amortization_unit_price": 0.21096836, "interest_amount": 21265.64253455, "amount": 248113.17, "due_principal": 462924.77833132, "due_interest": 0.0, "due_date": "2025-05-20", "has_interest": true }, { "installment_number": 5, "workdays": 22, "calendar_days": 31, "principal_amortization_amount": 236077.25086587, "principal_amortization_unit_price": 0.21955201, "interest_amount": 12035.91913413, "amount": 248113.17, "due_principal": 236077.25086587, "due_interest": 0.0, "due_date": "2025-06-20", "has_interest": true } ], "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02 } ``` ### Response Body Params | Field | Type | Description | Max Characters | |------------------------------|----------|---------------------------------------------------------------------------------------------------------|-----------------| | `financial_base_date` * | string | Operation financial base date (format "YYYY-MM-DD"). | - | | `issue_amount` * | number | Total issued amount of the operation. | - | | `released_amount` * | number | Net amount released in the operation. | - | | `issue_quantity` * | integer | Total quantity of units issued. | - | | `unit_price` * | number | Unit price of the issuance. | - | | `cet` * | number | Total Effective Cost (CET) in percentage. | - | | `annual_cet` * | number | Annual CET in percentage. | - | | `number_of_installments` * | integer | Total number of installments. | - | | `prefixed_interest_rate` * | object | Object containing prefixed interest rate details. | **[prefixed_interest_rate Object](#prefixed_interest_rate-object)** | | `fees` | array | List of fees associated with the operation. | **[fees Object](#fees-object)** | | `installments` | array | List of installment details generated in the operation. | **[installments Object](#installments-object)** | | `fine_delay_rate` * | object | Object containing delay fine details. | **[fine_delay_rate Object](#fine_delay_rate-object)** | | `contract_fine_rate` * | number | Contractual fine applied in percentage. | - | ### prefixed_interest_rate Object | Field | Type | Description | Max Characters | |---------------|----------|------------------------------------------------------------|-----------------| | `interest_base` * | string | Calculation base for interest. | **[interest_base Enumerators](#interest_base-enumerators)** | | `monthly_rate` * | number | Applied monthly interest rate. | - | | `daily_rate` * | number | Applied daily interest rate. | - | | `annual_rate` * | number | Applied annual interest rate. | - | ### fees Object | Field | Type | Description | Max Characters | |------------|--------|------------------------------------------------------------|-----------------| | `amount` * | number | Percentage value of the fee. | - | | `fee_amount` * | number | Monetary value corresponding to the fee. | - | | `amount_type` * | string | Fee value type. | **[amount_type Enumerators](#amount_type-enumerators)** | | `fee_type` * | string | Fee type. | **[fee_type Enumerators](#fee_type-enumerators)** | | `type` * | string | Fee recipient. | **[fee_recipient Enumerators](#fee_recipient-enumerators)** | ### installments Object | Field | Type | Description | |----------------------------|----------|--------------------------------------------------------| | `installment_number` * | integer | Installment number. | | `workdays` * | integer | Business days until installment due date. | | `calendar_days` * | integer | Calendar days until installment due date. | | `principal_amortization_amount` * | number | Principal amortized amount. | | `principal_amortization_unit_price` * | number | Amortized amount per unit. | | `interest_amount` * | number | Interest amount applied in the installment. | | `amount` * | number | Total installment amount. | | `due_date` * | string | Installment due date (format "YYYY-MM-DD"). | --- # Register Debenture Operation URL: /en/documentation/escrituracao/emissao-debentures/cadastro-operacao This endpoint creates a complete Debenture operation in a single request. :::info The `financial` object is **required** and must be sent already calculated, as this endpoint does not run the financial simulation. The issuer and its bank account must be previously registered. ::: --- ## **Request** ENDPOINT /debenture/create_operation METHOD POST The request body ranges from a **payload with the required fields** (including the financial object) to a **complete payload** that also includes related parties. See both variations below. Payload with the required fields ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "issue_date": "2025-01-20", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] } } ``` Complete payload (with related parties) ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "contract_number": "DEB-2025-0001", "issue_date": "2025-01-20", "signature_method": "certifiqi", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] }, "related_party_list": [ { "person_type": "legal", "name": "Garantidora S.A.", "document_number": "12.345.678/0001-90", "trading_name": "Garantidora", "cnae_code": "64.62-0-00", "company_type": "sa", "foundation_date": "2010-05-01", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "postal_code": "01310-100", "city": "São Paulo", "state": "SP", "role_type": "guarantor" }, { "person_type": "natural", "name": "João da Silva", "document_number": "123.456.789-00", "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "solidary_debtor", "is_pep": false } ] } ``` ### **Request Body Params** | Field | Type | Description | Max Characters | | ------------------- | ------- | --------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Unique tenant key. | - | | `issuer_key` * | string | Unique issuer key (previously registered). | - | | `issue_number` * | integer | Issue number. | - | | `issue_series` * | integer | Issue series. | - | | `issue_date` * | string | Operation issue date (format "YYYY-MM-DD"). | - | | `signature_method` | string | Signature method used in the operation. Optional; when omitted, defaults to `certifiqi`. | **[signature_method Enumerators](#signature_method-enumerators)** | | `investors` * | array | List of involved investors. | **investors Object** | | `financial` * | object | Already-calculated operation financial data. | **financial Object** | | `contract_number` | string | Contract number. | - | | `related_party_list` | array | Operation related parties (guarantors, debtors, etc.). | **related_party Object** | ### investors Object | Field | Type | Description | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Unique investor key (previously registered). | | `bank_account` * | object | Investor bank account (**bank_account Object**). | | `subscription_percentage` | number | Subscription percentage. | | `subscription_quantity` | number | Subscribed quantity. | ### bank_account Object | Field | Type | Description | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Bank account number. | | `account_digit` * | string | Bank account digit. | | `account_branch` * | string | Bank account branch. | | `financial_institution_code_number` | string | Financial institution code. | | `financial_institution_ispb` * | string | Financial institution ISPB code. | | `account_type` * | string | Account type (`checking`, `savings`, `salary`, `payment`). | ### financial Object | Field | Type | Description | | --------------------------- | ------- | -------------------------------------------- | | `financial_base_date` * | string | Financial base date (format "YYYY-MM-DD"). | | `interest_type` * | string | Interest type. | | `issue_amount` | number | Total issued amount. | | `issue_quantity` | integer | Quantity of issued units. | | `unit_price` | number | Unit price of the issuance. | | `released_amount` | number | Net released amount. | | `cet` / `annual_cet` | number | Total Effective Cost (monthly and annual), in percentage. | | `number_of_installments` * | integer | Number of installments. | | `prefixed_interest_rate` * | object | Prefixed interest rate. | | `fine_delay_rate` | object | Delay fine rate. | | `contract_fine_rate` | number | Contractual fine in percentage. | | `fees` | array | List of fees. | | `installments` | array | List of already-calculated installments. | ### related_party Object Each item in `related_party_list` represents a party involved in the operation. | Field | Type | Description | | ----------------- | ------- | ------------------------------------------------------------ | | `person_type` * | string | Person type (`natural` for individuals, `legal` for companies). | | `name` * | string | Related party name. | | `document_number` * | string | CPF (individual) or CNPJ (company). | | `role_type` * | string | Party role in the operation. **[role_type Enumerators](#role_type-enumerators)** | | `street` * | string | Street. | | `number` * | string | Address number. | | `neighborhood` | string | Neighborhood. | | `postal_code` * | string | Postal code (format "00000-000"). | | `city` * | string | City. | | `state` * | string | State (2 letters). | | `complement` | string | Address complement. | | `is_pep` | boolean | (Individual) Whether the person is a Politically Exposed Person. | | `marital_status` | string | (Individual) Marital status. | | `property_system` | string | (Individual) Property regime. | | `birthdate` | string | (Individual) Date of birth. | | `mother_name` | string | (Individual) Mother's name. | | `occupation` | string | (Individual) Occupation. | | `trading_name` | string | (Company) Trading name. | | `cnae_code` | string | (Company) CNAE code (format "00.00-0-00"). | | `company_type` | string | (Company) Company type. | | `foundation_date` | string | (Company) Foundation date. | :::warning Attention Required fields vary by `person_type`: - **Individual (`natural`)**: in addition to the common fields, `is_pep` is required. - **Company (`legal`)**: in addition to the common fields, `trading_name`, `cnae_code`, `company_type` and `foundation_date` are required. ::: ### role_type Enumerators | Enum | Description | |------|-------------| | `issuer` | Issuer. | | `investor` | Investor. | | `cosigner` | Co-obligor. | | `fiduciary_debtor` | Fiduciary debtor. | | `solidary_debtor` | Joint debtor. | | `guarantor` | Guarantor (aval). | | `bonafide_depositary` | Bona fide depositary. | | `intervening_guarantor` | Intervening guarantor. | | `intervening_consentor` | Intervening consentor. | | `intervening_discharger` | Intervening discharger. | | `assignor` | Assignor. | | `endorser` | Endorser. | | `consulting` | Consulting. | | `fund_administrator` | Fund administrator. | | `fund_representative` | Fund representative. | | `company_representative` | Company representative. | | `attestant` | Attestant. | | `debtor` | Debtor. | | `bestowal` | Grantor. | | `manager` | Manager. | :::tip Collateral and underlying assets are sent through a **separate endpoint**, after the operation is created. See the **Send collateral** page in this section. ::: ### signature_method Enumerators | Enum | Description | |------|-------------| | `certifiqi` | Default value. The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). | | `qi_sign` | The operation is sent to the signature service; a signature envelope is created and the client receives the signature URL (`signature_url`). Also allows querying the operation's signers. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "finished", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "issue_number": 10, "issue_series": 1, "related_party_list": [ ... ], "financial": { ... } } ``` The response returns the complete JSON of the created operation, including `operation_key`, the investor and related-party lists, and the calculated financial object. --- # Send Document URL: /en/documentation/escrituracao/emissao-debentures/envio-documento This endpoint **uploads a document** and returns the `document_key` that identifies it. This `document_key` is used to reference documents in other endpoints — for example, the `collateral_document_key` and the `additional_documents` of [Send collateral](./envio-garantia.md). --- ## **Request** ENDPOINT /debenture/upload METHOD POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Field | Type | Description | Required | |-------------------|--------|------------------------------------------|----------| | `document_base64` * | string | Base64 encoded content of the document. | Yes | | `document_name` | string | Document name. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |----------------|--------|----------------------------------------|----------------| | `document_key` * | string | Unique key of the uploaded document (UUID v4). | 36 | --- --- # Send Operation External Document URL: /en/documentation/escrituracao/emissao-debentures/envio-documento-externo This endpoint allows sending externally signed documents to the bookkeeping system by sending a base64 that will be analyzed and approved by the bookkeeper. :::warning Warning This endpoint should only be used for operations that use the **client_side** signature type or for sending the approval minutes for SA or Cooperative companies. For the flow via QI Sign or Certifiqi, contracts are generated normally. ::: --- ## Send Signed Document (POST) ### Request ENDPOINT /debenture/operation/ OPERATION-KEY /upload_signed_document METHOD POST ### Path Params | Field | Type | Description | Characters | |-----------------|--------|-------------------------------------|------------| | `OPERATION-KEY` | string | Unique operation key (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "debenture" } ``` ### Request Body Params | Field | Type | Description | Max Characters | |---------------------|--------|----------------------------|------------------------------------------------------------| | `contract_type` * | string | Type of signed document. | **[contract_type Enumerators](#contract_type-enumerators)** | | `contract_base64` * | string | Signed document in base64. | - | ### contract_type Enumerators | Enum | Description | |---------------------|--------------------------------------------| | `debenture` | Debenture issuance deed. | | `adhesion_term` | Debenture adhesion term. | | `sa_minute` | Debenture issuance approval minutes for **SA** company. | | `ltda_minute` | Debenture issuance approval minutes for **LTDA** company. | | `cop_minute` | Debenture issuance approval minutes for **Cooperative**. | ### Response The response body is a complete JSON of the updated operation. --- --- # Send Operation Collateral URL: /en/documentation/escrituracao/emissao-debentures/envio-garantia This endpoint allows **adding collateral** to a Debenture operation. The collateral is submitted for signature together with the operation documents. Each collateral type (`collateral_type`) has its own required-document rules, listed below. :::info Where `document_key` comes from The `collateral_document_key` and `document_key` (in `additional_documents`) reference previously uploaded documents. Each key is obtained from the [Send document](./envio-documento.md) endpoint (`POST /debenture/upload`), which receives the file in Base64 and returns the corresponding `document_key`. ::: --- ## **Request** ENDPOINT /debenture/operation/ OPERATION-KEY /collateral METHOD POST ### Path Params | Field | Type | Description | Characters | |-------|------|-------------|------------| | `OPERATION-KEY` * | string | Unique operation key (UUID v4). | 36 | --- ## Collateral types :::warning Documents marked as **required** are mandatory for the respective collateral type. ::: ### Fiduciary alienation of property (`fiduciary_alienation_property`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_property", "additional_documents": [ { "document_type": "property_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_registration_updated", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_full_content_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `property_appraisal_report` | Property appraisal report. | Yes | | `property_registration_updated` | Updated property registration. | Yes | | `property_full_content_certificate` | Full content certificate of registration. | Yes | | `property_insurance_policy` | Insurance policy (if required by contract). | - | | `others` | Other documents. | - | ### Fiduciary alienation of vehicle (`fiduciary_alienation_vehicle`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_vehicle", "additional_documents": [ { "document_type": "vehicle_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "vehicle_inspection_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "vehicle_crv_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `vehicle_appraisal_report` | Vehicle appraisal report or FIPE table. | Yes | | `vehicle_inspection_report` | Inspection report. | Yes | | `vehicle_crv_certificate` | Updated vehicle registration certificate (CRLV). | Yes | | `others` | Other documents. | - | ### Fiduciary alienation of aircraft (`fiduciary_alienation_aircraft`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_aircraft", "additional_documents": [ { "document_type": "aircraft_certificate_anac", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "aircraft_rab_consult", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "aircraft_insurance_policy", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "aircraft_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `aircraft_certificate_anac` | Registration certificate - ANAC. | Yes | | `aircraft_rab_consult` | Brazilian Aeronautical Registry (RAB) consultation. | Yes | | `aircraft_insurance_policy` | Insurance policy - fund as beneficiary. | Yes | | `aircraft_appraisal_report` | Aircraft appraisal report. | Yes | | `others` | Other documents. | - | ### Fiduciary alienation of equipment/products/inventory (`fiduciary_alienation_equipment`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_equipment", "additional_documents": [ { "document_type": "equipment_purchase_invoice", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "equipment_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `equipment_purchase_invoice` | Purchase invoice. | Yes | | `equipment_appraisal_report` | Equipment appraisal report. | Yes | | `equipment_insurance_policy` | Equipment insurance policy (if required). | - | | `fiduciary_depositary_declaration` | Bona fide depositary declaration. | - | | `others` | Other documents. | - | ### Fiduciary alienation of artwork (`fiduciary_alienation_artwork`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_artwork", "additional_documents": [ { "document_type": "artwork_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "artwork_storage_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `artwork_appraisal_report` | Artwork appraisal report. | Yes | | `artwork_storage_certificate` | Storage location adequacy certificate. | Yes | | `artwork_insurance_policy` | Insurance policy (if required). | - | | `others` | Other documents. | - | ### Fiduciary alienation of securities (`fiduciary_alienation_securities`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_securities", "additional_documents": [ { "document_type": "securities_negotiation_block", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `securities_negotiation_block` | Trading block at the custodian. | Yes | | `securities_registration_gravame` | Lien registration. | - | | `others` | Other documents. | - | ### Fiduciary assignment of shares/quotas (`fiduciary_assignment_shares`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_assignment_shares", "additional_documents": [ { "document_type": "share_registration_book", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `share_registration_book` | Registered shares book with lien annotation. | Yes | | `others` | Other documents. | - | ### Property mortgage (`mortgage_property`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "mortgage_property", "additional_documents": [ { "document_type": "property_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_registration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_full_content_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `property_appraisal_report` | Property appraisal report. | Yes | | `property_registration` | Updated property record. | Yes | | `property_full_content_certificate` | Full content certificate of registration. | Yes | | `property_insurance_policy` | Insurance policy (if required by contract). | - | | `others` | Other documents. | - | ### Ship mortgage (`mortgage_ship`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "mortgage_ship", "additional_documents": [ { "document_type": "ship_registration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "ship_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `ship_registration` | Updated ship ownership record. | Yes | | `ship_appraisal_report` | Ship appraisal report. | Yes | | `ship_insurance_policy` | Ship insurance policy (if required). | - | | `others` | Other documents. | - | ### Guaranty (aval) (`guarantor`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "guarantor", "additional_documents": [ { "document_type": "guarantor_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `guarantor_civil_status_declaration` | Guarantor civil status declaration. | Yes | | `guarantor_personal_document` | Guarantor personal document. | - | | `guarantor_income_tax_declaration` | Guarantor income tax declaration. | - | | `others` | Other documents. | - | ### Surety (`surety`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "surety", "additional_documents": [ { "document_type": "surety_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "surety_personal_document", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "surety_income_tax_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `surety_civil_status_declaration` | Surety civil status declaration. | Yes | | `surety_personal_document` | Surety personal document. | Yes | | `surety_income_tax_declaration` | Surety income tax declaration. | Yes | | `others` | Other documents. | - | ### Insurance (`insurance`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "insurance", "additional_documents": [ { "document_type": "insurance_policy_endorsed", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "insurance_policy_with_expiration_and_renewal", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `insurance_policy_endorsed` | Endorsed insurance policy. | Yes | | `insurance_policy_with_expiration_and_renewal` | Insurance policy with expiration and renewal. | Yes | | `others` | Other documents. | - | ### Guarantee monitoring (`monitoring_guarantee`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "monitoring_guarantee", "additional_documents": [ { "document_type": "guarantee_contract", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "guarantee_agent_contract", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Document types | Enum | Description | Required | |------|-------------|----------| | `guarantee_contract` | Guarantee contract. | Yes | | `guarantee_agent_contract` | Guarantee agent contract. | Yes | | `others` | Other documents. | - | --- ## Request Body Params | Field | Type | Description | Required | |-------|------|-------------|----------| | `collateral_document_key` * | string | Key of the collateral instrument document. | Yes | | `collateral_type` * | string | Collateral type. | **[collateral_type Enumerators](#collateral_type-enumerators)** | | `additional_documents` | array | Additional collateral documents. | - | ### additional_documents | Field | Type | Description | Required | |-------|------|-------------|----------| | `document_key` * | string | Document key. | Yes | | `document_type` * | string | Document type. | Yes | ### collateral_type Enumerators | Enum | Description | |------|-------------| | `fiduciary_alienation_property` | Fiduciary alienation of property. | | `fiduciary_alienation_vehicle` | Fiduciary alienation of vehicle. | | `fiduciary_alienation_aircraft` | Fiduciary alienation of aircraft. | | `fiduciary_alienation_equipment` | Fiduciary alienation of equipment/products/inventory. | | `fiduciary_alienation_artwork` | Fiduciary alienation of artwork. | | `fiduciary_alienation_securities` | Fiduciary alienation of securities. | | `fiduciary_assignment_shares` | Fiduciary assignment of shares/quotas. | | `mortgage_property` | Property mortgage. | | `mortgage_ship` | Ship mortgage. | | `guarantor` | Guaranty (aval). | | `surety` | Surety. | | `insurance` | Insurance. | | `monitoring_guarantee` | Guarantee monitoring. | | `bank_surety` | Bank surety. | | `fiduciary_assignment_credit_rights` | Fiduciary assignment of credit rights. | | `card_receivables` | Card receivables. | | `stock_guarantee` | Inventory guarantee. | | `others` | Other collaterals. | ## Response The response body is a complete JSON of the updated operation, with the new collateral in `collateral_list`. --- --- # Issuer Registration Update URL: /en/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/ To make changes to the Issuer registration, it is necessary that its status be set to "in_filling", this will re-enable all inclusion/removal endpoints. After making the modifications, the registration must be sent again for analysis with the status "in_analysis". --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY METHOD PATCH ### Path Params | Field | Type | Description | Characters | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | ### Request Body Request Body ```json { "issuer_status": "in_filling" } ``` ### Request Body Params | Field | Type | Description | Required | | ------------------ | ------ | ---------------------------------------------------- | ------------ | | `issuer_status`* | string | New issuer status. Accepted value:`in_filling`. | Yes | ## Response The response is a complete updated JSON of the issuer. --- # Consulta da Auto-assinatura URL: /en/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura Este endpoint permite consultar a auto-assinatura ativa de um emissor — status atual, dados do termo de adesão e histórico de eventos. Os links de assinatura de cada assinante ficam em um endpoint próprio: [consulta dos links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura). Consulte o [fluxo da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) para entender como a habilitação é criada e quais são os status possíveis. --- ## Consulta da Auto-assinatura (GET) ### Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|-----------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | --- ### Response STATUS 200 Response Body — aguardando assinatura do termo ```json { "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "pending_signature", "signed_at": null, "enabled_at": null, "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "created_at": "2026-02-10T09:15:44", "event_list": [ { "event_type": "auto_signature_creation", "status": "pending_term_generation", "event_data": { "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154" }, "created_at": "2026-02-10T09:15:44" }, { "event_type": "adhesion_term_generation", "status": "pending_term_generation", "event_data": { "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "template_key": "b71f1a2c-9e44-4c1d-8f3a-6d2c0b5e7a19" }, "created_at": "2026-02-10T09:16:02" }, { "event_type": "envelope_creation", "status": "pending_signature", "event_data": { "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34" }, "created_at": "2026-02-10T09:16:03" } ] } ``` Response Body — termo assinado (habilitado) ```json { "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "enabled", "signed_at": "2026-02-11T14:02:31", "enabled_at": "2026-02-11T14:02:31", "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "created_at": "2026-02-10T09:15:44", "event_list": [ { "event_type": "signature_webhook_received", "status": "pending_signature", "event_data": { "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "envelope_status": "signed" }, "created_at": "2026-02-11T14:02:31" }, { "event_type": "auto_signature_status_change", "status": "enabled", "event_data": { "status": "enabled" }, "created_at": "2026-02-11T14:02:31" } ] } ``` --- ### Response Body Params | Campo | Tipo | Descrição | |-----------------------------|--------|--------------------------------------------------------------------------------------------------------------| | `issuer_auto_signature_key` | string | Chave única da auto-assinatura. | | `status` | string | Status atual: `pending_term_generation`, `pending_signature`, `enabled`, `reproved` ou `canceled`. | | `signed_at` | string | Data e hora da assinatura do termo. `null` enquanto o termo não é assinado. | | `enabled_at` | string | Data e hora da habilitação. `null` enquanto o status não é `enabled`. | | `issuer_key` | string | Chave única do emissor. | | `term_document_key` | string | Caminho do documento do termo de adesão gerado. | | `envelope_key` | string | Chave única do envelope de assinatura do termo. | | `created_at` | string | Data e hora de criação da auto-assinatura. | | `event_list` | array | Histórico de eventos da auto-assinatura, em ordem cronológica. | **Campos de `event_list`:** | Campo | Tipo | Descrição | |--------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `event_type` | string | Tipo do evento: `auto_signature_creation`, `adhesion_term_generation`, `adhesion_term_generation_failure`, `envelope_creation`, `envelope_creation_failure`, `signature_webhook_received` ou `auto_signature_status_change`. | | `status` | string | Status da auto-assinatura no momento do evento. | | `event_data` | object | Dados do evento. O conteúdo varia conforme o `event_type`. | | `created_at` | string | Data e hora do evento. | --- ### Erros | HTTP | Código | Quando ocorre | |------|---------------------------------------|-----------------------------------------------------------------------------------------------------| | 403 | `ISS000011` (`TenantForbidden`) | O cliente não possui acesso completo ao cadastro do emissor informado. | | 404 | `ISS000009` (`IssuerNotFound`) | Não existe emissor para a chave informada. | | 404 | `ISS0000028` (`AutoSignatureNotFound`)| O emissor não possui auto-assinatura ativa. | :::info Auto-assinaturas encerradas A consulta retorna apenas a auto-assinatura **ativa** — aquela em `pending_term_generation`, `pending_signature` ou `enabled`. Depois que uma auto-assinatura vai para `reproved` ou `canceled`, este endpoint responde `ISS0000028` até que uma nova habilitação seja criada. O último estado conhecido continua visível no campo `auto_signature` da [consulta do emissor](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave). ::: --- # Consulta dos Links de Assinatura do Termo de Adesão URL: /en/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura Este endpoint retorna **um link de assinatura por assinante** do termo de adesão da auto-assinatura, com o status individual de cada um. Cada assinante do emissor assina pelo seu próprio link. Os links ficam disponíveis assim que a [solicitação da habilitação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) responde — é ela que abre o envelope e leva a auto-assinatura a `pending_signature`. Se a geração do termo tiver falhado, a auto-assinatura fica em `pending_term_generation`, sem envelope, e este endpoint responde `ISS0000030` até que a solicitação seja repetida. --- ## Consulta dos Links de Assinatura (GET) ### Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature/signers MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------ | ------ | --------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Query Params | Campo | Tipo | Descrição | Obrigatório | | -------------------- | ------- | ------------------------------------------------------------------------------ | ----------- | | `exclude_qi_signers` | boolean | Se `true`, oculta da resposta os assinantes que são da QI. Padrão: `false`. | Não | --- ### Response STATUS 200 Response Body ```json { "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "pending_signature", "documents": [ { "document_type": "adhesion_auto_signature_term", "signers": [ { "document_number": "123.456.789-01", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Joao da Silva", "email": "joao.silva@example.com", "status": "on_signature" }, { "document_number": "987.654.321-00", "signature_url": "https://sign.qitech.com.br/s/f7Kd91P", "name": "Maria de Souza", "email": "maria.souza@example.com", "status": "signed" }, { "document_number": "421.820.518-30", "signature_url": "https://sign.qitech.com.br/s/q1W2e3R", "name": "Assinante QI CTVM", "email": "assinaturas.estruturadas@qitech.com.br", "status": "on_signature" } ] } ], "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34" } ``` --- ### Response Body Params | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------------------- | | `envelope_key` | string | Chave única do envelope de assinatura do termo de adesão. | | `status` | string | Status do envelope no QI SIGN. | | `documents` | array | Documentos do envelope. O termo de adesão é o único documento. | | `issuer_key` | string | Chave única do emissor. | | `issuer_auto_signature_key` | string | Chave única da auto-assinatura. | **Campos de `documents`:** | Campo | Tipo | Descrição | | --------------- | ------ | ------------------------------------------------------------ | | `document_type` | string | Sempre `adhesion_auto_signature_term`. | | `signers` | array | Assinantes do documento, um item por assinante. | **Campos de `signers`:** | Campo | Tipo | Descrição | | ----------------- | ------ | ------------------------------------------------------------------------------ | | `document_number` | string | CPF do assinante. | | `signature_url` | string | Link individual de assinatura desse assinante. | | `name` | string | Nome do assinante. | | `email` | string | E-mail do assinante. | | `status` | string | Status individual da assinatura — por exemplo `on_signature` ou `signed`. | --- ### Erros | HTTP | Código | Quando ocorre | | ---- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | 400 | `ISS0000030` (`AutoSignatureInWrongStatus`) | O termo de adesão ainda não foi enviado para assinatura — a auto-assinatura está em `pending_term_generation`. | | 403 | `ISS000011` (`TenantForbidden`) | O cliente não possui acesso completo ao cadastro do emissor informado. | | 404 | `ISS000009` (`IssuerNotFound`) | Não existe emissor para a chave informada. | | 404 | `ISS0000028` (`AutoSignatureNotFound`) | O emissor não possui auto-assinatura ativa. | --- # Auto-assinatura do Emissor URL: /en/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio A auto-assinatura permite que a QI Tech assine automaticamente, em nome do emissor, os documentos das emissões seguintes — sem que um representante precise assinar operação por operação. Para isso, o emissor assina **uma única vez** um **termo de adesão à auto-assinatura**. Enquanto esse termo não estiver assinado, as emissões continuam seguindo o fluxo normal de assinatura manual. :::info Habilitação por cliente A auto-assinatura não vem habilitada por padrão. Ela é configurada pela QI Tech por cliente (`tenant`), incluindo o template do termo de adesão utilizado. Para habilitar, entre em contato com o time [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br). ::: --- ## Pré-requisitos | Pré-requisito | Como é atendido | |---------------|-----------------| | Cliente habilitado para auto-assinatura | Configurado pela QI Tech, com o template do termo de adesão | | Emissor com cadastro **aprovado** | Fluxo normal de [homologação do emissor](/documentation/escrituracao/homologacao-emissor/inicio) | | Emissor com **grupo de assinantes** ativo | [Cadastro de assinantes do emissor](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) | O grupo de assinantes cadastrado no emissor é exatamente quem assina o termo de adesão. Se ele estiver vazio ou desatualizado no momento da aprovação, corrija o cadastro antes de prosseguir. --- ## Fluxo ponta a ponta A habilitação é **solicitada pelo integrador**, e só é aceita depois que o cadastro do emissor está aprovado. Não há criação automática: enquanto a solicitação não for feita, o emissor não tem auto-assinatura. 1. **Emissor aprovado.** O cadastro passa pelo fluxo normal de homologação até o status `approved`. Nada é criado nesse momento. 2. **Solicitação da habilitação.** O integrador chama [`POST /issuer_management/issuer/{issuer_key}/auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura). Na mesma chamada, a QI Tech cria a auto-assinatura, gera o termo de adesão a partir do template configurado para o cliente e abre o envelope de assinatura — independente de qualquer operação. A resposta já vem no status `pending_signature`, com `issuer_auto_signature_key` e `envelope_key`. 3. **Assinatura do termo.** O integrador consulta os [links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) e direciona **cada assinante do emissor ao seu próprio link**. O termo é assinado fora de qualquer operação, e pode ser assinado antes da primeira emissão. 4. **Termo assinado.** Quando todas as assinaturas necessárias são concluídas, a auto-assinatura passa para `enabled` e os campos `signed_at` e `enabled_at` são preenchidos. A QI Tech emite então o certificado privado do emissor, utilizado para assinar os documentos das emissões. 5. **Recusa ou expiração.** Se o envelope for recusado, cancelado ou expirado, a auto-assinatura vai para `reproved` e as emissões seguem pelo fluxo de assinatura manual. Uma nova habilitação precisa ser solicitada. Os passos 2, 4 e 5 disparam o webhook [`issuer_management.auto_signature_status_change`](/documentation/escrituracao/webhooks-escrituracao) — ou seja, os status `pending_signature`, `enabled` e `reproved`. O cancelamento (`canceled`) não gera webhook e é observado por consulta. Como o `pending_signature` já vem na resposta da solicitação, o webhook desse status é redundante para quem chamou o endpoint — ele é útil para outros consumidores do mesmo tenant. :::caution Não assuma a auto-assinatura ativa A solicitação abre o envelope, mas não conclui a habilitação: o termo ainda precisa ser assinado. Só considere a assinatura automática disponível para uma emissão depois que a auto-assinatura estiver em `enabled`. Em qualquer outro status, o documento segue para assinatura manual — a integração precisa tratar os dois caminhos. ::: --- ## Máquina de status | Status | Significado | Assinatura de uma nova emissão | |--------|-------------|--------------------------------| | `pending_term_generation` | Estado transitório durante a solicitação | Manual | | `pending_signature` | Termo gerado e enviado para assinatura; links dos assinantes disponíveis | Manual | | `enabled` | Termo assinado; emissor habilitado à assinatura automática | **Automática** | | `reproved` | Envelope do termo recusado, cancelado ou expirado | Manual | | `canceled` | Auto-assinatura cancelada | Manual | **Transições possíveis:** - `pending_term_generation` → `pending_signature` (ambos dentro da solicitação) → `enabled` - `pending_signature` → `reproved` (envelope recusado, cancelado ou expirado) - `pending_term_generation` ou `pending_signature` → `canceled` A auto-assinatura é cancelada automaticamente quando o emissor deixa o status `approved` — ou seja, quando passa para `reproved`, `expired` ou `canceled`. Nesse caso, a habilitação precisa ser refeita após a nova aprovação do cadastro. --- ## Endpoints | Endpoint | Para quê | |---|---| | [`POST .../auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) | Solicitar a habilitação para um emissor aprovado | | [`GET .../auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) | Consultar o estado atual e o histórico de eventos | | [`GET .../auto_signature/signers`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) | Obter o link de assinatura de cada assinante do termo | ## Como acompanhar Há dois caminhos, complementares: - **Webhook** — [`issuer_management.auto_signature_status_change`](/documentation/escrituracao/webhooks-escrituracao) é enviado nos status `pending_signature`, `enabled` e `reproved`. Ao receber `pending_signature`, consulte os links de assinatura. - **Consulta** — [consulta da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) retorna o estado atual e o histórico completo de eventos. O bloco resumido também aparece na [consulta do emissor](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave), no campo `auto_signature`: ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "status": "approved", "auto_signature": { "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "enabled", "signed_at": "2026-02-11T14:02:31", "enabled_at": "2026-02-11T14:02:31" } } ``` O campo é `null` para emissores que nunca tiveram uma auto-assinatura solicitada. --- # Solicitação da Auto-assinatura URL: /en/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura Este endpoint solicita a habilitação da auto-assinatura para um emissor **aprovado**. Na mesma chamada, a QI Tech gera o termo de adesão e abre o envelope de assinatura, de modo que a resposta já volta com a habilitação pronta para ser assinada. Consulte o [fluxo da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) para o encadeamento completo. :::info Emissor aprovado A solicitação só é aceita quando o cadastro do emissor está no status `approved` e o cliente está habilitado para auto-assinatura. Não há criação automática — nada acontece até que este endpoint seja chamado. ::: --- ## Solicitação da Auto-assinatura (POST) ### Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------ | ------ | --------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Este endpoint não recebe corpo. O grupo de assinantes e o template do termo de adesão são resolvidos pela QI Tech a partir do cadastro do emissor e da configuração do cliente. --- ### Response STATUS 201 Response Body ```json { "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "pending_signature", "signed_at": null, "enabled_at": null, "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce", "created_at": "2026-02-10T09:15:44", "event_list": [ { "event_type": "auto_signature_creation", "status": "pending_term_generation", "event_data": { "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154" }, "created_at": "2026-02-10T09:15:44" }, { "event_type": "adhesion_term_generation", "status": "pending_term_generation", "event_data": { "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "template_key": "b71f1a2c-9e44-4c1d-8f3a-6d2c0b5e7a19" }, "created_at": "2026-02-10T09:15:46" }, { "event_type": "envelope_creation", "status": "pending_signature", "event_data": { "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce" }, "created_at": "2026-02-10T09:15:47" } ] } ``` A resposta é o mesmo objeto da [consulta da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura), normalmente já em `pending_signature`, com `term_document_key` e `envelope_key` preenchidos. Em seguida, consulte os [links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) para obter o link de cada assinante. --- ### Erros | HTTP | Código | Quando ocorre | | ---- | --------------------------------------------------- | ------------------------------------------------------------------------------------- | | 400 | `ISS0000032` (`IssuerNotApproved`) | O emissor não está no status `approved`. | | 400 | `ISS0000033` (`AutoSignatureNotEnabledForTenant`) | O cliente não está habilitado para auto-assinatura. | | 403 | `ISS000011` (`TenantForbidden`) | O cliente não possui acesso completo ao cadastro do emissor informado. | | 404 | `ISS000009` (`IssuerNotFound`) | Não existe emissor para a chave informada. | | 404 | `ISS0000026` (`TenantConfigurationNotFound`) | O cliente não possui configuração de auto-assinatura cadastrada. | | 409 | `ISS0000029` (`AutoSignatureAlreadyExists`) | O emissor já possui uma auto-assinatura ativa em `pending_signature` ou `enabled`. Cancele a atual antes de solicitar outra. | --- # Issuer Signer Groups Registration URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor This endpoint allows registering signer groups associated with a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group METHOD POST ### Path Params | Field | Type | Description | Characters | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | ### Request Body Request Body ```json { "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### Request Body Params | Field | Type | Description | Max Characters | | ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- | | `minimum_required_signers` * | integer | Minimum number of signers required to validate the group. | - | | `signers` * | array | List of Signer Objects that make up the signer group | **[Signer Object](#signer-object)** | ### Signer Object | Field | Type | Description | Max Characters | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Full name of the signer. | 255 | | `document_number` * | string | Signer's CPF (format "XXX.XXX.XXX-XX"). | 11 | | `email` * | string | Signer's email address. | 1023 | | `phone_number`* | string | Signer's phone number (complete format: country code, area code and number. Example: +5511999999999). | 20 | | `is_group_mandatory` * | boolean | Indicates if the signer is mandatory or optional within the group. | - | ## Response STATUS 201 Response Body ```json { "signer_group_key": "123e4567-e89b-12d3-a456-426614174000", "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### Response Body Params | Field | Type | Description | Max Characters | | ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- | | `signer_group_key` | string | Unique identifier of the signer group (UUID v4). | 36 | | `minimum_required_signers` | integer | Minimum number of signers required in the group. | - | | `signers` * | array | List of Signer Objects that make up the signer group | **[Signer Object](#signer-object)** | --- # Issuer Signer Groups Removal URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao This endpoint allows removing signer groups associated with a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group/ SIGNER-GROUP-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |--------------------|--------|----------------------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | | `SIGNER-GROUP-KEY` | string | Unique key of the signer group to be removed (UUID v4). | 36 | ## Response STATUS 204 No content is returned in the response body. --- # Issuer Registration URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico This endpoint allows registering the basic information of an issuer. ## Request ENDPOINT /issuer_management/issuer METHOD POST ### Request Body Request Body ```json { "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "trading_name": "Exemplo Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` ### Request Body Params | Field | Type | Description | Max Characters | | --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- | | `name` * | string | Full company name. | 255 | | `document_number` * | string | Company CNPJ (format "XX.XXX.XXX/XXXX-XX"). | 14 | | `trading_name`* | string | Company trade name. | 1023 | | `cnae_code`* | string | Company CNAE code (format "XX.XX-X-XX"). | 7 | | `company_type`* | string | Company type. | **[company_type Enumerators](#company_type-enumerators)** | | `foundation_date`* | string | Company foundation date (format "YYYY-MM-DD"). | - | | `address` * | string | Object referencing the address | **[address object](#address-object)** | | `annual_revenues` | number | Issuer's annual revenue declaration. | - | | `is_in_national_financial_system` | boolean | Indicator if the issuer is part of the National Financial System. | - | ### Address Object | Field | Type | Description | Max Characters | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | Street name of the company address. | 500 | | `neighborhood` * | string | Neighborhood name of the company address. | 100 | | `number` * | string | Address number. | 10 | | `postal_code` * | string | Address postal code (format "XXXXX-XXX"). | 8 | | `city` * | string | City name of the address. | 255 | | `state` * | string | State abbreviation (2 characters). | 2 | | `complement` | string | Address complement, if applicable. | 100 | ### company_type Enumerators | Enum | Description | | -------- | ------------------ | | `ltda` | Limited Company | | `sa` | Sociedade Anônima | | `cop` | Cooperative | ## Response STATUS 201 Response Body ```json { "issuer_key": "123e4567-e89b-12d3-a456-426614174000", "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "status": "in_filling", "person_type": "legal", "trading_name": "Exemplo Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2023-01-01T12:00:00Z", "expiration_date": "2024-01-01T12:00:00Z", "payment_bank_account": { "account_number": "19500", "account_digit": "7", "account_branch": "0001" }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` ### Response Body Params | Field | Type | Description | Max Characters | | ------------------------- | ------ | ----------------------------------- | -------------------------------------------------------------- | | `issuer_key` | string | Unique issuer key (UUID). | 36 | | `name` | string | Full issuer name. | 255 | | `document_number` | string | Issuer CNPJ. | 14 | | `status` | string | Issuer status. | - | | `person_type` | string | Person type | **[person_type Enumerators](#person_type-enumerators)** | | `trading_name` | string | Issuer trade name. | 1023 | | `cnae_code` | string | Issuer CNAE code. | 7 | | `company_type` | string | Company type | **[company_type Enumerators](#company_type-enumerators)** | | `foundation_date` | string | Issuer foundation date. | - | | `address` | string | Object referencing the address | **[address object](#address-object)** | | `registration_datetime` | string | Issuer registration date and time. | - | | `expiration_date` | string | Issuer expiration date. | - | | `annual_revenues` | number | Issuer's annual revenue declaration. | - | | `is_in_national_financial_system` | boolean | Indicator if the issuer is part of the National Financial System. | - | ### person_type Enumerators | Enum | Description | | ----------- | ---------------- | | `legal` | Legal Entity | | `natural` | Natural Person | :::warning Warning When registering an issuer, an internal account is reserved that will only be opened if an operation is completed. ::: ### payment_bank_account Object | Field | Type | Description | Max Characters | | -------------------- | ------ | --------------------------- | ---------------- | | `account_digit` * | string | Bank account digit. | - | | `account_branch` * | string | Bank branch. | - | | `account_number` * | string | Bank account number. | - | --- # Issuer Bank Account Registration URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor This endpoint allows registering a bank account associated with a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account METHOD POST ### Path Params | Field | Type | Description | Characters | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | ### Request Body Request Body ```json { "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ``` ### Request Body Params | Field | Type | Description | Max Characters | | -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- | | `account_number` * | string | Bank account number. Must contain only digits. | 20 | | `account_digit` * | string | Account verification digit. Must contain a single digit. | 1 | | `account_branch` * | string | Bank branch number. Must contain only digits. | 6 | | `financial_institution_code_number`* | string | Financial institution code (3 digits). | 3 | | `financial_institution_ispb` * | string | Financial institution ISPB code (8 digits). | 8 | | `account_type` * | string | Bank account type. | **[account_type Enumerators](#account_type-enumerators)** | ### account_type Enumerators | Enum | Description | | ------------ | ------------------ | | `checking` | Checking Account | | `savings` | Savings Account | | `salary` | Salary Account | | `payment` | Payment Account | ## Response STATUS 201 Response Body ```json { "bank_account_key": "123e4567-e89b-12d3-a456-426614174000", "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ``` ### Response Body Params | Field | Type | Description | Max Characters | | ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `bank_account_key` | string | Unique identifier of the registered bank account (UUID v4). | 36 | | `account_number` | string | Bank account number. | 20 | | `account_digit` | string | Bank account verification digit. | 1 | | `account_branch` | string | Bank branch number. | 6 | | `financial_institution_code_number` | string | Financial institution code. | 3 | | `financial_institution_ispb` | string | Financial institution ISPB code. | 8 | | `account_type` | string | Bank account type. | **[account_type Enumerators](#account_type-enumerators)** | --- # Setting the Issuer's Primary Bank Account URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal This endpoint promotes an existing issuer bank account to primary (`is_default: true`). The account previously marked as primary automatically becomes `is_default: false`. --- ## Swapping the issuer's primary bank account An issuer may have several registered bank accounts, but only one is marked as primary. To correct a primary account with incorrect data (digit, branch, ISPB), use the flow below. :::warning Prerequisite The issuer must be in `in_filling` status. After that status, the primary account cannot be changed — this is intentional, since the primary account is referenced by financial operations. ::: ### Swap flow (3 calls) 1. **POST** `.../bank_account` → creates the new (correct) account. 2. **POST** `.../bank_account/{key}/set_default` → promotes the new account to primary. 3. **DELETE** `.../bank_account/{old_key}` → removes the old account. The same ordering restriction applies: since deleting the primary account is not allowed, promotion must come before removal. Reversing the order returns `HTTP 400 / ISS0000012`. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY /set_default METHOD POST ### Path Params | Field | Type | Description | Characters | |--------------------|--------|----------------------------------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | | `BANK-ACCOUNT-KEY` | string | Unique key of the bank account to be promoted to primary (UUID v4). | 36 | ### Request Body No content is sent in the request body. --- ## Response STATUS 204 Account promoted to primary. No content is returned in the response body. --- ## Errors | HTTP | Code | Scenario | |------|--------------|-------------------------------------------------------------------------| | 400 | `ISS0000011` | Issuer is not in `in_filling`. | | 403 | `ISS000011` | Tenant does not have access to this issuer. | | 404 | `ISS000005` | `bank_account_key` not found for this issuer. | | 404 | `ISS000009` | `issuer_key` not found. | --- # Issuer Bank Account Removal URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao This endpoint allows removing bank account associated with a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |--------------------|--------|------------------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | | `BANK-ACCOUNT-KEY` | string | Unique key of the bank account to be removed (UUID v4).| 36 | --- ## Response STATUS 204 No content is returned in the response body. --- ## Notes - Removing the account marked as primary (`is_default: true`) is not allowed. The attempt returns `HTTP 400 / ISS0000012`. To swap the primary account, see the full flow in [Setting the issuer's primary bank account](./conta-bancaria-emissor-principal.md). - Changes to the primary account are only allowed while the issuer is in `in_filling`. Outside that status, the operation returns `HTTP 400 / ISS0000011`. --- --- # Issuer Documents Submission URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor This endpoint allows submitting documents associated with a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document METHOD POST ### Path Params | Field | Type | Description | Characters | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "proof_of_address" } ``` ### Request Body Params | Field | Type | Description | Max Characters | | --------------------- | ------ | ------------------------------------------------------- | ---------------------------------------------------------------- | | `document_base64` * | string | Document file content encoded in Base64. | - | | `document_type` * | string | Type of document submitted. | **[document_type Enumerators](#document_type-enumerators)** | | Enum | Description | | ------------------------------- | ---------------------------------- | | `danfe` | DANFE | | `proof_of_address` | Proof of Address | | `letter_of_attorney` | Power of Attorney | | `company_statute` | Company Contract or Statute | | `commercial_board_certificate` | Commercial Board Certificate | | `board_election_record` | Board Election Minutes | | `manager_declaration` | Manager Declaration | | `financial_statement` | Financial Statement | | `credit_report` | Credit Report | | `manager_statement` | Administrator Statement | | `compliance_statement` | Compliance Statement | | `cnpj_card` | CNPJ Card | | `additional_document` | Additional Document | ## Response STATUS 201 Response Body ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_address", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ``` ### Response Body Params | Field | Type | Description | Max Length | | ----------------- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------- | | `document_key` | string | Unique identifier of the submitted document (UUID v4). | 36 | | `document_type` | string | Type of document submitted. | **[document_type Enumerators](#document_type-enumerators)** | | `ocr_key` | string | OCR key associated with the submitted document. | 36 | --- # Issuer Documents Removal URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao This endpoint allows removing documents submitted for issuer registration. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document/ DOCUMENT-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |----------------|--------|------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Unique key of the document to be removed (UUID v4). | 36 | ## Response STATUS 204 No content is returned in the response body. --- # Issuer Representative Document Upload URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor This endpoint allows uploading documents associated with a representative of a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document METHOD POST ### Path Params | Field | Type | Description | Characters | |-----------------------------|--------|---------------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | Unique issuer representative key (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### Request Body Params | Field | Type | Description | Max Characters | |--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------| | `document_base64` *| string | Document file content encoded in Base64. | - | | `document_type` * | string | Type of document being uploaded. Accepted values: | **[document_type Enumerators](#document_type-enumerators)** | ### document_type Enumerators | Enum | Description | | ------------------------------- | ---------------------------------- | | `cnh` | National Driver's License | | `cnh_front` | CNH Front | | `cnh_back` | CNH Back | | `cnh_digital` | Digital CNH | | `rg_front` | RG Front | | `rg_back` | RG Back | | `proof_of_address` | Proof of Address | | `letter_of_attorney` | Power of Attorney | | `passport` | Passport | | `national_registry_of_foreigners`| National Registry of Foreigners | ## Response STATUS 201 Response Body ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ``` ### Response Body Params | Field | Type | Description | Max Characters | |------------------|----------|-----------------------------------------------------|-----------------------| | `document_key` | string | Unique identifier for the uploaded document (UUID v4). | 36 | | `document_type` | string | Type of document uploaded. | **[document_type Enumerators](#document_type-enumerators)** | | `ocr_key` | string | OCR key associated with the uploaded document. | 36 | --- # Issuer Representative Document Removal URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao This endpoint allows removing documents associated with a representative of a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |-----------------------------|--------|---------------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | Unique issuer representative key (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Unique key of the document to be removed (UUID v4). | 36 | ## Response STATUS 204 No content is returned in the response body. --- # Issuer Contact Information Registration URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor This endpoint allows registering contact information associated with a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information METHOD POST ### Path Params | Field | Type | Description | Characters | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | ### Request Body Request Body ```json { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ``` ### Request Body Params | Field | Type | Description | Max Characters | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Full name of the contact. | 255 | | `document_number` * | string | Contact's document number (CPF format, format "XXX.XXX.XXX-XX"). | 14 | | `email`* | string | Contact's email address. | 1023 | | `phone_number`* | string | Contact's phone number (complete format: country code, area code and number. Example: +5511999999999). | 20 | ## Response STATUS 201 Response Body ```json { "issuer_contact_information_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ``` ### Response Body Params | Field | Type | Description | Max Characters | | ---------------------------------- | ------ | --------------------------------------------------------------------- | --------------------- | | `issuer_contact_information_key` | string | Unique identifier of the registered contact information (UUID v4). | 36 | | `name` | string | Full name of the contact. | 255 | | `document_number` | string | Contact's document number (CPF). | 11 | | `email` | string | Contact's email address. | 1023 | | `phone_number` | string | Contact's phone number. | 20 | --- # Setting the Issuer's Primary Contact URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal This endpoint promotes an existing issuer contact to primary (`is_default: true`). The contact previously marked as primary automatically becomes `is_default: false`. --- ## Swapping the issuer's primary contact An issuer may have multiple registered contacts, but only one is marked as primary. If the primary contact was registered with incorrect data (typo in the e-mail, wrong digit in the phone number), use the flow below to replace it. :::warning Prerequisite The issuer must be in `in_filling` status. Once the issuer leaves that status, changes to the primary contact/account are not allowed — the endpoint will return `HTTP 400 / ISS0000011`. ::: ### Swap flow (3 calls) 1. **POST** `.../issuer_contact_information` → creates the new (correct) contact. 2. **POST** `.../issuer_contact_information/{key}/set_default` → promotes the new contact to primary. 3. **DELETE** `.../issuer_contact_information/{old_key}` → removes the old contact (with the typo). Order matters: since deleting a contact marked as primary is not allowed, you must promote the new contact before deleting the old one. Reversing the order returns `HTTP 400 / ISS0000013`. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY /set_default METHOD POST ### Path Params | Field | Type | Description | Characters | |----------------------------------|--------|-------------------------------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | | `ISSUER-CONTACT-INFORMATION-KEY` | string | Unique key of the contact to be promoted to primary (UUID v4). | 36 | ### Request Body No content is sent in the request body. --- ## Response STATUS 204 Contact promoted to primary. No content is returned in the response body. --- ## Errors | HTTP | Code | Scenario | |------|--------------|-------------------------------------------------------------------------| | 400 | `ISS0000011` | Issuer is not in `in_filling`. | | 403 | `ISS000011` | Tenant does not have access to this issuer. | | 404 | `ISS000008` | `issuer_contact_information_key` not found for this issuer. | | 404 | `ISS000009` | `issuer_key` not found. | --- # Issuer Contact Information Removal URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao This endpoint allows removing contact information associated with a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |----------------------------------|--------|-----------------------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | | `ISSUER-CONTACT-INFORMATION-KEY` | string | Unique key of the contact information to be removed (UUID v4).| 36 | ## Response STATUS 204 No content is returned in the response body. --- ## Notes - Removing the contact marked as primary (`is_default: true`) is not allowed. The attempt returns `HTTP 400 / ISS0000013`. To swap the primary contact, see the full flow in [Setting the issuer's primary contact](./informacao-contato-emissor-principal.md). - Changes to the primary contact are only allowed while the issuer is in `in_filling`. Outside that status, the operation returns `HTTP 400 / ISS0000011`. --- # Issuer Representatives Registration URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor This endpoint allows registering representatives associated with a previously registered issuer. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative METHOD POST ### Path Params | Field | Type | Description | Characters | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | ### Request Body Request Body ```json { "name": "João da Silva", "document_number": "123.456.789-01", "birthdate": "1990-01-01", "nationality": "BRA", "mother_name": "Maria da Silva", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "related_party_type": "attorney", "annual_revenues": 150000, } ``` ### Request Body Params | Field | Type | Description | Max Characters | | ---------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | `name` * | string | Full name of the issuer representative. | 255 | | `document_number` * | string | Document number (CPF, format "XXX.XXX.XXX-XX"). | 11 | | `birthdate` | string | Representative's birthdate in ISO 8601 format (YYYY-MM-DD). | - | | `document_identification_number` | string | Document identification number. | 255 | | `marital_status` | string | Representative's marital status. | **[marital_status Enumerators](#marital_status-enumerators)** | | `property_system` | string | Property regime. | **[property_system Enumerators](#property_system-enumerators)** | | `nationality` * | string | Beneficiary's country of origin. | 3, according to ISO 3166-1 alpha-3 | | `mother_name` | string | Full name of the representative's mother. | 1023 | | `father_name` | string | Full name of the representative's father. | 1023 | | `occupation` | string | Representative's occupation or profession. | 255 | | `is_pep` | boolean | Indicates if the representative is a Politically Exposed Person (PEP). | - | | `address` * | string | Object referencing the address | **[Address Object](#address-object)** | | `annual_revenues` | number | Annual revenue declaration of the assignor. | - | | `related_party_type` * | enumerator | Related party relationship type. | See **[Related Party Type Enumerators](#related-party-type)** | ### Address Object | Field | Type | Description | Max Characters | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | Street name of the company address. | 500 | | `neighborhood` | string | Neighborhood name of the company address. | 100 | | `number` * | string | Address number. | 10 | | `postal_code` * | string | Address postal code (format "XXXXX-XXX"). | 8 | | `city` * | string | City name of the address. | 255 | | `state` * | string | State abbreviation (2 characters). | 2 | | `complement` | string | Address complement, if applicable. | 100 | ### marital_status Enumerators | Enum | Description | | ---------------- | ------------------ | | `single` | Single | | `married` | Married | | `widower` | Widowed | | `separated` | Separated | | `stable_union` | In Stable Union | | `divorced` | Divorced | ### property_system Enumerators | Enum | Description | | --------------------------------------- | --------------------------------- | | `total_communion_of_goods` | Total Community of Property | | `partial_communion_of_goods` | Partial Community of Property | | `total_separation_of_goods` | Total Separation of Property | | `final_participation_of_acquisitions` | Final Participation in Acquisitions | | `compulsory_separation_of_goods` | Compulsory Separation of Property | ### Related Party Type | Enumerator | Description | | ----------------------- | ------------- | | **president** | President | | **partner** | Partner | | **administrator** | Administrator | | **director** | Director | | **manager** | Manager | | **attorney** | Attorney | --- ## Response STATUS 201 Response Body ```json { "issuer_representative_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "document_identification_number": "987654321", "marital_status": "single", "property_system": "partial_communion_of_goods", "birthdate": "1990-01-01", "nationality": "BRA", "mother_name": "Maria da Silva", "father_name": "José da Silva", "occupation": "Advogado", "is_pep": false, "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "related_party_type": "attorney", "annual_revenues": 150000, "issuer_representative_document_list": [] } ``` ### Response Body Params | Field | Type | Description | Max Characters | | --------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | `issuer_representative_key` | string | Unique identifier for the issuer representative (UUID v4). | 36 | | `name` | string | Full name of the issuer representative. | 255 | | `document_number` | string | Representative's document number (format "XXX.XXX.XXX-XX"). | 11 | | `document_identification_number` | string | Document identification number. | 255 | | `marital_status` | string | Representative's marital status. | **[marital_status Enumerators](#marital_status-enumerators)** | | `property_system` | string | Property regime. | **[property_system Enumerators](#property_system-enumerators)** | | `birthdate` | string | Representative's birthdate. | - | | `nationality` * | string | Beneficiary's country of origin. | 3, according to ISO 3166-1 alpha-3 | | `mother_name` | string | Full name of the representative's mother. | 1023 | | `father_name` | string | Full name of the representative's father. | 1023 | | `occupation` | string | Representative's occupation or profession. | 255 | | `is_pep` | boolean | Indicates if the representative is a Politically Exposed Person (PEP). | - | | `address` * | string | Object referencing the address | **[Address Object](#address-object)** | | `issuer_representative_document_list` | array | List of documents associated with the representative. | - | | `annual_revenues` | number | Annual revenue declaration of the assignor. | - | | `related_party_type` * | enumerator | Related party relationship type. | See **[Related Party Type Enumerators](#related-party-type)** | --- # Issuer Representative Removal URL: /en/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao This endpoint allows removing representatives submitted for issuer registration. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |-----------------------------|--------|--------------------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | Unique key of the representative to be removed (UUID v4). | 36 | ## Response STATUS 204 No content is returned in the response body. --- # Get Issuer URL: /en/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave This endpoint allows querying the complete details of an issuer registered in the system, using their unique key. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY METHOD GET ### Path Params | Field | Type | Description | Characters | |--------------|--------|------------------------------------------|------------| | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | ## Response STATUS 200 Response Body ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "in_filling", "backoffice_analysis_status": "in_analysis", "person_type": "legal", "trading_name": "Fabrica Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2025-01-23T13:47:57.354528", "expiration_date": "2026-01-23", "signer_group_list": [], "bank_account_list": [], "issuer_representative_list": [], "issuer_contact_information_list": [], "issuer_document_list": [], "issuer_analysis_list": [], "payment_bank_account": { "account_number": "19500", "account_digit": "7", "account_branch": "0001" }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` ### Response Body Params | Field | Type | Description | Max Characters | |--------|----------|--------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | Unique issuer identifier. | 36 | | `name` | string | Full issuer name. | 255 | | `document_number` | string | Issuer document number (CNPJ). | 14 | | `status` | string | Issuer status | **[status Enumerators](#status-enumerators)** | | `backoffice_analysis_status`| string | Backoffice analysis status. | - | | `person_type` | string | Person type (`legal` or `natural`). | - | | `trading_name` | string | Issuer trade name. | 1023 | | `cnae_code` | string | Issuer CNAE code. | 10 | | `company_type` | string | Company type Accepted: ´sa´, ´ltda´, ´cop´ | 50 | | `foundation_date` | string | Issuer foundation date. | - | | `signer_group_list` | array | List of signer groups associated with the issuer. | - | | `bank_account_list` | array | List of bank accounts associated with the issuer. | - | | `issuer_representative_list` | array | List of issuer representatives. | - | | `issuer_contact_information_list` | array | List of contact information associated with the issuer. | - | | `issuer_document_list` | array | List of documents registered for the issuer. | - | | `address` * | string | Object referencing the address | **[address object](#address-object)** | | `annual_revenues` | number | Issuer's annual revenue declaration. | - | | `is_in_national_financial_system` | boolean | Indicator if the issuer is part of the National Financial System. | - | ### Address Object | Field | Type | Description | Max Characters | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` * | string | Street name of the company address. | 500 | | `neighborhood` | string | Neighborhood name of the company address. | 100 | | `number` * | string | Address number. | 10 | | `postal_code` * | string | Address postal code (numbers only). | 8 | | `city` * | string | City name of the address. | 255 | | `state` * | string | State abbreviation (2 characters). | 2 | | `complement` | string | Address complement, if applicable. | 100 | ### status Enumerators | Enum | Description | |--------|-----------------| | `in_filling` | In filling | | `in_analysis` | Under analysis | | `canceled` | Canceled | | `approved` | Approved | | `reproved` | Rejected | | `expired` | Expired | :::warning Warning When registering an issuer, an internal account is reserved that will only be opened if an operation is completed. ::: ### payment_bank_account Object | Field | Type | Description | Max Characters | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_digit` * | string | Bank account digit. | - | | `account_branch` * | string | Bank branch. | - | | `account_number` * | string | Bank account number. | - | --- # Issuer Query by Filters URL: /en/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro This endpoint allows querying issuers registered in the system using the document number (CNPJ) or Name. --- ## Request ENDPOINT /issuer_management/issuer METHOD GET ### Query Params | Field | Type | Description | Required | |-------------------|----------|------------------------------------|-------------| | `document_number` | string | Issuer document number. | No | | `name` | string | Issuer name. | No | | `page` | integer | Current page of the query. | No | | `rows_per_page` | integer | Number of records per page. | No | ## Response STATUS 200 Response Body ```json { "data": [ { "issuer_key": "495ae701-5c38-49b1-b517-a3b910fe8d8f", "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "status": "in_filling" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 1 } } ``` ### Response Body Params | Field | Type | Description | | |--------------|--------|---------------------|-----------------------------------------------------------------| | `data` | list | List of results | **[Simplified Issuer Object](#simplified-issuer-object)** | | `pagination` | object | Pagination data | **[Pagination Object](#pagination-object)** | ### Simplified Issuer Object | Field | Type | Description | Max Characters | |-------------------|----------|-------------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | Unique issuer identifier (UUID v4). | 36 | | `name` | string | Full issuer name. | 255 | | `document_number` | string | Issuer document number (CNPJ). | 14 | | `status` | string | Current issuer status. | **[status Enumerators](#status-enumerators)** | ### status Enumerators | Enum | Description | |--------|-----------------| | `in_filling` | In filling | | `in_analysis` | Under analysis | | `canceled` | Canceled | | `approved` | Approved | | `reproved` | Rejected | | `expired` | Expired | ### Pagination Object | Field | Type | Description | |-------------------|----------|------------------------------------------| | `current_page` | integer | Current page of the query. | | `next_page` | integer | Next page, if it exists. | | `rows_per_page` | integer | Number of records per page. | | `total_pages` | integer | Total number of pages. | | `total_rows` | integer | Total number of records found. | --- # Issuer Analysis Submission URL: /en/documentation/escrituracao/homologacao-emissor/envio-analise/ This endpoint allows changing an issuer's status to analysis, sending it to the validation process. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY METHOD PATCH ### Path Params | Field | Type | Description | Characters | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Unique issuer key (UUID v4). | 36 | ### Request Body Request Body ```json { "issuer_status": "in_analysis" } ``` ### Request Body Params | Field | Type | Description | Required | | ----------------- | ------ | ------------------------------------------------------- | ------------ | | `issuer_status` | string | New issuer status. Accepted value: `in_analysis`. | Yes | ## Response The response is a complete updated JSON of the issuer. --- # Introduction URL: /en/documentation/escrituracao/homologacao-emissor/inicio The Issuer registration section is essential for starting Commercial Paper issuance. In this section we will explain the entire flow, from sending the first information, to sending for analysis. To have access to the services discussed in the next sessions, contact the team [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br), so that the proper releases are made, both in the Sandbox environment and in the production environment. ### Issuer Registration At this stage, all information from both the Issuer and its representatives, documents, contact information, signer groups and bank accounts must be sent. Once the information submission is complete, the registration is sent for analysis by the assignor registry team and after approval this issuer will be able to participate in Commercial Paper issuance. If the registration has already been done on the QI CTVM assignor registry platform, it is possible to reuse this registration in a simple way, using the data access request endpoint. ### Issuer Update In case of need for registration update, all Issuer information must be sent again with the desired modifications. After submission, a new Analysis is generated for validation. As soon as this new Analysis is approved, the new Issuer registration data is effectively changed. --- # Issuer Data Access Request URL: /en/documentation/escrituracao/homologacao-emissor/solicitacao-acesso Clients who registered an issuer that already has a **registration in the assignor registry platform** need to **request access to the issuer data** so they can issue operations with this issuer as a party in the bookkeeping system. --- ## **Access Request (POST)** ### **Request** ENDPOINT /issuer_management/issuer/data_access_request METHOD POST --- ## **Request Body** Request Body ```json { "document_number": "96.146.194/0001-07", } ``` --- ## **Response** STATUS 201 Response Body ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "approved", "backoffice_analysis_status": "approved", "person_type": "legal", "trading_name": "Fabrica Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2025-01-23T13:47:57.354528", "expiration_date": "2026-01-23", "signer_group_list": [ { "signer_group_key": "123e4567-e89b-12d3-a456-426614174000", "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ], "bank_account_list": [ { "bank_account_key": "123e4567-e89b-12d3-a456-426614174000", "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ], "issuer_representative_list": [ { "issuer_representative_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "document_identification_number": "987654321", "marital_status": "single", "property_system": "partial_communion_of_goods", "birthdate": "1990-01-01", "nationality": "BRA", "mother_name": "Maria da Silva", "father_name": "José da Silva", "occupation": "Advogado", "is_pep": false, "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "related_party_type": "attorney", "annual_revenues": 150000, "issuer_representative_document_list": [ { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ] } ], "issuer_contact_information_list": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ], "issuer_document_list": [ { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_address", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ], "issuer_analysis_list": [], "payment_bank_account": { "account_number": "19500", "account_digit": "7", "account_branch": "0001" } } ``` ### Response Body Params | Field | Type | Description | Max Characters | |--------|----------|--------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | Unique issuer identifier. | 36 | | `name` | string | Full issuer name. | 255 | | `document_number` | string | Issuer document number (CNPJ). | 14 | | `status` | string | Issuer status | **[status Enumerators](#status-enumerators)** | | `backoffice_analysis_status`| string | Backoffice analysis status. | - | | `person_type` | string | Person type (`legal` or `natural`). | - | | `trading_name` | string | Issuer trade name. | 1023 | | `cnae_code` | string | Issuer CNAE code. | 10 | | `company_type` | string | Company type Accepted: ´sa´, ´ltda´, ´cop´ | 50 | | `foundation_date` | string | Issuer foundation date. | - | | `signer_group_list` | array | List of signer groups associated with the issuer. | - | | `bank_account_list` | array | List of bank accounts associated with the issuer. | - | | `issuer_representative_list` | array | List of issuer representatives. | - | | `issuer_contact_information_list` | array | List of contact information associated with the issuer. | - | | `issuer_document_list` | array | List of documents registered for the issuer. | - | | `address` * | string | Object referencing the address | **[address object](#address-object)** | ### Address Object | Field | Type | Description | Max Characters | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` * | string | Street name of the company address. | 500 | | `neighborhood` | string | Neighborhood name of the company address. | 100 | | `number` * | string | Address number. | 10 | | `postal_code` * | string | Address postal code (numbers only). | 8 | | `city` * | string | City name of the address. | 255 | | `state` * | string | State abbreviation (2 characters). | 2 | | `complement` | string | Address complement, if applicable. | 100 | ### status Enumerators | Enum | Description | |--------|-----------------| | `in_filling` | In filling | | `in_analysis` | Under analysis | | `canceled` | Canceled | | `approved` | Approved | | `reproved` | Rejected | | `expired` | Expired | ### payment_bank_account Object | Field | Type | Description | Max Characters | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_digit` * | string | Bank account digit. | - | | `account_branch` * | string | Bank branch. | - | | `account_number` * | string | Bank account number. | - | --- # Investor Registration Update URL: /en/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/ To make changes to the Investor registration, it is necessary that its status be set to "in_filling", this will re-enable all inclusion/removal endpoints. After making the modifications, the registration must be sent again for analysis with the status "in_analysis". --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY METHOD PATCH ### Path Params | Field | Type | Description | Characters | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | ### Request Body Request Body ```json { "investor_status": "in_filling" } ``` ### Request Body Params | Field | Type | Description | Required | |------------------|----------|-----------------------------------------------------|-------------| | `investor_status` | string | New investor status. Accepted value: `in_filling`. | Yes | ## Response The response is a complete updated JSON of the investor. --- # Investor Signer Groups Registration URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor This endpoint allows registering signer groups associated with a previously registered investor. :::danger Attention It is not possible to add a signer group for a Natural Person (PF) investor. ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group METHOD POST ### Path Params | Field | Type | Description | Characters | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | ### Request Body Request Body ```json { "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### Request Body Params | Field | Type | Description | Max Characters | | ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- | | `minimum_required_signers` * | integer | Minimum number of signers required to validate the group. | - | | `signers` * | array | List of Signer Objects that make up the signer group | **[Signer Object](#signer-object)** | ### Signer Object | Field | Type | Description | Max Characters | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Full name of the signer. | 255 | | `document_number` * | string | Signer's CPF (format "XXX.XXX.XXX-XX"). | 11 | | `email` * | string | Signer's email address. | 1023 | | `phone_number`* | string | Signer's phone number (complete format: country code, area code and number. Example: +5511999999999). | 20 | | `is_group_mandatory` * | boolean | Indicates if the signer is mandatory or optional within the group. | - | ## Response STATUS 201 Response Body ```json { "signer_group_key": "123e4567-e89b-12d3-a456-426614174000", "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### Response Body Params | Field | Type | Description | Max Characters | | ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- | | `signer_group_key` | string | Unique identifier of the signer group (UUID v4). | 36 | | `minimum_required_signers` | integer | Minimum number of signers required in the group. | - | | `signers` * | array | List of Signer Objects that make up the signer group | **[Signer Object](#signer-object)** | --- # Investor Signer Groups Removal URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao This endpoint allows removing signer groups associated with a previously registered investor. :::danger Attention It is not possible to remove a signer group from a Natural Person (PF) investor. ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group/ SIGNER-GROUP-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |--------------------|--------|----------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | | `SIGNER-GROUP-KEY` | string | Unique key of the signer group to be removed (UUID v4). | 36 | ## Response STATUS 204 No content is returned in the response body. --- # Investor Registration URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico This endpoint allows registering the basic information of an investor. The same endpoint is used for both **legal entity (PJ)** and **natural person (PF)** investors — the request body varies according to the `person_type` field. ## Request ENDPOINT /investor_management/investor METHOD POST ### Request Body Case 01: Legal Entity ```json { "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "trading_name": "Exemplo Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" } } ``` Case 02: Natural Person ```json { "person_type": "natural", "name": "Maria Exemplo da Silva", "document_number": "123.456.789-00", "document_identification_number": "12.345.678-9", "marital_status": "single", "property_system": null, "birthdate": "1990-05-14", "nationality": "BRA", "mother_name": "Joana Exemplo da Silva", "father_name": "José Exemplo da Silva", "occupation": "software engineer", "is_pep": false, "email": "maria.exemplo@example.com", "phone_number": "+5511999999999", "investor_category": "retail", "investment_suitability": "moderate", "address": { "street": "Rua Exemplo", "neighborhood": "Centro", "number": "45", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Apto 12" } } ``` :::warning Attention If the `person_type` field is omitted, the registration is treated as **Legal Entity** (`legal`). To register a **Natural Person** investor, send `person_type: "natural"`. ::: ### Request Body Params — Legal Entity | Field | Type | Description | Max Characters | | --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- | | `person_type` | string | Optional. If omitted, the registration is treated as Legal Entity (`legal`). | **[person_type Enumerators](#person_type-enumerators)** | | `name` * | string | Full company name. | 255 | | `document_number` * | string | Company CNPJ (format "XX.XXX.XXX/XXXX-XX"). | 14 | | `trading_name`* | string | Company trade name. | 1023 | | `cnae_code`* | string | Company CNAE code (format "XXXXX-XXX"). | 7 | | `company_type`* | string | Company type. | **[company_type Enumerators](#company_type-enumerators)** | | `foundation_date`* | string | Company foundation date (format "YYYY-MM-DD"). | - | | `address` * | object | Object referencing the address | **[address object](#address-object)** | ### Request Body Params — Natural Person | Field | Type | Description | Max Characters | | ----------------------------------- | ------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `person_type` * | string | Must be sent as `"natural"`. | **[person_type Enumerators](#person_type-enumerators)** | | `name` * | string | Investor's full name. | 255 | | `document_number` * | string | Investor's CPF (format "XXX.XXX.XXX-XX"). | 14 | | `document_identification_number`* | string | Investor's identity document number (RG, CNH, or passport). | 255 | | `marital_status`* | string | Investor's marital status. | **[marital_status Enumerators](#marital_status-enumerators)** | | `property_system` | string | Marital property regime. Required only when `marital_status` requires a property regime. | **[property_system Enumerators](#property_system-enumerators)** | | `birthdate`* | string | Investor's date of birth (format "YYYY-MM-DD"). | - | | `nationality`* | string | Investor's nationality. | **[nationality Enumerators](#nationality-enumerators)** | | `mother_name`* | string | Investor's mother's name. | 1023 | | `father_name`* | string | Investor's father's name. | 1023 | | `occupation`* | string | Investor's occupation/profession. | 255 | | `is_pep`* | boolean | Indicates whether the investor is a Politically Exposed Person. | - | | `email`* | string | Investor's contact email. | 1023 | | `phone_number`* | string | Investor's contact phone number. | 20 | | `investor_category` | string | Investor's self-declared category. Optional. | **[investor_category Enumerators](#investor_category-enumerators)** | | `investment_suitability` | string | Investor's self-declared suitability profile. Optional. | **[investment_suitability Enumerators](#investment_suitability-enumerators)** | | `address` * | object | Object referencing the address | **[address object](#address-object)** | ### Address Object | Field | Type | Description | Max Characters | | ----------------- | ------ | -------------------------------------------- | ---------------- | | `street` * | string | Street name of the address. | 500 | | `neighborhood` * | string | Neighborhood name of the address. | 100 | | `number` * | string | Address number. | 10 | | `postal_code` * | string | Address postal code (format "XXXXX-XXX"). | 8 | | `city` * | string | City name of the address. | 255 | | `state` * | string | State abbreviation (2 characters). | 2 | | `complement` | string | Address complement, if applicable. | 100 | ### company_type Enumerators | Enum | Description | | -------- | ------------------ | | `ltda` | Limited Company | | `sa` | Sociedade Anônima | | `cop` | Cooperative | ### marital_status Enumerators | Enum | Description | | ------------- | ------------ | | `single` | Single | | `married` | Married | | `divorced` | Divorced | | `widowed` | Widowed | | `separated` | Separated | ### property_system Enumerators | Enum | Description | | ---------------------------------------- | --------------------------------------- | | `total_communion_of_goods` | Universal community of property | | `partial_communion_of_goods` | Partial community of property | | `total_separation_of_goods` | Total separation of property | | `final_participation_of_acquisitions` | Final participation in acquisitions | | `compulsory_separation_of_goods` | Mandatory separation of property | ### nationality Enumerators Full list of [ISO 3166-1 alpha-3](https://www.iso.org/obp/ui/#search) codes (e.g., `BRA` for Brazil, `USA` for the United States). ### investor_category Enumerators | Enum | Description | | ------------------ | ------------------ | | `not_applicable` | Not applicable | | `retail` | Retail | | `qualified` | Qualified | | `professional` | Professional | ### investment_suitability Enumerators | Enum | Description | | ------------- | ------------- | | `conservative` | Conservative | | `moderate` | Moderate | | `bold` | Bold | ## Response STATUS 201 Case 01: Legal Entity ```json { "investor_key": "123e4567-e89b-12d3-a456-426614174000", "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "status": "in_filling", "person_type": "legal", "trading_name": "Exemplo Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2023-01-01T12:00:00Z", "expiration_date": "2024-01-01T12:00:00Z" } ``` Case 02: Natural Person ```json { "investor_key": "9f8e7d6c-5b4a-3210-9876-543210fedcba", "name": "Maria Exemplo da Silva", "document_number": "123.456.789-00", "status": "in_filling", "person_type": "natural", "document_identification_number": "12.345.678-9", "marital_status": "single", "birthdate": "1990-05-14", "nationality": "BRA", "occupation": "software engineer", "is_pep": false, "investor_category": "retail", "investment_suitability": "moderate", "address": { "street": "Rua Exemplo", "neighborhood": "Centro", "number": "45", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Apto 12" }, "registration_datetime": "2023-01-01T12:00:00Z", "expiration_date": "2024-01-01T12:00:00Z", "investor_contact_information_list": [ { "investor_contact_information_key": "3f1e2d3c-4b5a-6978-8899-aabbccddeeff", "name": "Maria Exemplo da Silva", "document_number": "123.456.789-00", "email": "maria.exemplo@example.com", "phone_number": "+5511999999999", "is_default": true } ], "signer_group_list": [ { "signer_group_key": "7a6b5c4d-3e2f-1a0b-9c8d-1234567890ab", "minimum_required_signers": 1, "signers": [ { "name": "Maria Exemplo da Silva", "document_number": "123.456.789-00", "email": "maria.exemplo@example.com", "phone_number": "+5511999999999", "is_group_mandatory": true } ] } ] } ``` :::info Information `investor_contact_information_list` and `signer_group_list` are only returned when the registration is done with full access (`data_access_type == full_access`). ::: ### Response Body Params | Field | Type | Person | Description | Max Characters | | ------------------------- | ------- | ----------- | ----------------------------------------- | ----------------------------------------------------------------- | | `investor_key` | string | Both | Unique investor key (UUID). | 36 | | `name` | string | Both | Full name (PF) or company name (PJ). | 255 | | `document_number` | string | Both | Investor's CPF (PF) or CNPJ (PJ). | 14 | | `status` | string | Both | Investor status. | - | | `person_type` | string | Both | Person type | **[person_type Enumerators](#person_type-enumerators)** | | `trading_name` | string | PJ only | Investor trade name. | 1023 | | `cnae_code` | string | PJ only | Investor CNAE code. | 7 | | `company_type` | string | PJ only | Company type | **[company_type Enumerators](#company_type-enumerators)** | | `foundation_date` | string | PJ only | Investor foundation date. | - | | `document_identification_number` | string | PF only | Investor's identity document number. | 255 | | `marital_status` | string | PF only | Investor's marital status. | **[marital_status Enumerators](#marital_status-enumerators)** | | `birthdate` | string | PF only | Investor's date of birth. | - | | `nationality` | string | PF only | Investor's nationality. | **[nationality Enumerators](#nationality-enumerators)** | | `occupation` | string | PF only | Investor's occupation/profession. | 255 | | `is_pep` | boolean | PF only | Indicates whether the investor is a PEP. | - | | `investor_category` | string | PF only | Investor's self-declared category. | **[investor_category Enumerators](#investor_category-enumerators)** | | `investment_suitability`| string | PF only | Self-declared suitability profile. | **[investment_suitability Enumerators](#investment_suitability-enumerators)** | | `address` | object | Both | Object referencing the address | **[address object](#address-object)** | | `investor_contact_information_list` | array | PF only | Investor's contact information list. Only with `data_access_type == full_access`. | - | | `signer_group_list` | array | PF only | Investor's signer group list. Only with `data_access_type == full_access`. | - | | `registration_datetime` | string | Both | Investor registration date and time. | - | | `expiration_date` | string | Both | Investor expiration date. | - | ### person_type Enumerators | Enum | Description | | ----------- | ---------------- | | `legal` | Legal Entity | | `natural` | Natural Person | --- # Investor Bank Account Registration URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor This endpoint allows registering a bank account associated with a previously registered investor. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account METHOD POST ### Path Params | Field | Type | Description | Characters | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | ### Request Body Request Body ```json { "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ``` ### Request Body Params | Field | Type | Description | Max Characters | | -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- | | `account_number` * | string | Bank account number. Must contain only digits. | 20 | | `account_digit` * | string | Account verification digit. Must contain a single digit. | 1 | | `account_branch` * | string | Bank branch number. Must contain only digits. | 6 | | `financial_institution_code_number`* | string | Financial institution code (3 digits). | 3 | | `financial_institution_ispb` * | string | Financial institution ISPB code (8 digits). | 8 | | `account_type` * | string | Bank account type. | **[account_type Enumerators](#account_type-enumerators)** | ### account_type Enumerators | Enum | Description | | ------------ | ------------------ | | `checking` | Checking Account | | `savings` | Savings Account | | `salary` | Salary Account | | `payment` | Payment Account | ## Response STATUS 201 Response Body ```json { "bank_account_key": "123e4567-e89b-12d3-a456-426614174000", "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ``` ### Response Body Params | Field | Type | Description | Max Characters | | ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `bank_account_key` | string | Unique identifier of the registered bank account (UUID v4). | 36 | | `account_number` | string | Bank account number. | 20 | | `account_digit` | string | Bank account verification digit. | 1 | | `account_branch` | string | Bank branch number. | 6 | | `financial_institution_code_number` | string | Financial institution code. | 3 | | `financial_institution_ispb` | string | Financial institution ISPB code. | 8 | | `account_type` | string | Bank account type. | **[account_type Enumerators](#account_type-enumerators)** | --- # Investor Bank Account Removal URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao This endpoint allows removing bank account associated with a previously registered investor. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account/ BANK-ACCOUNT-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |--------------------|--------|------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | | `BANK-ACCOUNT-KEY` | string | Unique key of the bank account to be removed (UUID v4).| 36 | --- ## Response STATUS 204 No content is returned in the response body. --- --- # Investor Documents Submission URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor This endpoint allows submitting documents associated with a previously registered investor. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /document METHOD POST ### Path Params | Field | Type | Description | Characters | |---------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "proof_of_address" } ``` ### Request Body Params | Field | Type | Description | Max Characters | |--------------------|----------|------------------------------------------------------------------------------------------|---------------------------------------------------------------| | `document_base64` *| string | Document file content encoded in Base64. | - | | `document_type` * | string | Type of document submitted. Accepted values vary according to the investor's `person_type`. | **[document_type Enumerators](#document_type-enumerators)** | ### document_type Enumerators Accepted values depend on the investor's `person_type`. **Legal Entity** | Enum | Description | |--------|-----------------------------| | `danfe` | DANFE | | `proof_of_address` | Proof of Address | | `letter_of_attorney` | Power of Attorney | | `company_statute` | Company Contract or Statute | **Natural Person** | Enum | Description | |--------|-----------------------------| | `cnh` | Driver's License (CNH) | | `cnh_front` | CNH Front | | `cnh_back` | CNH Back | | `cnh_digital` | Digital CNH PDF | | `rg_front` | RG Front | | `rg_back` | RG Back | | `passport` | Passport | ## Response STATUS 201 Response Body ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_address", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ``` ### Response Body Params | Field | Type | Description | Max Length | |-----------------|----------|--------------------------------------------------------------------|------------| | `document_key` | string | Unique identifier of the submitted document (UUID v4). | 36 | | `document_type` | string | Type of document submitted. | **[document_type Enumerators](#document_type-enumerators)** | | `ocr_key` | string | OCR key associated with the submitted document. | 36 | --- # Investor Documents Removal URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao This endpoint allows removing documents submitted for investor registration. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /document/ DOCUMENT-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |----------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Unique key of the document to be removed (UUID v4). | 36 | ## Response STATUS 204 No content is returned in the response body. --- # Investor Representative Documents Submission URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor This endpoint allows submitting documents associated with a representative of a previously registered investor. :::danger Attention It is not possible to add representative documents for a Natural Person (PF) investor. ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document METHOD POST ### Path Params | Field | Type | Description | Characters | |-----------------------------|--------|---------------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | Unique investor representative key (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### Request Body Params | Field | Type | Description | Max Characters | |--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------| | `document_base64` *| string | Document file content encoded in Base64. | - | | `document_type` * | string | Type of document submitted. Accepted values: | **[document_type Enumerators](#document_type-enumerators)** | ### document_type Enumerators | Enum | Description | |--------|-------------------------| | `cnh` | Driver's License | | `cnh_front` | Driver's License Front | | `cnh_back` | Driver's License Back | | `cnh_digital` | Digital Driver's License PDF | `rg_front` | ID Front | | `rg_back` | ID Back | | `danfe` | DANFE | | `proof_of_address` | Proof of Address | | `letter_of_attorney` | Power of Attorney | ## Response STATUS 201 Response Body ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ``` ### Response Body Params | Field | Type | Description | Max Characters | |------------------|----------|-----------------------------------------------------|-----------------------| | `document_key` | string | Unique identifier of the submitted document (UUID v4). | 36 | | `document_type` | string | Type of document submitted. | **[document_type Enumerators](#document_type-enumerators)** | | `ocr_key` | string | OCR key associated with the submitted document. | 36 | --- # Investor Representative Documents Removal URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao This endpoint allows removing documents associated with a representative of a previously registered investor. :::danger Attention It is not possible to remove representative documents from a Natural Person (PF) investor. ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |-----------------------------|--------|---------------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | Unique investor representative key (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Unique key of the document to be removed (UUID v4). | 36 | ## Response STATUS 204 No content is returned in the response body. --- # Investor Contact Information Registration URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor This endpoint allows registering contact information associated with a previously registered investor. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information METHOD POST ### Path Params | Field | Type | Description | Characters | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | ### Request Body Request Body ```json { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ``` ### Request Body Params | Field | Type | Description | Max Characters | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Full name of the contact. | 255 | | `document_number` * | string | Contact's document number (CPF format, "XXX.XXX.XXX-XX"). | 11 | | `email`* | string | Contact's email address. | 1023 | | `phone_number`* | string | Contact's phone number (complete format: country code, area code and number. Example: +5511999999999). | 20 | ## Response STATUS 201 Response Body ```json { "investor_contact_information_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ``` ### Response Body Params | Field | Type | Description | Max Characters | | ------------------------------------ | ------ | --------------------------------------------------------------------- | --------------------- | | `investor_contact_information_key` | string | Unique identifier of the registered contact information (UUID v4). | 36 | | `name` | string | Full name of the contact. | 255 | | `document_number` | string | Contact's document number (CPF). | 11 | | `email` | string | Contact's email address. | 1023 | | `phone_number` | string | Contact's phone number. | 20 | --- # Investor Contact Information Removal URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao This endpoint allows removing contact information associated with a previously registered investor. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information/ INVESTOR-CONTACT-INFORMATION-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |----------------------------------|--------|-----------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | | `INVESTOR-CONTACT-INFORMATION-KEY` | string | Unique key of the contact information to be removed (UUID v4).| 36 | ## Response STATUS 204 No content is returned in the response body. --- # Investor Representatives Registration URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor This endpoint allows registering representatives associated with a previously registered investor. :::danger Attention It is not possible to add a representative for a Natural Person (PF) investor. ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative METHOD POST ### Path Params | Field | Type | Description | Characters | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | ### Request Body Request Body ```json { "name": "João da Silva", "document_number": "123.456.789-01", "birthdate": "1990-01-01", "nationality": "Brasileiro", "mother_name": "Maria da Silva", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" } } ``` ### Request Body Params | Field | Type | Description | Max Characters | | ----------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | `name` * | string | Full name of the investor representative. | 255 | | `document_number` * | string | Document number (CPF, format "XXX.XXX.XXX-XX"). | 11 | | `birthdate`* | string | Representative's birth date in ISO 8601 format (YYYY-MM-DD). | - | | `document_identification_number`* | string | Document identification number. | 255 | | `marital_status`* | string | Representative's marital status. | **[marital_status Enumerators](#marital_status-enumerators)** | | `property_system`* | string | Property regime. | **[property_system Enumerators](#property_system-enumerators)** | | `nationality`* | string | Representative's nationality. | 255 | | `mother_name` | string | Representative's mother's full name. | 1023 | | `father_name` | string | Representative's father's full name. | 1023 | | `occupation`* | string | Representative's occupation or profession. | 255 | | `is_pep`* | boolean | Indicates if the representative is a Politically Exposed Person (PEP). | - | | `address` * | string | Object referencing the address | **[address object](#address-object)** | ### Address Object | Field | Type | Description | Max Characters | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | Street name of the company address. | 500 | | `neighborhood` | string | Neighborhood name of the company address. | 100 | | `number` * | string | Address number. | 10 | | `postal_code` * | string | Address postal code (numbers only). | 8 | | `city` * | string | City name of the address. | 255 | | `state` * | string | State abbreviation (2 characters). | 2 | | `complement` | string | Address complement, if applicable. | 100 | ### marital_status Enumerators | Enum | Description | | ---------------- | ------------------ | | `single` | Single | | `married` | Married | | `widower` | Widowed | | `separated` | Separated | | `stable_union` | In Stable Union | | `divorced` | Divorced | ### property_system Enumerators | Enum | Description | | --------------------------------------- | --------------------------------- | | `total_communion_of_goods` | Total Communion of Goods | | `partial_communion_of_goods` | Partial Communion of Goods | | `total_separation_of_goods` | Total Separation of Goods | | `final_participation_of_acquisitions` | Final Participation in Acquisitions | | `compulsory_separation_of_goods` | Compulsory Separation of Goods | ## Response STATUS 201 Response Body ```json { "investor_representative_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "document_identification_number": "987654321", "marital_status": "single", "property_system": "partial_communion_of_goods", "birthdate": "1990-01-01", "nationality": "Brasileiro", "mother_name": "Maria da Silva", "father_name": "José da Silva", "occupation": "Advogado", "is_pep": false, "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "investor_representative_document_list": [] } ``` ### Response Body Params | Field | Type | Description | Max Characters | | ----------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | `investor_representative_key` | string | Unique identifier of the investor representative (UUID v4). | 36 | | `name` | string | Full name of the investor representative. | 255 | | `document_number` | string | Representative's document number (CPF format). | 11 | | `document_identification_number` | string | Document identification number. | 255 | | `marital_status` | string | Representative's marital status. | **[marital_status Enumerators](#marital_status-enumerators)** | | `property_system` | string | Property regime. | **[property_system Enumerators](#property_system-enumerators)** | | `birthdate` | string | Representative's birth date. | - | | `nationality` | string | Representative's nationality. | 255 | | `mother_name` | string | Representative's mother's full name. | 1023 | | `father_name` | string | Representative's father's full name. | 1023 | | `occupation` | string | Representative's occupation or profession. | 255 | | `is_pep` | boolean | Indicates if the representative is a Politically Exposed Person (PEP). | - | | `address` * | string | Object referencing the address | **[address object](#address-object)** | | `investor_representative_document_list` | array | List of documents associated with the representative. | - | --- # Investor Representative Removal URL: /en/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao This endpoint allows removing representatives submitted for investor registration. :::danger Attention It is not possible to remove a representative from a Natural Person (PF) investor. ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY METHOD DELETE ### Path Params | Field | Type | Description | Characters | |-----------------------------|--------|--------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | Unique key of the representative to be removed (UUID v4). | 36 | ## Response STATUS 204 No content is returned in the response body. --- # Get Investor URL: /en/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave This endpoint allows querying the complete details of an investor registered in the system, using their unique key. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY METHOD GET ### Path Params | Field | Type | Description | Characters | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | ## Response STATUS 200 Response Body ```json { "investor_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "in_filling", "backoffice_analysis_status": "in_analysis", "person_type": "legal", "trading_name": "Fabrica Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2025-01-23T13:47:57.354528", "expiration_date": "2026-01-23", "signer_group_list": [], "bank_account_list": [], "investor_representative_list": [], "investor_contact_information_list": [], "investor_document_list": [], "investor_analysis_list": [] } ``` ### Response Body Params | Field | Type | Description | Max Characters | |--------|----------|--------------------------------------------------------|-----------------------| | `investor_key` | string | Unique investor identifier. | 36 | | `name` | string | Full investor name. | 255 | | `document_number` | string | Investor document number (CNPJ). | 14 | | `status` | string | Investor status | **[status Enumerators](#status-enumerators)** | | `backoffice_analysis_status`| string | Backoffice analysis status. | - | | `person_type` | string | Person type (`legal` or `natural`). | - | | `trading_name` | string | Investor trade name. | 1023 | | `cnae_code` | string | Investor CNAE code. | 7 | | `company_type` | string | Company type Accepted: ´sa´, ´ltda´, ´cop´ | 50 | | `foundation_date` | string | Investor foundation date. | - | | `signer_group_list` | array | List of signer groups associated with the investor. | - | | `bank_account_list` | array | List of bank accounts associated with the investor. | - | | `investor_representative_list` | array | List of investor representatives. | - | | `investor_contact_information_list` | array | List of contact information associated with the investor. | - | | `investor_document_list` | array | List of documents registered for the investor. | - | | `address` * | string | Object referencing the address | **[address object](#address-object)**| ### Address Object | Field | Type | Description | Max Characters | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` * | string | Street name of the company address. | 500 | | `neighborhood` | string | Neighborhood name of the company address. | 100 | | `number` * | string | Address number. | 10 | | `postal_code` * | string | Address postal code (numbers only). | 8 | | `city` * | string | City name of the address. | 255 | | `state` * | string | State abbreviation (2 characters). | 2 | | `complement` | string | Address complement, if applicable. | 100 | ### status Enumerators | Enum | Description | |--------|-----------------| | `in_filling` | In filling | | `in_analysis` | Under analysis | | `canceled` | Canceled | | `approved` | Approved | | `reproved` | Rejected | | `expired` | Expired | --- # Investor Query by Filters URL: /en/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro This endpoint allows querying investors registered in the system using document number (CNPJ) or Name. --- ## Request ENDPOINT /investor_management/investor METHOD GET ### Query Params | Field | Type | Description | Required | |-------------------|----------|------------------------------------|-------------| | `document_number` | string | Investor document number. | No | | `name` | string | Investor name. | No | | `page` | integer | Current page of the query. | No | | `rows_per_page` | integer | Number of records per page. | No | ## Response STATUS 200 Response Body ```json { "data": [ { "investor_key": "495ae701-5c38-49b1-b517-a3b910fe8d8f", "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "status": "in_filling" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 1 } } ``` ### Response Body Params | Field | Type | Description | | |--------------|--------|---------------------|-----------------------------------------------------------------| | `data` | list | Results list | **[Simplified Investor Object](#simplified-investor-object)** | | `pagination` | object | Pagination data | **[Pagination Object](#pagination-object)** | ### Simplified Investor Object | Field | Type | Description | Max Characters | |-------------------|----------|-------------------------------------------------------------|-------------------------------------------------| | `investor_key` | string | Unique investor identifier (UUID v4). | 36 | | `name` | string | Full investor name. | 255 | | `document_number` | string | Investor document number (CNPJ). | 14 | | `status` | string | Current investor status. | **[status enumerators](#status-enumerators)** | ### status enumerators | Enum | Description | |--------|-----------------| | `in_filling` | In filling | | `in_analysis` | Under analysis | | `canceled` | Canceled | | `approved` | Approved | | `reproved` | Rejected | | `expired` | Expired | ### Pagination Object | Field | Type | Description | |-------------------|----------|------------------------------------------| | `current_page` | integer | Current page of the query. | | `next_page` | integer | Next page, if it exists. | | `rows_per_page` | integer | Number of records per page. | | `total_pages` | integer | Total number of pages. | | `total_rows` | integer | Total number of records found. | --- # Investor Analysis Submission URL: /en/documentation/escrituracao/homologacao-investidor/envio-analise/ This endpoint allows changing an investor's status to analysis, sending it to the validation process. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY METHOD PATCH ### Path Params | Field | Type | Description | Characters | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | ### Request Body Request Body ```json { "investor_status": "in_analysis" } ``` ### Request Body Params | Field | Type | Description | Required | |------------------|----------|-------------------------------------------------|-------------| | `investor_status` | string | New investor status. Accepted value: `in_analysis`. | Yes | ## Response The response is a complete updated JSON of the investor. --- # Introduction URL: /en/documentation/escrituracao/homologacao-investidor/inicio The investor registration section is essential for the beginning of Commercial Paper issuance. In this section we will explain the entire flow, from sending the first information, to sending for analysis. To have access to the services discussed in the next sessions, contact the team [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br), so that the proper releases can be made, both in the Sandbox environment and in the production environment. ### Investor Registration At this stage, all information about both the Investor and their representatives, documents, contact information, subscriber groups and bank accounts must be sent. Once the information submission is completed, the registration is sent for analysis and after approval this investor will be able to participate in the Commercial Paper issuance. ### Investor Update In case of need for registration updates, all Investor information must be sent again with the desired modifications. After submission, a new Analysis is generated for validation. As soon as this new Analysis is approved, the new Investor registration data is effectively changed. --- # **Investor Data Access Request** URL: /en/documentation/escrituracao/homologacao-investidor/solicitacao-acesso Clients who registered an investor that already has a **unique registration** need to **request access to the investor's data** so they can issue operations with that investor as a party. When making this request, the **investor will receive an email with instructions to approve or deny access**. --- ## **Access Request (POST)** ### **Request** ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request METHOD POST ### **Path Params** | Field | Type | Description | Max Characters | |---------------|--------|-----------------------------------------------|-----------------| | `INVESTOR-KEY` * | string | Unique investor key (UUID v4). | 36 | --- ## **Request Body** No request body is required. --- ## **Response** STATUS 201 Response Body ```json { "data_access_request_key": "6beb9e44-1513-4d3b-9af5-f3c39ebbf2d0", "requested_at": "2025-02-22T10:45:49.609517", "responded_at": null, "data_access_request_status": "in_analysis" } ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |--------------------------------|----------|-------------------------------------------------------------|-----------------| | `data_access_request_key` * | string | Unique access request key (UUID v4). | 36 | | `requested_at` * | string | Date and time of the request (ISO 8601 format). | - | | `responded_at` | string | Date and time of the response to the request, if already responded. | - | | `data_access_request_status` * | string | Request status. | **[data_access_request_status Enumerators](#data_access_request_status-enumerators)** | --- ## **Request Status Query (GET)** Clients can check if their request was approved, denied or is still under analysis. ## **Request** ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request METHOD GET ### **Path Params** | Field | Type | Description | Max Characters | |---------------|--------|-----------------------------------------------|-----------------| | `INVESTOR-KEY` * | string | Unique investor key (UUID v4). | 36 | ## **Response** STATUS 200 Response Body ```json [ { "data_access_request_key": "6beb9e44-1513-4d3b-9af5-f3c39ebbf2d0", "requested_at": "2025-02-22T10:45:49.609517", "responded_at": null, "data_access_request_status": "in_analysis" } ] ``` ### **Response Body Params** | Field | Type | Description | Max Characters | |--------------------------------|----------|-------------------------------------------------------------|-----------------| | `data_access_request_key` * | string | Unique access request key (UUID v4). | 36 | | `requested_at` * | string | Date and time of the request (ISO 8601 format). | - | | `responded_at` | string | Date and time of the response to the request, if already responded. | - | | `data_access_request_status` * | string | Request status. | **[data_access_request_status Enumerators](#data_access_request_status-enumerators)** | --- ## **data_access_request_status Enumerators** | Enum | Description | |-------------|------------------------------------------------------| | `in_analysis` | The request is under analysis by the investor. | | `approved` | Access was approved and the client can view the investor's data. | | `reproved` | The request was denied and the client will not be able to access the investor's data. | --- # Get Transaction Receipt URL: /en/documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao This endpoint returns the receipt (PDF + metadata) of one of the BaaS TEDs that QI Tech executed for an integralization. A single integralization cycle (investor payment → fees → disbursement) can produce multiple TEDs — pick the one you want with the `transaction_type` query parameter. If multiple TEDs of the same type were executed for the same integralization (e.g., several `extraordinary_event_payment`), this endpoint returns only the most recent one. To list all of them, use **[Get Integralization Transactions](./consulta-transacoes-integralizacao.md)**. --- ## Get Transaction Receipt (GET) ### Request ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transaction_receipt METHOD GET ### Path Params | Field | Type | Description | Characters | |-----------------------|--------|--------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Unique integralization key (UUID v4). | 36 | ### Query Params | Field | Type | Description | Required | |--------------------|--------|------------------------------------------------------------------------------------------|----------| | `transaction_type` | string | Type of TED to fetch. **[transaction_type enums](#transaction_type-enums)** | Yes | --- ### Response STATUS 200 Response Body ```json { "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec", "transaction_amount": 12345.67, "transaction_status": "settled", "pdf_encoded_string": "JVBERi0xLi4u..." } ``` --- ### Response Body Params | Field | Type | Description | |----------------------|--------|------------------------------------------------------------------------------------------------------| | `transaction_key` | string | Unique BaaS-side TED key — same value returned by `consulta-transacoes-integralizacao`. | | `transaction_amount` | number | TED amount as recorded by QI Tech. | | `transaction_status` | string | TED status on the BaaS side (e.g., `settled`, `paid`). | | `pdf_encoded_string` | string | Bank receipt as a base64-encoded string. Decode it to retrieve the PDF. | --- ### transaction_type enums | Enum | Description | |-------------------------------|------------------------------------------------------------------------------------------| | `disbursement` | TED that delivered the issuer's net amount to the issuer's bank account. | | `bookkeeping_fee_internal` | TED to QI CTVM for the internal bookkeeping fee. | | `bookkeeping_fee_external` | TED to the client's external bookkeeping account. | | `structuring_fee` | TED to the client's structuring account. | | `extraordinary_event_payment` | TED to an investor for an extraordinary settlement event. | --- ### Errors | HTTP | Code | When | |------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| | 400 | `HTTPMissingParam` | The `transaction_type` query parameter was not provided. | | 400 | `HTTPInvalidParam` | `transaction_type` is not one of the allowed values. | | 404 | `ACL000004` (`IntegralizationTransactionNotFound`) | No TED of the requested type exists for the integralization, OR the integralization was never settled (no TEDs). | :::note A 404 with `ACL000004` is returned identically in every scenario (unknown key, never-settled integralization, or missing TED type) — by design, we don't differentiate the cases. To check whether an integralization exists, list its transactions first. ::: --- # Settlement Account Query URL: /en/documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao This endpoint allows you to query the details of an issuer's settlement account — banking data (branch, account, digit), status and, when the account is already open, owner information and balances. While the account has not yet been opened in the BaaS, the endpoint returns only the basic data with `account_status: "pending"`. After the opening, the response includes the additional owner and balance fields. --- ## Settlement Account Query (GET) ### Request ENDPOINT /account_liquidation/issuer/ ISSUER-KEY METHOD GET ### Path Params | Field | Type | Description | Characters | |--------------|--------|--------------------------------------|------------| | `ISSUER-KEY` | string | Unique key of the issuer (UUID v4). | 36 | --- ### Response STATUS 200 Response Body — open account ```json { "issuer_key": "23d933e9-88ba-4291-a6a4-33f025ab361f", "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154", "bank_account_key": "8f2a6f10-3c43-4a3b-9f5e-2a9a1d4be0c1", "request_account_key": "1c0a2e54-77a8-4f0e-8d8e-6f2b9b3c1d22", "account_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec", "account_branch": "0001", "account_number": "1234567", "account_digit": "8", "account_status": "opened", "account_type": "payment_account", "account_documents": [], "balance": 12345.67, "blocked_balance": 0.0, "owner_document_number": "12345678000190", "owner_name": "Emissor Exemplo LTDA", "owner_person_key": "9b1f3c77-5a2d-4e8f-b6a0-3d2c1e0f9a88", "created_at": "2026-01-15T12:34:56" } ``` Response Body — pending account ```json { "issuer_key": "23d933e9-88ba-4291-a6a4-33f025ab361f", "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154", "bank_account_key": "8f2a6f10-3c43-4a3b-9f5e-2a9a1d4be0c1", "request_account_key": "1c0a2e54-77a8-4f0e-8d8e-6f2b9b3c1d22", "account_branch": "0001", "account_number": "1234567", "account_digit": "8", "account_status": "pending" } ``` --- ### Response Body Params | Field | Type | Description | |-------------------------|--------|---------------------------------------------------------------------------------------------| | `issuer_key` | string | Unique key of the issuer. | | `tenant_key` | string | Unique key of the client that owns the account. | | `bank_account_key` | string | Unique key of the bank account in the BaaS. | | `request_account_key` | string | Unique key of the account opening request. | | `account_key` | string | Unique key of the account in the BaaS. Present only once the account has been opened. | | `account_branch` | string | Account branch. | | `account_number` | string | Account number. | | `account_digit` | string | Account digit. | | `account_status` | string | Account status. `pending` while the opening has not been completed. | | `account_type` | string | Account type in the BaaS. Present only once the account has been opened. | | `account_documents` | array | Documents associated with the account. Present only once the account has been opened. | | `balance` | number | Available balance of the account. Present only once the account has been opened. | | `blocked_balance` | number | Blocked balance of the account. Present only once the account has been opened. | | `owner_document_number` | string | CPF/CNPJ of the account owner. Present only once the account has been opened. | | `owner_name` | string | Name of the account owner. Present only once the account has been opened. | | `owner_person_key` | string | Unique key of the owner in the BaaS. Present only once the account has been opened. | | `created_at` | string | Account creation date. Present only once the account has been opened. | --- ### Errors | HTTP | Code | When it occurs | |------|----------------------------------------------------------|-------------------------------------------------------------------------------| | 404 | `ACL000002` (`IssuerAccountLiquidationNotFound`) | There is no settlement account for the informed issuer. | | 400 | `ACL000003` (`IssuerAccountLiquidationNotBelongToTenant`) | The issuer's settlement account does not belong to the client that made the request. | --- # Get Integralization by Key URL: /en/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao This endpoint allows querying the details of an integralization process using its unique key. --- ## Integralization Process (GET) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY METHOD GET ### Path Params | Field | Type | Description | Characters | |------------------------|--------|------------------------------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Unique integralization key (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "tenant_key": "39a0d458-c06f-41e7-92cf-a335cea90675", "integralization_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753", "operation_key": "c9cc8980-25b2-49ec-ac40-2a12b8df9dfc", "operation_type": "commercial_paper", "contract_number": "0000000002", "issue_number": 1, "issue_series": 1, "issuer_key": "1bc06a53-9503-4520-916c-38b5a6bb5912", "issuer_name": "Advanced Solutions", "issuer_document_number": "05120047000102", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "subscripted_quantity": 1000000, "subscripted_total_amount": 1000000.0, "integralized_quantity": 1000000, "issue_quantity": 1000000, "integralization_status": "finished", "subscription_list": [ { "subscription_key": "5a2100db-6bad-4fc7-9b5f-390543c63c55", "investor_key": "2d14cfef-7b95-4aa4-be0c-860ec8a60934", "investor_name": "Dynamic Group", "investor_document_number": "99525109000100", "investor_bank_account": { "account_digit": "0", "account_branch": "1234", "account_number": "12345678", "financial_institution_ispb": "12345678", "financial_institution_code_number": "001" }, "subscription_date": "2025-01-27", "financial_base_date": "2025-01-27", "subscripted_quantity": 1000000, "unit_price": 1.0, "expected_amount": 1000000.0, "paid_amount": 1000000.0, "subscription_note_template_key": "8bfba2a3-1cda-45c4-9a97-05b2bf31e486", "subscription_note_document_key": "c9cc8980-25b2-49ec-ac40-2a12b8df9dfc/5a2100db-6bad-4fc7-9b5f-390543c63c55/subscription_note/8b6867d8-95c8-4e0d-b670-6a7d06f3acf7", "subscription_note_signature_status": "pending_creation", "subscription_payment_list": [ { "subscription_payment_key": "edf8a4cc-24c9-4dd9-8cae-9cb9151b40bf", "payment_receipt_document_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753/5a2100db-6bad-4fc7-9b5f-390543c63c55/subscription_payment/edf8a4cc-24c9-4dd9-8cae-9cb9151b40bf", "description": "Comprovante itau", "amount": 1000000.0, "subscription_payment_status": "confirmed", "updated_at": "2025-01-27T14:30:18.741983" } ] } ] } ``` --- ### Response Body Params | Field | Type | Description | |------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------| | `tenant_key` | string | Unique key of the tenant associated with the integralization. | | `integralization_key` | string | Unique integralization key. | | `operation_key` | string | Unique key of the associated operation. | | `operation_type` | string | Operation type. Possible values: `commercial_paper`. | | `contract_number` | string | Contract number associated with the integralization. | | `issue_number` | integer | Issue number associated with the integralization. | | `issue_series` | integer | Issue series associated with the integralization. | | `issuer_key` | string | Unique key of the associated issuer. | | `issuer_name` | string | Name of the issuer associated with the integralization. | | `issuer_document_number` | string | Issuer document number | | `issuer_bank_account` | object | Issuer bank account data. | | `issuer_bank_account.account_type` | string | Bank account type (`checking`, etc.). | | `issuer_bank_account.account_digit` | string | Bank account verification digit. | | `issuer_bank_account.account_branch` | string | Bank branch. | | `issuer_bank_account.account_number` | string | Bank account number. | | `issuer_bank_account.financial_institution_ispb` | string | Financial institution ISPB. | | `issuer_bank_account.financial_institution_code_number` | string | Financial institution code. | | `subscripted_quantity` | integer | Total quantity of subscribed shares. | | `subscripted_total_amount` | number | Total value of subscribed shares. | | `integralized_quantity` | integer | Total quantity of integralized shares. | | `issue_quantity` | integer | Total quantity of shares issued in the operation. | | `integralization_status` | string | Integralization status. Possible values: `pending`, `finished`. | | `subscription_list` | array | List of subscriptions associated with the integralization. **[subscription object](#subscription-object)** | ### subscription object | Field | Type | Description | |------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------------------------------------| | `subscription_key` | string | Unique subscription key. | | `investor_key` | string | Unique key of the investor associated with the subscription. | | `investor_name` | string | Investor name. | | `investor_document_number` | string | Investor document number (CPF or CNPJ). | | `investor_bank_account` | object | Investor bank data. | | `subscription_date` | string | Subscription date (format: YYYY-MM-DD). | | `financial_base_date` | string | Financial base date of the subscription (format: YYYY-MM-DD). | | `subscripted_quantity` | integer | Quantity of subscribed shares. | | `unit_price` | number | Unit price of shares. | | `expected_amount` | number | Total expected value of the subscription. | | `paid_amount` | number | Paid amount already confirmed of the subscription. | | `subscription_note_template_key` | string | Subscription note template key. | | `subscription_note_document_key` | string | Subscription note document key. | | `subscription_note_signature_status` | string | Subscription note signature status. | | `subscription_payment_list` | array | List of payments associated with the subscription. **[subscription_payment object](#subscription_payment-object)]** | ### subscription_payment object | Field | Type | Description | |------------------------------------------------------------------------|------------|----------------------------------------------------------------------------------------| | `subscription_payment_key` | string | Unique subscription payment key. | | `payment_receipt_document_key` | string | Payment receipt document key. | | `description` | string | Payment receipt description. | | `amount` | number | Registered payment amount. | | `subscription_payment_status` | string | Payment status. Possible values: `waiting_confirmation`, `confirmed`, `denied`. | | `updated_at` | string | Date and time of last payment update (format: ISO 8601). | --- # Get Integralization Transactions URL: /en/documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao This endpoint returns metadata for every BaaS TED executed by QI Tech for an integralization — without the PDF. Useful for discovering how many receipts exist, in what order they were executed, and their `transaction_key`. To get the PDF for a specific TED, use **[Get Transaction Receipt](./consulta-comprovante-transacao.md)**. The response is in chronological order (`created_at` ASC) and includes every TED in the cycle (disbursement, fees, and extraordinary events). When multiple TEDs of the same type exist (e.g., several `extraordinary_event_payment`), all of them appear here — unlike the receipt endpoint, which returns only the most recent. --- ## Get Transactions (GET) ### Request ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transactions METHOD GET ### Path Params | Field | Type | Description | Characters | |-----------------------|--------|--------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Unique integralization key (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json [ { "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec", "external_id": "072a7cc4-1fbf-419b-8a41-f57bd86ee753", "transaction_amount": 12345.67, "transaction_type": "disbursement", "transaction_status": "paid", "created_at": "2026-05-05T13:22:01" } ] ``` --- ### Response Body Params | Field | Type | Description | |----------------------|--------|----------------------------------------------------------------------------------------------------------| | `transaction_key` | string | Unique BaaS-side TED key. | | `external_id` | string | `integralization_key` the TED belongs to. | | `transaction_amount` | number | TED amount as recorded by QI Tech. Do not treat as the authoritative value for accounting reconciliation.| | `transaction_type` | string | TED type. **[transaction_type enums](./consulta-comprovante-transacao.md#transaction_type-enums)** | | `transaction_status` | string | Current TED status (e.g., `paid`, `settled`). | | `created_at` | string | Record creation timestamp (ISO 8601). | --- # Introduction to Shares Integralization URL: /en/documentation/escrituracao/integralizacao-cotas/inicio After completing the Commercial Paper issuance process, the operation will remain in issued status. By default, the share subscription process for integralization occurs automatically after signing the constitutive instrument. When consulting an operation in issued state, a field called `integralization_key` will be available through which the integralization process can be monitored. The integralization process consists of: - Share subscription - Subscription note signing - Payment registration - Payment confirmation --- # Subscription Registration URL: /en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao This endpoint allows registering an investor's intention to subscribe to a specific quantity of shares in an integralization. --- ## Subscription Registration (POST) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription METHOD POST ### Path Params | Field | Type | Description | Characters | | ----------------------- | ------ | ------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | Unique integralization key (UUID v4). | 36 | --- ### Request Body ```json { "investor_key": "123e4567-e89b-12d3-a456-426614174000", "investor_bank_account": { "account_number": "12345678", "account_digit": "0", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "12345678" }, "subscription_date": "2025-01-01", "financial_base_date": "2025-01-01", "subscription_note_template_key": "c649c01a-dd24-47b7-b93e-5a6bac50bcf0", "subscripted_quantity": 100000 } ``` ### Request Body Params | Field | Type | Description | | ------------------------------------------------------------ | ------- | ------------------------------------------------------- | | `investor_key`* | string | Unique investor key (UUID v4). | | `investor_bank_account`* | object | Investor bank account data. | | `investor_bank_account.account_number`* | string | Investor bank account number. | | `investor_bank_account.account_digit`* | string | Investor bank account verification digit. | | `investor_bank_account.account_branch`* | string | Investor bank branch. | | `investor_bank_account.financial_institution_code_number`* | string | Investor's financial institution code. | | `investor_bank_account.financial_institution_ispb`* | string | Investor's financial institution ISPB. | | `subscripted_quantity`* | integer | Quantity of shares the investor wants to subscribe to. | | `financial_base_date`* | string | Financial base date. | | `subscription_date`* | string | Subscription date. | | `subscription_note_template_key`* | string | Subscription bulletin template. | --- ### Response STATUS 201 Response Body ```json { "subscription_key": "2f7e00b5-988f-4214-bb46-4728d9081148", "investor_key": "a76e408a-c733-4a68-963a-dc93ff0bc3e3", "investor_name": "Global Enterprises", "investor_document_number": "89206257000108", "investor_bank_account": { "account_digit": "0", "account_branch": "1234", "account_number": "12345678", "financial_institution_ispb": "12345678", "financial_institution_code_number": "001" }, "subscription_date": "2025-01-27", "financial_base_date": "2025-01-27", "subscripted_quantity": 1000000, "unit_price": 1.0, "expected_amount": 1000000.0, "paid_amount": 1000000.0, "subscription_note_template_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80", "subscription_note_document_key": "5ea88fca-4ca3-4dfe-aea4-35e431aef3c5/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_note/f206d799-cb94-48d5-81c5-5988ecef8079", "envelope_signature_status": "pending_creation", "envelope_signature_url": "https://certifiqi.com.br/envelope_key", "envelope_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80", "subscription_payment_list": [ { "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "description": "Comprovante itau", "amount": 1000000.0, "subscription_payment_status": "confirmed", "updated_at": "2025-01-27T14:33:54.214891" } ] } ``` ### **Response Body Params** | Field | Type | Description | | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | `subscription_key` | string | Unique subscription key (UUID v4). | | `investor_key` | string | Unique key of the investor associated with the subscription (UUID v4). | | `investor_name` | string | Investor name. | | `investor_document_number` | string | Investor document number (CPF or CNPJ). | | `investor_bank_account` | object | **[investor_bank_account object](#investor_bank_account-object)**. | | `subscription_date` | string | Subscription date (format: YYYY-MM-DD). | | `financial_base_date` | string | Financial base date of the subscription (format: YYYY-MM-DD). | | `subscripted_quantity` | integer | Quantity of subscribed shares. | | `unit_price` | number | Unit price of subscribed shares. | | `expected_amount` | number | Total expected value of the subscription. | | `paid_amount` | number | Total amount paid in the subscription. | | `subscription_note_template_key` | string | Unique subscription note template key (UUID v4). | | `subscription_note_document_key` | string | Unique subscription note document key. | | `envelope_signature_status` | string | Subscription note signature status. | | `envelope_signature_url` | string | Subscription note signature URL. | | `envelope_key` | string | Signature envelope key. | | `subscription_payment_list` | array | List of payments associated with the subscription.**[subscription_payment_list object](#subscription_payment_list-object)**. | --- ### investor_bank_account object | Field | Type | Description | | ------------------------------------- | ------ | ----------------------------------------------------- | | `account_number` | string | Investor bank account number. | | `account_digit` | string | Investor bank account verification digit. | | `account_branch` | string | Investor bank branch. | | `financial_institution_code_number` | string | Investor's financial institution code. | | `financial_institution_ispb` | string | Investor's financial institution ISPB. | ### subscription_payment_list object | Field | Type | Description | | -------------------------------- | ------ | -------------------------------------------------------------------------------------------- | | `subscription_payment_key` | string | Unique subscription payment key (UUID v4). | | `payment_receipt_document_key` | string | Payment receipt document key. | | `description` | string | Payment receipt description. | | `amount` | number | Registered payment amount. | | `subscription_payment_status` | string | Payment status. Possible values:`waiting_confirmation`, `confirmed`, `denied`. | | `updated_at` | string | Date and time of last payment update (format: ISO 8601). | --- # Cancel Subscription URL: /en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao --- ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY METHOD PATCH ### Path Params | Field | Type | Description | Characters | |------------------|--------|------------------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Unique integralization process key (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Unique subscription key (UUID v4). | 36 | --- ### Request Body ```json { "subscription_status": "canceled" } ``` ### Request Body Params | Field | Type | Description | Required | |-------------------|----------|-----------------------------------------|-------------| | `subscription_status` | string | Accepted values: `canceled`. | Yes | --- ### Response STATUS 200 An updated copy of the Subscription will be returned. --- --- # Subscription Payment Confirmation or Rejection URL: /en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento This endpoint allows confirming or rejecting the payment associated with an integralization subscription. The payment status is updated according to the value provided in the request body. --- ## Payment Status Update (PATCH) ### Request ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment/ SUBSCRIPTION-PAYMENT-KEY METHOD PATCH ### Path Params | Field | Type | Description | Characters | | ---------------------------- | ------ | ---------------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | Unique integralization key (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Unique associated subscription key (UUID v4). | 36 | | `SUBSCRIPTION-PAYMENT-KEY` | string | Unique subscription payment key (UUID v4). | 36 | --- ### Request Body ```json { "subscription_payment_status": "confirmed" } ``` ### Request Body Params | Field | Type | Description | Required | | -------------------------------- | ------ | ------------------------------------------------------------------------- | ------------ | | `subscription_payment_status`* | string | New payment status. Possible values:`confirmed` or `denied`. | Yes | --- ### Response STATUS 200 Response Body ```json { "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "description": "Comprovante de pagamento Itau R$100.000,00", "amount": 100000.0, "subscription_payment_status": "waiting_confirmation", "updated_at": "2025-01-24T11:30:00Z" } ``` --- ### Response Body Params | Field | Type | Description | | ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | | `subscription_payment_key` | string | Unique subscription payment key (UUID v4). | | `amount` | number | Declared value of the registered payment. | | `description` | number | Description of the receipt content. | | `subscription_payment_status` | string | Updated payment status. Possible values:`waiting_confirmation` `confirmed`, `denied`. | | `updated_at` | string | Date and time of payment status update (format: ISO 8601). | --- # Get Subscription URL: /en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas This endpoint allows querying an ongoing subscription. --- ## Subscription Query (GET) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY METHOD GET ### Path Params | Field | Type | Description | Characters | |-----------------------|--------|------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Unique integralization key (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Unique subscription key (UUID v4). | 36 | --- ### Response STATUS 201 Response Body ```json { "subscription_key": "2f7e00b5-988f-4214-bb46-4728d9081148", "investor_key": "a76e408a-c733-4a68-963a-dc93ff0bc3e3", "investor_name": "Global Enterprises", "investor_document_number": "89206257000108", "investor_bank_account": { "account_digit": "0", "account_branch": "1234", "account_number": "12345678", "financial_institution_ispb": "12345678", "financial_institution_code_number": "001" }, "subscription_date": "2025-01-27", "financial_base_date": "2025-01-27", "subscripted_quantity": 1000000, "unit_price": 1.0, "expected_amount": 1000000.0, "paid_amount": 1000000.0, "subscription_note_template_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80", "subscription_note_document_key": "5ea88fca-4ca3-4dfe-aea4-35e431aef3c5/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_note/f206d799-cb94-48d5-81c5-5988ecef8079", "envelope_signature_status": "pending_creation", "envelope_signature_url": "https://certifiqi.com.br/envelope_key", "envelope_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80", "subscription_payment_list": [ { "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "description": "Comprovante itau", "amount": 1000000.0, "subscription_payment_status": "confirmed", "updated_at": "2025-01-27T14:33:54.214891" } ] } ``` --- ### **Response Body Params** | Field | Type | Description | |-----------------------------------------------------------|------------|---------------------------------------------------------------------------| | `subscription_key` | string | Unique subscription key (UUID v4). | | `investor_key` | string | Unique key of the investor associated with the subscription (UUID v4). | | `investor_name` | string | Investor name. | | `investor_document_number` | string | Investor document number (CPF or CNPJ). | | `investor_bank_account` | object | **[investor_bank_account object](#investor_bank_account-object)**. | | `subscription_date` | string | Subscription date (format: YYYY-MM-DD). | | `financial_base_date` | string | Financial base date of the subscription (format: YYYY-MM-DD). | | `subscripted_quantity` | integer | Quantity of subscribed shares. | | `unit_price` | number | Unit price of subscribed shares. | | `expected_amount` | number | Total expected value of the subscription. | | `paid_amount` | number | Total amount paid in the subscription. | | `subscription_note_template_key` | string | Unique subscription note template key (UUID v4). | | `subscription_note_document_key` | string | Unique subscription note document key. | | `envelope_signature_status` | string | Subscription note signature status. | | `envelope_signature_url` | string | Subscription note signature URL. | | `envelope_key` | string | Signature envelope key. | | `subscription_payment_list` | array | List of payments associated with the subscription. **[subscription_payment_list object](#subscription_payment_list-object)**. | --- ### investor_bank_account object | Field | Type | Description | |--------------------------------|------------|---------------------------------------------------------| | `account_number` | string | Investor bank account number. | | `account_digit` | string | Investor bank account verification digit. | | `account_branch` | string | Investor bank branch. | | `financial_institution_code_number` | string | Investor's financial institution code. | | `financial_institution_ispb` | string | Investor's financial institution ISPB. | ### subscription_payment_list object | Field | Type | Description | |-----------------------------------------------------------|------------|---------------------------------------------------------------------------| | `subscription_payment_key` | string | Unique subscription payment key (UUID v4). | | `payment_receipt_document_key` | string | Payment receipt document key. | | `description` | string | Payment receipt description. | | `amount` | number | Registered payment amount. | | `subscription_payment_status` | string | Payment status. Possible values: `waiting_confirmation`, `confirmed`, `denied`. | | `updated_at` | string | Date and time of last payment update (format: ISO 8601). | --- # Subscription Payment Registration URL: /en/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento This endpoint allows registering a payment associated with an integralization subscription. The payment includes a declared amount and a receipt in Base64. --- ## Payment Registration (POST) ### Request ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment METHOD POST ### Path Params | Field | Type | Description | Characters | | ----------------------- | ------ | ------------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | Unique integralization key (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Unique key of the associated subscription (UUID v4). | 36 | --- ### Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "amount": 100000.00, "description": "Comprovante de pagamento Itau R$100.000,00" } ``` ### Request Body Params | Field | Type | Description | Required | | -------------------- | ------- | ---------------------------------------------- | ------------ | | `document_base64`* | string | Payment receipt encoded in Base64. | Yes | | `amount`* | number | Declared amount of the payment made. | Yes | | `description` | string | Description of the receipt content. | Yes | --- ### Response STATUS 201 Response Body ```json { "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "description": "Comprovante de pagamento Itau R$100.000,00", "amount": 100000.0, "subscription_payment_status": "waiting_confirmation", "updated_at": null } ``` --- ### Response Body Params | Field | Type | Description | | ------------------------------- | ------ | ----------------------------------------------------------------------------------------------- | | `subscription_payment_key` | string | Unique subscription payment key (UUID v4). | | `amount` | number | Declared amount of the registered payment. | | `subscription_payment_status` | string | Current payment status. Possible values:`waiting_confirmation` `confirmed` `denied` | | `description` | string | Description of the receipt content. | --- --- # Receiving Webhooks URL: /en/documentation/escrituracao/introducao/autenticacao_webhooks Webhook signing uses a symmetric key encryption strategy, that is, both QI CTVM and the integrating partner share the same key. When we configure Webhooks, we will generate a Signature Key and make it available. Every request originated in the QI system, will carry a SIGNATURE header that will be a JWT signed with this key. The encoding is performed with the HS256 algorithm. Below we have a python example of how to perform signature decoding: ```python from jose import jwt signature_key = "UNIQUE CONFIGURED KEY" signature_token = headers["SIGNATURE"] decoded_token = jwt.decode(signature_token, key=signature_key, algorithms=["HS256"]) print(decoded_token) ``` We suggest that, in addition to comparing the signature, the integrating partner validates our IP, given that all our requests originate from the same IP, according to the environment: |Environment| IP | |--------|----| |Production| - | |Sandbox | - | :::danger Attention! QI CTVM webhooks should not be mapped restrictively. Additional fields may be included in the webhook payloads returned in our APIs. ::: --- # Commercial Paper Bookkeeping URL: /en/documentation/escrituracao/introducao/ This documentation aims to describe the flows, endpoints and data structures necessary to operate and issue **Commercial Paper**. Note: In case of doubts in any step of the process, please contact [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br) detailing your problem/question and we will assist you. ## Environments (Hosts) QI CTVM has two environments, SANDBOX and PRODUCTION. Both environments have completely identical code and behavior, however, the SANDBOX environment presents totally fictitious monetary values, and the Production environment performs valid financial transactions. The Sandbox environment was created for developers to perform their integrations, and when they are ready for production entry, they only need to update the environment variables with the Production parameters. | Environment | Host | |----------|----------------------------------------------| | Sandbox | https://api.sandbox.securities.qidtvm.com.br | | Production | https://api.securities.qidtvm.com.br | --- # Test endpoints URL: /en/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste ## GET Method ### Request ENDPOINT /authentication_test METHOD GET ### Response STATUS 200 Response Body ```json { "success": "Congrats!" } ``` ## POST Method ### Request ENDPOINT /authentication_test METHOD POST Request Body ```json { "name": "QI Tech" } ``` ### Response STATUS 200 Response Body ```json { "name": "QI Tech", "success": "Congrats!" } ``` --- # Authentication test URL: /en/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao ### 1. Introduction In this section we will explain how the request should work so that it can be accepted by our system. First, you must put the API Key provided by the QI CTVM team in the API-CLIENT-KEY header. Then you must create an AUTHORIZATION header signing with the integrating partner's Private Key; Below we will teach step by step using Python to exemplify the AUTHORIZATION creation process. ### 2. Import libraries In this Python example we are using 5 libraries to perform the authentication process. ```python from datetime import datetime import json from jose import jwt from hashlib import md5 import requests ``` ### 3. Insert the private key and integration key ```python title="Encryption data" api_key = "\" client_private_key = '''-----BEGIN EC PRIVATE KEY----- MIHbAgEBBEH7OuewosJfz4zKF+Gm0ogJxhb8G6LSMDVQQbFYz335mHCx9/Pr6Yk+ yYwsVozeXhlry3/vnUn1zCasU+4O+yseZ6AHBgUrgQQAI6GBiQOBhgAEAa46fN/2 8vI64shRhu9erMA6JLl3zHFX8gFHQrbb0g4IDfjXCKMCILiwdtL8QecstsgepTa7 yo1pTXOVNDbmLX2TAK38xb2Gv6OC+PA+5drF2wWajWbVLpR2R7mYEzr5HNIAJYHb 5C1jvM2ItK2R22HAbYfH25nsvGhkCGbrRNWQVF9g -----END EC PRIVATE KEY-----''' ``` ### 4. Define variables Define the method, endpoint and content variables specific to each request (in this example, we will use the "POST" method for the "/authentication_test" endpoint) ```python title="Request data" base_url = "https://api.securities.qidtvm.com.br" today_str = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S") method = "POST" endpoint = "/authentication_test" body = {"name": "QI Tech"} ``` ### 5. Build Base Signature Dictionary ```python title="Base dictionary" dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint} ``` #### 5.1. If necessary, add the content For requests that have a _body_, you must add the md5 of the bytes of that content. Since all requests in our system are through JSON, you can use the following: ```python title="Base dictionary" body_bytes = json.dumps(body).encode() md5_instance = md5() md5_instance.update(body_bytes) md5_body = md5_instance.hexdigest() dict_to_sign["payload_md5"] = md5_body ``` ### 6. Perform header encryption Perform encryption using JWT library (in this code example, we use jsonwebtoken as jwt in javascript) ```python jwt_headers = {"alg": "ES512", "typ": "JWT"} encoded_header_token = jwt.encode( claims=dict_to_sign, key=client_private_key, algorithm="ES512", headers=jwt_headers, ) ``` ### 7. Building the final header ```python headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token} ``` ```python title="Defining final url" url = f"{base_url}{endpoint}" ``` ### Making request ```python resp = requests.post(url=url, headers=headers, json=body) print(resp.json()) ``` --- # Keys Exchange URL: /en/documentation/escrituracao/introducao/troca_de_chaves ## 1. Signed Request All requests to our APIs must use the **HTTPS** protocol, using **TLS 1.2 or 1.3**, containing two Headers: 1. API-CLIENT-KEY: A key provided by our Integration team that identifies a specific integration; 2. AUTHORIZATION: A signature of the request that must be performed as explained in this manual; As standard, QI CTVM uses asymmetric keys, where there are two different keys, one for signing, called private key , and one for reading, called public key . With the private key, the integrating partner must perform the signature using the JWT standard. The integrating partner is responsible for generating the pair and providing the public key to the QI CTVM team so that we can validate their requests. :::caution **Attention** The private key is for exclusive use by the integrating partner, and must be stored securely. QI CTVM will never ask, under any circumstances, for you to share it with us. ::: ## 2. Generating the pair To generate a private key on a UNIX computer: ```bash $ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key ``` And from this private key generate your public key. ```bash $ openssl ec -in private.key -pubout -outform PEM -out public.key.pub ``` The generated public key (public.key.pub file) must be sent to the QI Tech team, and wait for the integration to be configured; --- # Asset Query URL: /en/documentation/escrituracao/operacoes-ativas/consulta-security This endpoint allows querying the details of an asset using its unique key. --- ## **Request** ENDPOINT /security/security/ SECURITY-KEY METHOD GET ### **Path Params** | Field | Type | Description | Characters | |--------------|--------|-----------------------------------------------|------------| | `SECURITY-KEY` | string | Unique security key (UUID v4). | 36 | --- ## **Response** STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "security_key": "42bd7161-5ec1-4f64-ac0c-861d93ffb4c2", "operation_key": "8eb2291e-2dbf-4af1-9d12-f29fac665ed2", "operation_type": "commercial_paper", "contract_number": "0000000027", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "financial_base_date": "2025-02-18", "current_unit_price": 1.0, "latest_accrual_date": "2025-02-18", "integralized_quantity": 100000, "issue_quantity": 100000, "security_status": "active", "is_defaulted": false, "financial": { "financial_base_date": "2025-02-18", "issue_quantity": 100000, "unit_price": 1.0, "issue_amount": 100000.0, "released_amount": 100000.0, "cet": 1.0, "annual_cet": 12.68, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0003271877, "annual_rate": 0.1268250301, "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "post_fixed_interest_rate": null, "financial_index": null, "fine_delay_rate": { "daily_rate": 0.00032719, "annual_rate": 0.12682503, "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 2000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 5000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_key": "959a1d8f-9f7f-4b5b-b963-828693caad58", "installment_status": "opened", "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.20395804, "principal_amortization_amount": 20395.80431829, "interest_amount": 201.13568171, "interest_amount_unit_price": 0.00201136, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 20395.80431829, "due_interest": 0.0, "due_date": "2025-07-18", "has_interest": true, "current_unit_price": 0.20395804, "latest_accrual_date": "2025-02-18", "paid_at": null, "paid_amount": 0.0, "settlement_process_list": [] }, { "installment_key": "b1f4fc31-7b73-45b8-bce7-4256394b974e", "installment_status": "paid", "installment_number": 1, "workdays": 18, "calendar_days": 28, "principal_amortization_unit_price": 0.19676756, "principal_amortization_amount": 19676.75638427, "interest_amount": 920.18361573, "interest_amount_unit_price": 0.00920184, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 100000.0, "due_interest": 0.0, "due_date": "2025-03-18", "has_interest": true, "current_unit_price": 0.19676756, "latest_accrual_date": "2025-02-18", "paid_at": "2025-02-18T18:39:47.174392", "paid_amount": 20596.94, "settlement_process_list": [ { "settlement_process_key": "a9030b64-5003-4f82-be4f-8296a4e0b140", "installment_key": "b1f4fc31-7b73-45b8-bce7-4256394b974e", "due_date": "2025-03-18", "reference_date": "2025-03-18", "current_integralized_quantity": 100000, "principal_amortization_amount": 19676.75638427, "interest_amount": 920.18361573, "post_fixed_interest_amount": 0.0, "fine_amount": 0.0, "total_amount": 20596.94, "expected_total_amount": 20596.94, "paid_amount": 20596.94, "settlement_process_status": "paid", "paid_at": "2025-02-18T18:39:47.185004", "settlement_process_payment_list": [ { "settlement_process_payment_key": "69615875-ed71-44f2-9a06-20f6ea4276f3", "investment": { "investment_key": "4b705afb-18cb-4fe5-922a-5eab71c2b558", "acquisition_date": "2025-02-18", "acquisition_unit_price": 1.0, "acquisition_amount": 100000.0, "acquisition_quantity": 100000.0, "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "investor_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "total_sell_amount": 0.0, "total_yield_amount": 920.18, "total_amortization_amount": 20596.94, "current_quantity": 100000, "investment_transaction_list": [ { "transaction_type": "integralization", "transaction_date": "2025-02-18", "transaction_unit_price": 1.0, "transaction_amount": 100000.0, "transaction_quantity": 100000.0, "amortization_amount": 0.0, "yield_amount": 0.0, "old_quantity": 0.0, "new_quantity": 100000.0, "investment_transaction_origin": "subscription", "investment_transaction_origin_key": "8549efc4-76e3-4e62-abd1-71162b383b4e" }, { "transaction_type": "maturity", "transaction_date": "2025-03-18", "transaction_unit_price": 0.2059694, "transaction_amount": 20596.94, "transaction_quantity": 0.0, "amortization_amount": 20596.94, "yield_amount": 920.18, "old_quantity": 100000.0, "new_quantity": 100000.0, "investment_transaction_origin": "settlement_process_payment", "investment_transaction_origin_key": "69615875-ed71-44f2-9a06-20f6ea4276f3" } ] }, "investment_quantity": 100000, "amount": 20596.94, "paid_at": "2025-02-18T18:39:47.159822", "settlement_process_payment_status": "paid", "settlement_process_payment_type": "manual", "settlement_process_payment_receipt_list": [ { "settlement_process_payment_receipt_key": "47fa434a-68cc-47d4-af8c-6a84061f38a6", "settlement_process_payment_receipt_status": "confirmed", "updated_at": "2025-02-18T18:39:47.153603" } ] } ] } ] }, { "installment_key": "dafc9683-a2b3-4bde-bf9a-ff4b2ea2599f", "installment_status": "opened", "installment_number": 2, "workdays": 23, "calendar_days": 35, "principal_amortization_unit_price": 0.19671978, "principal_amortization_amount": 19671.97807672, "interest_amount": 924.96192328, "interest_amount_unit_price": 0.00924962, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 80323.24361573, "due_interest": 0.0, "due_date": "2025-04-22", "has_interest": true, "current_unit_price": 0.19671978, "latest_accrual_date": "2025-02-18", "paid_at": null, "paid_amount": 0.0, "settlement_process_list": [] }, { "installment_key": "aab04935-763e-4431-b0e8-d3d341d5c563", "installment_status": "opened", "installment_number": 3, "workdays": 18, "calendar_days": 27, "principal_amortization_unit_price": 0.20058857, "principal_amortization_amount": 20058.85739386, "interest_amount": 538.08260614, "interest_amount_unit_price": 0.00538083, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 60651.26553901, "due_interest": 0.0, "due_date": "2025-05-19", "has_interest": true, "current_unit_price": 0.20058857, "latest_accrual_date": "2025-02-18", "paid_at": null, "paid_amount": 0.0, "settlement_process_list": [] }, { "installment_key": "6a76fd8f-631b-4b42-ac2e-daae8f87401d", "installment_status": "opened", "installment_number": 4, "workdays": 22, "calendar_days": 30, "principal_amortization_unit_price": 0.20196604, "principal_amortization_amount": 20196.60382686, "interest_amount": 400.33617314, "interest_amount_unit_price": 0.00400336, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 40592.40814515, "due_interest": 0.0, "due_date": "2025-06-18", "has_interest": true, "current_unit_price": 0.20196604, "latest_accrual_date": "2025-02-18", "paid_at": null, "paid_amount": 0.0, "settlement_process_list": [] } ] }, "investment_list": [ { "investment_key": "4b705afb-18cb-4fe5-922a-5eab71c2b558", "acquisition_date": "2025-02-18", "acquisition_unit_price": 1.0, "acquisition_amount": 100000.0, "acquisition_quantity": 100000.0, "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "investor_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "total_sell_amount": 0.0, "total_yield_amount": 920.18, "total_amortization_amount": 20596.94, "current_quantity": 100000, "investment_transaction_list": [ { "transaction_type": "integralization", "transaction_date": "2025-02-18", "transaction_unit_price": 1.0, "transaction_amount": 100000.0, "transaction_quantity": 100000.0, "amortization_amount": 0.0, "yield_amount": 0.0, "old_quantity": 0.0, "new_quantity": 100000.0, "investment_transaction_origin": "subscription", "investment_transaction_origin_key": "8549efc4-76e3-4e62-abd1-71162b383b4e" }, { "transaction_type": "maturity", "transaction_date": "2025-03-18", "transaction_unit_price": 0.2059694, "transaction_amount": 20596.94, "transaction_quantity": 0.0, "amortization_amount": 20596.94, "yield_amount": 920.18, "old_quantity": 100000.0, "new_quantity": 100000.0, "investment_transaction_origin": "settlement_process_payment", "investment_transaction_origin_key": "69615875-ed71-44f2-9a06-20f6ea4276f3" } ] } ] } ``` ## **Response Body Params** | Field | Type | Description | |------------------------------|----------|--------------------------------------------------------------| | `tenant_key` | string | Unique key of the tenant associated with the security. | | `security_key` | string | Unique security key. | | `operation_key` | string | Unique key of the operation associated with the security. | | `operation_type` | string | Operation type. Possible values: `commercial_paper`. | | `contract_number` | string | Contract number associated with the security. | | `issuer_key` | string | Unique key of the associated issuer. | | `issuer_name` | string | Name of the security issuer. | | `issuer_document_number` | string | Issuer document number (CPF/CNPJ). | | `issuer_bank_account` | object | **[issuer_bank_account object](#bank_account-object)**. | | `financial_base_date` | string | Financial base date of the security. | | `current_unit_price` | number | Current unit price of the security. | | `latest_accrual_date` | string | Date of the last accrual performed. | | `integralized_quantity` | integer | Total quantity of integralized shares. | | `issue_quantity` | integer | Total quantity of shares issued in the operation. | | `security_status` | string | Security status. Possible values: `active`, `inactive`. | | `is_defaulted` | boolean | Indicates if the security is in default (`true` or `false`). | | `financial` | object | **[financial object](#financial-object)**. | | `investment_list` | array | Investment list. **[investment object](#investment-object)**. | --- ### **bank_account object** | Field | Type | Description | |--------------------------------|----------|-------------------------------------------------| | `account_number` | string | Issuer's bank account number. | | `account_digit` | string | Issuer's bank account verification digit. | | `account_branch` | string | Issuer's bank branch. | | `financial_institution_ispb` | string | ISPB of the issuer's financial institution. | | `financial_institution_code_number` | string | Code of the issuer's financial institution. | --- ### **financial object** | Field | Type | Description | |--------------------------------|----------|-------------------------------------------------| | `financial_base_date` | string | Financial base date. | | `issue_quantity` | integer | Quantity of shares issued. | | `unit_price` | number | Unit price of shares. | | `issue_amount` | number | Total issue amount. | | `released_amount` | number | Total released amount. | | `cet` | number | Total effective cost (CET). | | `annual_cet` | number | Annualized total effective cost. | | `number_of_installments` | integer | Total number of installments. | | `prefixed_interest_rate` | object | **[prefixed_interest_rate object](#prefixed_interest_rate-object)**. | | `post_fixed_interest_rate` | object | **[post_fixed_interest_rate object](#post_fixed_interest_rate-object)**. | | `financial_index` | object | **[financial_index object](#financial_index-object)**. | | `fine_delay_rate` | object | **[fine_delay_rate object](#fine_delay_rate-object)**. | | `contract_fine_rate` | number | Contractual fine. | | `fees` | array | Fee list. **[fees object](#fees-object)**. | | `installment_list` | array | Installment list. **[installment object](#installment-object)**. | --- ### **investment object** | Field | Type | Description | |--------------------------------|----------|-------------------------------------------------| | `investment_key` | string | Unique investment key. | | `acquisition_date` | string | Investment acquisition date. | | `acquisition_unit_price` | number | Unit price at acquisition. | | `acquisition_amount` | number | Total acquisition amount. | | `acquisition_quantity` | integer | Quantity of shares acquired. | | `investor_key` | string | Unique investor key. | | `investor_name` | string | Investor name. | | `investor_document_number` | string | Investor document (CPF/CNPJ). | | `investor_bank_account` | object | **[investor_bank_account object](#bank_account-object)**. | | `total_sell_amount` | number | Total amount of sales made. | | `total_yield_amount` | number | Total yield amount. | | `total_amortization_amount` | number | Total amortization amount. | | `current_quantity` | integer | Current quantity of shares. | | `investment_transaction_list` | array | Transaction list. **[investment_transaction object](#investment_transaction-object)**. | --- ### **investment_transaction object** | Field | Type | Description | |--------------------------------|----------|-------------------------------------------------| | `transaction_type` | string | Transaction type (`integralization`, `maturity`). | | `transaction_date` | string | Transaction date. | | `transaction_unit_price` | number | Unit price in the transaction. | | `transaction_amount` | number | Total transaction amount. | | `transaction_quantity` | integer | Quantity of shares transacted. | | `amortization_amount` | number | Amortization amount in the transaction. | | `yield_amount` | number | Yield amount in the transaction. | | `old_quantity` | integer | Quantity of shares before the transaction. | | `new_quantity` | integer | Quantity of shares after the transaction. | | `investment_transaction_origin`| string | Transaction origin (`subscription`, `settlement_process_payment`). | | `investment_transaction_origin_key` | string | Origin key of the transaction. | ### **prefixed_interest_rate object** | Field | Type | Description | |---------------------|--------|--------------------------------------------------| | `daily_rate` | number | Daily prefixed interest rate. | | `annual_rate` | number | Annual prefixed interest rate. | | `monthly_rate` | number | Monthly prefixed interest rate. | | `interest_base` | string | Interest calculation base (`calendar_days_365`). | --- ### **post_fixed_interest_rate object** | Field | Type | Description | |---------------------|--------|---------------------------------------------------| | `daily_rate` | number | Daily post-fixed interest rate. | | `annual_rate` | number | Annual post-fixed interest rate. | | `monthly_rate` | number | Monthly post-fixed interest rate. | | `interest_base` | string | Interest calculation base (`calendar_days_365`). | --- ### **financial_index object** | Field | Type | Description | |------------------|--------|-------------------------------------------------| | `index_type` | string | Financial index type (`CDI`, `IPCA`, etc.). | | `index_value` | number | Financial index value. | --- ### **fine_delay_rate object** | Field | Type | Description | |---------------------|--------|------------------------------------------------| | `daily_rate` | number | Daily interest rate for payment delay. | | `annual_rate` | number | Annual interest rate for payment delay. | | `monthly_rate` | number | Monthly interest rate for payment delay. | | `interest_base` | string | Interest calculation base (`calendar_days_365`).| --- ### **fees object** | Field | Type | Description | |-------------|---------|--------------------------------------------| | `type` | string | Fee type (`internal`, `external`). | | `amount` | number | Percentage or absolute value of the fee. | | `fee_type` | string | Fee type. | | `fee_amount`| number | Monetary value of the applied fee. | | `amount_type` | string | Value type (`percentage`, `absolute`). | --- ### **installment object** | Field | Type | Description | |----------------------------------------|---------|-----------------------------------------------------------| | `installment_key` | string | Unique installment key. | | `installment_status` | string | Installment status | | `installment_number` | integer | Installment number in the schedule sequence. | | `workdays` | integer | Number of business days until maturity. | | `calendar_days` | integer | Number of calendar days until maturity. | | `principal_amortization_unit_price` | number | Unit value of principal amortization. | | `principal_amortization_amount` | number | Total principal amortization amount. | | `interest_amount` | number | Total interest amount of the installment. | | `interest_amount_unit_price` | number | Unit interest value of the installment. | | `post_fixed_interest_amount` | number | Total post-fixed interest amount of the installment. | | `post_fixed_interest_amount_unit_price` | number | Unit post-fixed interest value of the installment. | | `amount` | number | Total installment amount. | | `due_principal` | number | Principal amount due before the installment. | | `due_interest` | number | Interest amount due before the installment. | | `due_date` | string | Installment maturity date. | | `has_interest` | boolean | Indicates if the installment contains interest (`true` or `false`). | | `current_unit_price` | number | Updated unit price of the installment. | | `latest_accrual_date` | string | Date of the last accrual of the installment. | | `paid_at` | string | Installment payment date (if applicable). | | `paid_amount` | number | Total amount paid of the installment (if applicable). | | `settlement_process_list` | array | Settlement process list. **[settlement_process object](#settlement_process-object)** | ### **settlement_process object** | Field | Type | Description | |-----------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------| | `settlement_process_key` | string | Unique settlement process key. | | `installment_key` | string | Unique key of the installment associated with the settlement. | | `due_date` | string | Maturity date of the associated installment. | | `reference_date` | string | Settlement reference date. | | `current_integralized_quantity` | integer | Quantity of integralized shares at the time of settlement. | | `principal_amortization_amount` | number | Principal amortization amount. | | `interest_amount` | number | Total interest amount paid in the settlement. | | `post_fixed_interest_amount` | number | Post-fixed interest amount paid in the settlement. | | `fine_amount` | number | Fine amount applied (if any). | | `total_amount` | number | Total settlement amount. | | `expected_total_amount` | number | Expected total settlement amount. | | `paid_amount` | number | Total amount paid in the settlement. | | `settlement_process_status` | string | Settlement status (`waiting_payment`, `paid`, `canceled`). | | `paid_at` | string | Settlement payment date (if applicable). | | `settlement_process_payment_list` | array | Payment list associated with the settlement. **[settlement_process_payment object](#settlement_process_payment-object)** | ### **settlement_process_payment object** | Field | Type | Description | |---------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------| | `settlement_process_payment_key` | string | Unique settlement process payment key. | | `investment` | object | Investment information. **[investment object](#investment-object)**. | | `investment_quantity` | integer | Quantity of investment shares involved in the payment. | | `amount` | number | Payment amount made. | | `paid_at` | string | Payment date and time (ISO 8601 format). | | `settlement_process_payment_status` | string | Payment status (`waiting_payment`, `paid`, `canceled`). | | `settlement_process_payment_type` | string | Payment type (`manual`). | | `settlement_process_payment_receipt_list` | array | Payment receipt list. **[settlement_process_payment_receipt object](#settlement_process_payment_receipt-object)**. | ### **settlement_process_payment_receipt object** | Field | Type | Description | |---------------------------------------------|--------|-------------------------------------------------------------------| | `settlement_process_payment_receipt_key` | string | Unique settlement process payment receipt key. | | `settlement_process_payment_receipt_status` | string | Receipt status (`waiting_confirmation`, `confirmed`, `denied`). | | `amount` | number | Receipt amount. | | `updated_at` | string | Date and time of last receipt update (ISO 8601 format). | ### **security_status Enumerators** | Enum | Description | |-----------|------------------------------------------------------| | `issued` | The security was issued but is not yet active. | | `active` | The security is active and ongoing. | | `matured` | The security has reached maturity. | | `canceled` | The security was canceled. | ### **installment_status Enumerators** | Enum | Description | |-----------------------------|-----------------------------------------------------------------------| | `created` | The installment was created but is not yet available for payment. | | `opened` | The installment is open. | | `waiting_payment` | The installment is waiting for payment by the investor. | | `paid_partial` | The installment was partially paid. | | `paid` | The installment was fully paid. | | `paid_early` | The installment was paid early. | | `overdue` | The installment matured and was not paid. | | `paid_partial_overdue` | The installment was partially paid after maturity. | | `paid_overdue` | The installment was paid after maturity. | | `canceled` | The installment was canceled and does not need to be paid. | | `unmonitored` | The installment is not monitored for payments. | --- # Investor Position URL: /en/documentation/escrituracao/operacoes-ativas/posicao-investidor This endpoint allows querying an investor's consolidated position, returning information about their holdings in securities. --- ## Request ENDPOINT /security/investor/ INVESTOR-KEY METHOD GET ### Path Params | Field | Type | Description | Characters | |--------------|--------|-----------------------------------------------|------------| | `INVESTOR-KEY` | string | Unique investor key (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "total_current_amount": 100000.0, "investment_list": [ { "current_unit_price": 1.0, "current_quantity": 100000, "security_key": "42bd7161-5ec1-4f64-ac0c-861d93ffb4c2", "contract_number": "0000000027", "investment_key": "4b705afb-18cb-4fe5-922a-5eab71c2b558", "current_amount": 100000.0 } ] } ``` --- ### Response Body Params | Field | Type | Description | |----------------------------|----------|--------------------------------------------------------------------| | `investor_key` | string | Unique investor key. | | `investor_name` | string | Investor name. | | `investor_document_number` | string | Investor document number (CNPJ). | | `total_current_amount` | number | Investor's total consolidated amount. | | `investment_list` | array | List of investor's holdings in securities. **[Investment object](#investment-object)** | ### Investment object | Field | Type | Description | |-----------------------|----------|--------------------------------------------------| | `current_unit_price` | number | Current unit price of the security. | | `current_quantity` | integer | Investor's current quantity of the security. | | `security_key` | string | Unique key of the associated security. | | `contract_number` | string | Contract number of the security. | | `investment_key` | string | Unique key of the investor's investment. | | `current_amount` | number | Current value of the investor's holding. | --- # Webhooks URL: /en/documentation/escrituracao/webhooks-escrituracao ## Overview Those webhooks allow you to receive real-time notifications about status changes and important events related to the Commercial Paper issuance process. When an event occurs, QI Tech automatically sends an HTTP POST payload to the configured URL in your system. ## Webhook Configuration To receive webhooks, you need to configure an endpoint URL in your system. See the [webhook configuration documentation](./introducao/autenticacao_webhooks.md) for more details on how to register and manage your webhook URLs. ### Authentication and Security All webhooks sent by QI Tech include an HMAC-SHA256 signature in the `Signature` header. This signature must be validated in your system to ensure the authenticity and integrity of the received data. For more information about the validation process, see the [webhook authentication documentation](./introducao/autenticacao_webhooks.md). ## Available Events ### Issuer Management #### Issuer Registration Approved Sent when an issuer registration is approved by compliance. **Event Type:** `issuer_management.issuer_status_change` **Payload:** ```json { "event_type": "issuer_management.issuer_status_change", "event_datetime": "2025-07-30T15:32:00Z", "event_data": { "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "status": "approved" } } ``` #### Issuer Registration Rejected Sent when an issuer registration is rejected by compliance. **Event Type:** `issuer_management.issuer_status_change` **Payload:** ```json { "event_type": "issuer_management.issuer_status_change", "event_datetime": "2025-07-30T15:32:00Z", "event_data": { "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "status": "reproved" } } ``` ### Investor Management #### Investor Registration Approved Sent when an investor registration is approved by compliance. **Event Type:** `investor_management.investor_status_change` **Payload:** ```json { "event_type": "investor_management.investor_status_change", "event_datetime": "2025-07-30T15:32:00Z", "event_data": { "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "status": "approved" } } ``` #### Investor Registration Rejected Sent when an investor registration is rejected by compliance. **Event Type:** `investor_management.investor_status_change` **Payload:** ```json { "event_type": "investor_management.investor_status_change", "event_datetime": "2025-07-30T15:32:00Z", "event_data": { "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "status": "reproved" } } ``` ### Operation Management #### Operation Approved Sent when an operation is approved by compliance and is ready to be sent for signature. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "pending_signature_submission" } } ``` #### Operation Rejected Sent when an operation is rejected in the analysis (automatic pre-analysis or manual compliance review). The operation does not proceed to signature. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "compliance_reproved", "reproval_reason": { "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue." } } } ``` The `reproval_reason` field carries the rejection reasons as an object of key and description. In the automatic pre-analysis, each key is the eligibility rule that rejected the operation. The field may come as `null` when the rejection recorded no reason. #### Operation Sent for Signature Sent when an operation is sent for signature by the involved parties. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "waiting_signature" } } ``` #### Operation Signed and Issued Sent when an operation is signed by all parties. This event confirms that the Commercial Paper was successfully issued. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "issued", "signed_files_url": "https://storage.googleapis.com/commercial-paper-bucket/89c7f73a-c184-400c-bb2a-dd4424075a4f/signed_files?X-Goog-Algorithm=..." } } ``` The `signed_files_url` field carries the download link for a compressed file containing all signed contracts of the operation, available regardless of the signature method used. The link is valid for 7 days from the moment the webhook is sent. #### Operation Canceled Sent when an operation is canceled. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "canceled" } } ``` ### Subscription Management #### Subscription Sent for Signature Sent when a subscription is created and sent for investor signature. **Event Type:** `subscription.subscription_status_change` **Payload:** ```json { "event_type": "subscription.subscription_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "status": "waiting_signature" } } ``` #### Subscription Signed Sent when the subscription is signed by all parties and is waiting for payment. **Event Type:** `subscription.subscription_status_change` **Payload:** ```json { "event_type": "subscription.subscription_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "status": "waiting_payment" } } ``` #### Subscription Completed Sent when the subscription is completely finalized after payment confirmation. **Event Type:** `subscription.subscription_status_change` **Payload:** ```json { "event_type": "subscription.subscription_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "status": "finished" } } ``` #### Subscription Canceled Sent when the subscription is canceled because the integralization was rejected in the eligibility analysis. The integralization order and the signature envelope are canceled along with it. **Event Type:** `subscription.subscription_status_change` **Payload:** ```json { "event_type": "subscription.subscription_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "status": "canceled", "cancellation_reason": "ineligible", "ineligible_reasons": { "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue." } } } ``` The `cancellation_reason` field identifies the cancellation motive with a stable value. For `ineligible`, the `ineligible_reasons` field carries an object in which each key is the eligibility rule that rejected the integralization and each value is the corresponding description. ### Subscription Payment Management #### Payment Receipt Included Sent when a payment receipt is included and is waiting for confirmation. **Event Type:** `subscription_payment.subscription_payment_status_change` **Payload:** ```json { "event_type": "subscription_payment.subscription_payment_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1", "status": "waiting_confirmation" } } ``` #### Payment Receipt Approved Sent when the payment receipt is approved and confirmed. **Event Type:** `subscription_payment.subscription_payment_status_change` **Payload:** ```json { "event_type": "subscription_payment.subscription_payment_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1", "status": "confirmed" } } ``` ## Event Flow ### Commercial Paper Issuance Flow 1. **Issuer Registration** → `issuer_status_change` (approved/reproved) 2. **Investor Registration** → `investor_status_change` (approved/reproved) 3. **Operation Creation** → `operation_status_change` (pending_signature_submission) 4. **Sent for Signature** → `operation_status_change` (waiting_signature) 5. **Operation Issued** → `operation_status_change` (issued) ### Subscription Flow 1. **Subscription Creation** → `subscription_status_change` (waiting_signature) 2. **Signature Completed** → `subscription_status_change` (waiting_payment) 3. **Receipt Inclusion** → `subscription_payment_status_change` (waiting_confirmation) 4. **Payment Confirmed** → `subscription_payment_status_change` (confirmed) 5. **Subscription Completed** → `subscription_status_change` (finished) ## Best Practices 1. **Respond quickly**: Return an HTTP 2xx status as quickly as possible to confirm webhook receipt. 2. **Asynchronous processing**: For time-consuming operations, confirm receipt immediately and process the event asynchronously. 3. **Idempotency**: Implement idempotent logic, as webhooks may be resent in case of network failure. 4. **Signature validation**: Always validate the HMAC signature before processing the webhook. 5. **Logs and monitoring**: Maintain detailed logs of all received webhooks for auditing and debugging. ## References - [Webhook Configuration](./introducao/autenticacao_webhooks.md)