# QI Tech — Investment-as-a-Service › Escrituração Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 111 página(s). Índice: - Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/conceito) - Consultar Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao) - Criar Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao) - Simular Valor Presente da Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente) - Exemplos — Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/exemplos) - Amortização com Recompra (/documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao) - Regras de Negócio — Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio) - Catálogo de Erros (/documentation/escrituracao/catalogo-erros/catalogo-erros) - Configuração de Webhooks (/documentation/escrituracao/configuracao-webhooks) - Cadastro de Lastro (Ativo Subjacente) (/documentation/escrituracao/emissao-cr/cadastro-lastro) - Cadastro de Operação de CR (/documentation/escrituracao/emissao-cr/cadastro-operacao) - Envio de Documento (/documentation/escrituracao/emissao-cr/envio-documento) - Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-cr/envio-documento-externo) - Cadastro de Lastro (Ativo Subjacente) (/documentation/escrituracao/emissao-cra/cadastro-lastro) - Cadastro de Operação de CRA (/documentation/escrituracao/emissao-cra/cadastro-operacao) - Envio de Documento (/documentation/escrituracao/emissao-cra/envio-documento) - Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-cra/envio-documento-externo) - Cadastro de Lastro (Ativo Subjacente) (/documentation/escrituracao/emissao-cri/cadastro-lastro) - Cadastro de Operação de CRI (/documentation/escrituracao/emissao-cri/cadastro-operacao) - Envio de Documento (/documentation/escrituracao/emissao-cri/envio-documento) - Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-cri/envio-documento-externo) - Atualização da conta de desembolso da operação. (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso) - Atualização de dados financeiros na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros) - Atualização do método de assinatura na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura) - Envio de Garantia na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) - Remoção de Garantia na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia) - Envio de documentos (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento) - Cadastro e Remoção de Metadata na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao) - Envio e Remoção de Documentos de Representantes de Partes Relacionadas (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento) - Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) - Cadastro e Remoção de Partes Relacionadas de um documento específico (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento) - Cadastro e Remoção de Partes Relacionadas (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) - Cadastro de Operação de Nota Comercial (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) - Campos Extras (Extra Fields) (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields) - Cancelar Operação (/documentation/escrituracao/emissao-de-notas/cancelar-operacao) - Consulta do Link dos contratos assinados via QI SIGN da Operação (/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) - Consulta dos Links para assinatura via QI SIGN da Operação (/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) - Consulta de Operação por Chave (/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) - Consulta de Operações por Filtros (/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) - Consulta do Próximo Número de Emissão por Emissor (/documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao) - Enviar Atas de Aprovação Assinadas (/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) - Enviar Operação para Análise (/documentation/escrituracao/emissao-de-notas/envio-para-analise) - Enviar Operação para Assinatura (/documentation/escrituracao/emissao-de-notas/envio-para-assinatura) - Alterar Template do Termo de Adesão (/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta) - Alterar Template do Termo Constitutivo (/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) - Pré-visualizar Termo de Adesão (/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao) - Pré-visualizar Termo Constitutivo (/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) - Introdução à Emissão de Notas Comerciais (/documentation/escrituracao/emissao-de-notas/inicio) - Simulação de condições financeiras (/documentation/escrituracao/emissao-de-notas/simulacao) - Cadastro de Operação de Debênture (/documentation/escrituracao/emissao-debentures/cadastro-operacao) - Envio de Documento (/documentation/escrituracao/emissao-debentures/envio-documento) - Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-debentures/envio-documento-externo) - Envio de Garantia na Operação (/documentation/escrituracao/emissao-debentures/envio-garantia) - Alteração de Cadastro do Emissor (/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) - Cadastro de Grupos de Assinantes do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) - Remoção de Grupos de Assinantes do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) - Cadastro Básico do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) - Cadastro de Conta Bancária do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor) - Definição de Conta Bancária Principal do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal) - Remoção de Conta Bancária do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) - Envio de Documentos do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor) - Remoção de Documentos do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) - Envio de Documentos do Representante do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor) - Remoção de Documentos do Representante do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) - Cadastro de Informações de Contato do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor) - Definição de Contato Principal do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal) - Remoção de Informações de Contato do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) - Cadastro de Representantes do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor) - Remoção de Representante do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) - Consulta de Emissor (/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) - Consulta de Emissores por filtros (/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) - Envio para Análise do Emissor (/documentation/escrituracao/homologacao-emissor/envio-analise/) - Introdução (/documentation/escrituracao/homologacao-emissor/inicio) - Solicitação de Acesso aos Dados do Emissor (/documentation/escrituracao/homologacao-emissor/solicitacao-acesso) - Alteraçao de Cadastro do Investidor (/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/) - Cadastro de Grupos de Assinantes do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor) - Remoção de Grupos de Assinantes do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) - Cadastro Básico do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico) - Cadastro de Conta Bancária do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor) - Remoção de Conta Bancária do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) - Envio de Documentos do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor) - Remoção de Documentos do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) - Envio de Documentos do Representante do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor) - Remoção de Documentos do Representante do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) - Cadastro de Informações de Contato do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor) - Remoção de Informações de Contato do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao) - Cadastro de Representantes do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor) - Remoção de Representante do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) - Consulta de Investidor (/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) - Consulta de Investidores por filtros (/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) - Envio para Análise do Investidor (/documentation/escrituracao/homologacao-investidor/envio-analise/) - Introdução (/documentation/escrituracao/homologacao-investidor/inicio) - **Solicitação de Acesso aos Dados do Investidor** (/documentation/escrituracao/homologacao-investidor/solicitacao-acesso) - Consulta de Comprovante de Transação (/documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao) - Consulta de Conta de Liquidação (/documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao) - Consulta de Integralização por Chave (/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) - Consulta de Transações da Integralização (/documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao) - Introdução à Integralização de Cotas (/documentation/escrituracao/integralizacao-cotas/inicio) - Cadastro de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao) - Cancelar subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao) - Confirmação ou Rejeição do Pagamento de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento) - Consulta de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas) - Registro de Pagamento de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento) - Recebimento de Webhooks (/documentation/escrituracao/introducao/autenticacao_webhooks) - Escrituração de Notas Comerciais (/documentation/escrituracao/introducao/) - Endpoints de teste (/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) - Teste de autenticação (/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao) - Troca de Chaves (/documentation/escrituracao/introducao/troca_de_chaves) - Consulta de Ativo (/documentation/escrituracao/operacoes-ativas/consulta-security) - Consulta de Posição do Investidor (/documentation/escrituracao/operacoes-ativas/posicao-investidor) - Webhooks de Escrituração (/documentation/escrituracao/webhooks-escrituracao) --- # Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/conceito ## Visão geral Amortização extraordinária é o processo de reduzir o saldo devedor de uma emissão fora do cronograma ordinário — quando o emissor antecipa um pagamento, quita parcelas adiante do vencimento ou refinancia parte da dívida. O QI Tech recebe esse pedido via API, valida os valores e registra o evento para liquidação posterior, sem interferir nas amortizações ordinárias geradas em cada `due_date` (data de vencimento). Os cenários típicos envolvem quitação antecipada pelo emissor, pagamento antecipado de uma ou mais parcelas e operações de refinanciamento parcial. Em todos esses casos o integrador inicia o fluxo sob demanda, informando qual parcela (ou conjunto de parcelas) está sendo amortizada e qual o valor. Você recorre a esta API sempre que precisa alterar o saldo devedor fora da agenda ordinária de pagamentos. O resultado é sempre um evento rastreável, com `status` próprio e registro financeiro. A criação é fire-and-forget: a QI Tech orquestra liquidação, finalização e cancelamento internamente, sem que o integrador precise chamar endpoints adicionais. ## Amortização ordinária vs extraordinária A amortização ordinária é gerada automaticamente pela QI Tech: em cada `due_date` (data de vencimento), o processo de liquidação da parcela é criado internamente sem ação do integrador. Já a amortização extraordinária é sempre iniciada sob demanda, por chamada explícita à API. As duas coexistem — registrar uma amortização extraordinária não cancela nem substitui as ordinárias que ainda vão vencer; apenas adiciona um novo evento de liquidação sobre o ativo. ## Tipos de amortização Os cinco tipos suportados ficam no campo `amortization_type`: - `equal_amount` (valores proporcionais) — distribui proporcionalmente o valor informado entre as parcelas vencidas primeiro e depois entre as futuras. - `first_installments` (primeiras parcelas) — aplica o valor sequencialmente às N primeiras parcelas até esgotá-lo. - `present_amount` (valor presente) — o integrador escolhe as parcelas e pode informar `total_discount`; a ordem de distribuição é juros → multa → principal. - `matured_installments` (parcelas vencidas) — aplica o valor exclusivamente a parcelas já vencidas. - `early_amortization` (amortização antecipada) — antecipa o pagamento de uma parcela futura. Apenas `early_amortization` permite pagamento parcial — os outros quatro exigem cobertura integral do valor declarado dentro da tolerância. ## Conceitos-chave - **`event_conciliation`** — corresponde ao evento de conciliação de uma parcela específica. Responsável pelo ato de conciliação de pagamentos e/ou amortizações extraordinárias de parcelas de um valor mobiliário. - **`reference_date`** — data de referência fornecida pelo chamador em toda criação (deve corresponder à data de quitação). O QI Tech nunca usa `date.today()`: toda lógica relativa a datas (classificação de vencimento, projeção do Valor Presente, discriminação de parcelas vencidas vs a vencer) parte desse campo. - **Valor Presente** — calculado internamente e consumido durante a criação do evento. O integrador não precisa calcular Valor Presente no seu lado. - **Tolerância (`tolerance_amount`)** — diferença máxima aceita entre o valor de liquidação e o valor esperado da parcela. Default de R$ 0,01. Diferenças acima da tolerância fazem a liquidação ser rejeitada. - **Estado parcial derivado** — quando `paid_amount > 0` e `paid_amount < expected_amount`, a parcela é considerada parcialmente paga. Não há novo status: o estado é DERIVADO das colunas `paid_amount` e `expected_amount`. O status `pending_conciliation` cobre tanto o "ainda não pago" quanto o "parcialmente pago"; `paid` só aparece quando o acumulado cobre o esperado dentro da tolerância. ## Próximos passos Siga para o [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md) para ver o fluxo passo a passo. Para o cenário em que uma nova operação recompra amortizações extraordinárias em aberto, veja [Amortização com Recompra](./recompra-de-operacao.md). --- # Consultar Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao Este endpoint retorna uma amortização extraordinária específica pela sua chave (`extraordinary_event_conciliation_key`). Use-o para acompanhar o status da conciliação do evento — desde `pending_conciliation` (ainda não pago ou parcialmente pago) até o estado terminal (`paid` ou `canceled`) definido pela orquestração interna da QI Tech. A consulta é agnóstica de data e não dispara nenhuma transição de status: apenas reflete o estado atual do evento e de cada parcela vinculada. --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event/ EXTRAORDINARY-EVENT-CONCILIATION-KEY MÉTODO GET ### **Path Params** | Campo | Tipo | Obrigatório | Descrição | |----------------------------------------|---------------|-------------|---------------------------------------------------------------------------| | `extraordinary_event_conciliation_key` | string (UUID) | Sim | Chave única do evento extraordinário de amortização a consultar. | Exemplo de chamada: ``` 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** | Campo | Tipo | Descrição | |----------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key` | string (UUID) | Chave do evento extraordinário de amortização consultado. | | `security_key` | string (UUID) | Chave do ativo (`security`) ao qual o evento pertence. | | `investment_key` | string (UUID) | Chave do investimento alvo do evento. | | `amortization_type` | string | Tipo de amortização do evento — ecoa o valor usado na criação. | | `total_expected_amount` | number | Valor total esperado do evento (soma distribuída entre as parcelas) em BRL. | | `total_discount_amount` | number | Desconto total aplicado. Diferente de zero apenas para `present_amount`. | | `total_paid_amount` | number | Valor já conciliado para o evento (em BRL). `0` enquanto nenhum pagamento foi confirmado; `> 0` em pagamento parcial. | | `status` | string | Status atual do evento: `pending_conciliation`, `paid` ou `canceled`. | | `reference_date` | string (date) | Data de referência informada na criação. | | `due_date` | string (date) | Data alvo de liquidação informada na criação. | | `paid_at` | string (date) | Data em que o evento foi liquidado. `null` enquanto não estiver `paid`. | | `event_conciliation_list` | array | Lista de `event_conciliation` (evento de conciliação de cada parcela) do evento. **[Objeto event_conciliation_list](#objeto-event_conciliation_list)**. | ### **Objeto event_conciliation_list** | Campo | Tipo | Descrição | |-----------------------------|-----------------|-------------------------------------------------------------------------------------------| | `event_conciliation_key` | string (UUID) | Chave do evento de conciliação da parcela (`event_conciliation`). | | `installment_key` | string (UUID) | Chave da parcela afetada por este evento de conciliação. | | `event_conciliation_status` | string | Status atual do evento de conciliação da parcela (`pending_conciliation`, `paid`, `canceled`). | | `event_conciliation_type` | string | Tipo do `event_conciliation`. Sempre `extraordinary_event` para eventos criados por este fluxo. | :::info O `status` (e o `event_conciliation_status` de cada parcela) reflete o estado atual no momento da consulta. A transição para `paid` ou `canceled` é feita pela orquestração interna da QI Tech — o integrador não precisa acionar nenhum endpoint para isso. ::: --- ## **Erros** | Código | HTTP | Significado | |------------|------|--------------------------------------------------------------------------------------------------------| | EVC100011 | 404 | Nenhuma amortização extraordinária encontrada para a `extraordinary_event_conciliation_key` informada. | Consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) para resolução completa. --- ## **Veja também** - [Criar Amortização Extraordinária](./criar-amortizacao.md) - [Simular Valor Presente da Amortização Extraordinária](./simular-valor-presente.md) - [Conceito](../conceito.md) - [Roteiro de Integração](../../roteiro-integracao/roteiro-integracao-padrao.md) - [Regras de Negócio](../regras-de-negocio.md) - [Exemplos](../exemplos.md) --- # Criar Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao Este endpoint cria uma amortização extraordinária sobre um ou mais `installment` de uma emissão. O event-conciliation-service agrupa as parcelas em um evento extraordinário de amortização único, distribui o `amount` declarado conforme o `amortization_type` informado e obtém o Valor Presente via security-service — o integrador não calcula Valor Presente no seu lado. A `reference_date` é fornecida pelo chamador na requisição da amortização extraordinária e é a única referência temporal usada pelo serviço na classificação de vencidos e no desconto pro-rata. --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event MÉTODO POST ### **Request Body** Existem dois modos de criação. **Modo 1 — Targeted** exige `installment_list` (array de `installment_number`, inteiros ≥ 1) e é usado com os tipos `early_amortization`, `present_amount` e `matured_installments`. **Modo 2 — Acquittance** não recebe `installment_list` e é usado com os tipos `equal_amount` e `first_installments`. Os números enviados em `installment_list` são resolvidos pelo serviço contra `installment_number` da `security` correspondente. Exemplo — Modo 1 (`early_amortization`): ```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] } ``` Exemplo — Modo 2 (`equal_amount`): ```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" } ``` ### **Request Body Params** | Campo | Tipo | Obrigatório | Descrição | |---------------------------|-----------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | Sim | Chave única do ativo (`security`) sobre o qual a amortização será aplicada. | | `investment_key` | string (UUID) | Sim | Chave do investimento alvo. Usado pelo security-service como base proporcional no cálculo de Valor Presente. | | `amortization_type` | string | Sim | Estratégia de distribuição. Valores: `equal_amount`, `first_installments`, `present_amount`, `matured_installments`, `early_amortization`. | | `amount` | number | Sim | Valor total a ser amortizado (em BRL). Distribuído entre as parcelas selecionadas conforme o `amortization_type`. | | `reference_date` | string (date) | Sim | Data de referência em formato `YYYY-MM-DD`. **Fornecida pelo chamador** — o serviço a usa como "hoje" para classificar parcelas vencidas e aplicar o desconto pro-rata do Valor Presente. | | `due_date` | string (date) | Sim | Data alvo de liquidação (tipicamente igual à `reference_date`). | | `installment_list` | array de inteiros (≥ 1) | Condicional | Lista de `installment_number` (não UUIDs) das parcelas-alvo, com `minItems: 1`. Obrigatório para `present_amount`, `matured_installments` e `early_amortization`. Omita para `equal_amount` e `first_installments` para usar distribuição por acquittance (Modo 2). O serviço resolve cada número contra `installment_number` da `security`; números inexistentes retornam `EVC000007`. O legado `installment_key_list` foi removido — clientes que ainda enviarem o campo recebem `QIT000001` (400). | | `total_discount` | number | Não | Utilizado apenas com `present_amount` — distribui o desconto na ordem juros → multa → principal. | | `number_of_installments` | integer | Não | Utilizado apenas com `first_installments`, quando `installment_list` não é informado. | --- ## **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** | Campo | Tipo | Descrição | |---------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key`| string (UUID) | Chave do evento geral de amortização extraordinário criado. | | `security_key` | string (UUID) | Chave do ativo — ecoa o valor enviado. | | `amortization_type` | string | Tipo de amortização escolhido — ecoa o valor enviado. | | `total_expected_amount` | number | Soma distribuída entre os `event_conciliation` (eventos de conciliação da parcela) pelo engine do tipo escolhido. | | `total_discount_amount` | number | Desconto total aplicado. Diferente de zero apenas para `present_amount`. | | `status` | string | Status inicial do evento extraordinário. Sempre `pending_conciliation` ao criar. | | `reference_date` | string (date) | Data de referência enviada na requisição (deve corresponder a data de quitação). | | `due_date` | string (date) | Data alvo de liquidação enviada na requisição. | | `event_conciliation_list` | array | Lista de `event_conciliation` (evento de conciliação da parcela) gerado. **[Objeto event_conciliation_list](#objeto-event_conciliation_list)**. | ### **Objeto event_conciliation_list** | Campo | Tipo | Descrição | |--------------------------|-----------------|-------------------------------------------------------------------------------------------| | `event_conciliation_key` | string (UUID) | Chave do evento de conciliação da parcela (`event_conciliation`). | | `installment_key` | string (UUID) | Chave da parcela afetada por este evento de conciliação. | | `expected_amount` | number | Valor atribuído a este evento de conciliação da parcela pela engine de distribuição. | | `discount_amount` | number | Parcela do `total_discount` alocada a este evento de conciliação da parcela (quando aplicável). | | `due_date` | string (date) | Data de vencimento da parcela associada. | | `status` | string | Status inicial do evento de conciliação da parcela. Sempre `pending_conciliation` ao criar. | | `event_conciliation_type`| string | Tipo do `event_conciliation`. Sempre `extraordinary` para eventos de conciliação da parcela criados por este fluxo. | --- ## **Erros** | Código | HTTP | Significado | |------------|------|--------------------------------------------------------------------------------------------------------| | EVC100001 | 400 | `amortization_type` inválido. Use um dos cinco valores suportados. | | EVC100002 | 400 | `installment_list` é obrigatório (e não vazio) para `present_amount`, `matured_installments` ou `early_amortization`. | | EVC100003 | 400 | `number_of_installments` é obrigatório para `first_installments` quando `installment_list` não é enviado. | | EVC100004 | 400 | Alguma parcela informada não pertence à `security` alvo. | | EVC000007 | 404 | Algum inteiro em `installment_list` não corresponde a nenhum `installment_number` da `security` (`InstallmentNumberNotFound`). | | QIT000001 | 400 | Falha de schema — por exemplo, envio do legado `installment_key_list` (removido) ou item de `installment_list` que não é inteiro ≥ 1. | | EVC100005 | 400 | `amount` não cobre todas as parcelas selecionadas (não aplicável a `early_amortization`). | | EVC100006 | 400 | `total_discount` excede a soma do Valor Presente das parcelas selecionadas. | | EVC100007 | 400 | Para `matured_installments`, todas as parcelas selecionadas devem estar vencidas. | | EVC100008 | 400 | Já existe uma amortização extraordinária pendente para a parcela — cancele-a antes de criar outra. | | EVC100013 | 424 | Security API indisponível (Failed Dependency). Transitório — repita após o restabelecimento. | | EVC100015 | 400 | `early_amortization` requer exatamente 1 parcela em `installment_list`. | | EVC100016 | 400 | A parcela alvo de `early_amortization` não pode estar vencida. | | EVC100017 | 400 | Em `early_amortization`, `amount` deve ser menor ou igual ao Valor Presente da parcela. | Consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) para resolução completa. --- ## **Veja também** - [Simular Valor Presente da Amortização Extraordinária](./simular-valor-presente.md) - [Consultar Amortização Extraordinária](./consultar-amortizacao.md) - [Conceito](../conceito.md) - [Roteiro de Integração](../../roteiro-integracao/roteiro-integracao-padrao.md) - [Regras de Negócio](../regras-de-negocio.md) - [Exemplos](../exemplos.md) --- # Simular Valor Presente da Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente Este endpoint simula uma amortização extraordinária do tipo `present_amount` sem criar nenhum evento — é um cálculo puro, sem efeitos colaterais. A partir das parcelas informadas em `installment_list`, o serviço calcula e devolve o `amount` total (Valor Presente) do evento extraordinário que seria criado, além do Valor Presente de cada `event_conciliation` (tipo `extraordinary`) por parcela — o integrador não calcula Valor Presente no seu lado. O `amortization_type` não é enviado na requisição: por se tratar de uma simulação de Valor Presente, o tipo é sempre `present_amount`. O `amount` também não é enviado — ele é o resultado do cálculo. A `reference_date` é fornecida pelo chamador e é a única referência temporal usada pelo serviço na classificação de vencidos e no desconto pro-rata; na simulação, a `due_date` é assumida igual à `reference_date`. O response é o payload de criação pronto para uso: basta remover o campo `event_conciliation_list` — que é apenas informativo — e enviá-lo como body do [Criar Amortização Extraordinária](./criar-amortizacao.md) para efetivar a amortização simulada. --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event/present_value_simulation MÉTODO 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** | Campo | Tipo | Obrigatório | Descrição | |--------------------|-------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | Sim | Chave única do ativo (`security`) sobre o qual a amortização será simulada. | | `investment_key` | string (UUID) | Sim | Chave do investimento alvo. Usada como base proporcional no cálculo do Valor Presente. | | `reference_date` | string (date) | Sim | Data de referência em formato `YYYY-MM-DD`. **Fornecida pelo chamador** — o serviço a usa como "hoje" para classificar parcelas vencidas e aplicar o desconto pro-rata do Valor Presente. Na simulação, também é usada como `due_date`. | | `installment_list` | array de inteiros (≥ 1) | Sim | Lista de `installment_number` (não UUIDs) das parcelas-alvo, com `minItems: 1`. O serviço resolve cada número contra `installment_number` da `security`; números inexistentes retornam `EVC000007`. | Diferente da criação, `amortization_type`, `amount` e `due_date` **não são enviados**: o tipo é sempre `present_amount`, o `amount` é calculado pelo serviço e a `due_date` é assumida igual à `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** | Campo | Tipo | Descrição | |---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | Chave do ativo — ecoa o valor enviado. | | `investment_key` | string (UUID) | Chave do investimento alvo — ecoa o valor enviado. | | `amortization_type` | string | Sempre `present_amount` — preenchido pelo serviço para compor o payload de criação. | | `amount` | number | Valor Presente total calculado para o evento extraordinário (soma dos `amount` de `event_conciliation_list`). | | `reference_date` | string (date) | Data de referência — ecoa o valor enviado. | | `due_date` | string (date) | Data alvo de liquidação — igual à `reference_date` enviada. | | `installment_list` | array de inteiros | Parcelas-alvo — ecoa o valor enviado. | | `event_conciliation_list` | array | Valor Presente por parcela dos `event_conciliation` (tipo `extraordinary`) que seriam gerados. **Apenas para visualização — não entra no payload de criação.** **[Objeto event_conciliation_list](#objeto-event_conciliation_list)**. | :::info O campo `event_conciliation_list` é **apenas para visualização** da simulação de cada parcela — ele **não deve ser incluído** no payload de criação do evento extraordinário. Para efetivar a amortização simulada, envie o response **sem** `event_conciliation_list` como body do [Criar Amortização Extraordinária](./criar-amortizacao.md). ::: ### **Objeto event_conciliation_list** | Campo | Tipo | Descrição | |----------------------|---------|----------------------------------------------------------------------------------------------------------| | `installment_number` | integer | Número da parcela (`installment_number`) a que este evento de conciliação se refere. | | `amount` | number | Valor Presente calculado para o `event_conciliation` (tipo `extraordinary`) desta parcela. | --- ## **Erros** | Código | HTTP | Significado | |------------|------|----------------------------------------------------------------------------------------------------------------------------------------| | EVC100002 | 400 | `installment_list` é obrigatório e não pode ser vazio. | | EVC100004 | 400 | Alguma parcela informada não pertence à `security` alvo. | | EVC000007 | 404 | Algum inteiro em `installment_list` não corresponde a nenhum `installment_number` da `security` (`InstallmentNumberNotFound`). | | QIT000001 | 400 | Falha de schema — por exemplo, item de `installment_list` que não é inteiro ≥ 1. | | EVC100008 | 400 | Já existe uma amortização extraordinária pendente para a parcela — cancele-a antes de simular/criar outra. | | EVC100013 | 424 | Dependência temporariamente indisponível (Failed Dependency). Transitório — repita após o restabelecimento. | O `EVC100005` (`amount` insuficiente) não se aplica à simulação — o `amount` é calculado pelo serviço, não enviado. Consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) para resolução completa. --- ## **Veja também** - [Criar Amortização Extraordinária](./criar-amortizacao.md) - [Consultar Amortização Extraordinária](./consultar-amortizacao.md) - [Conceito](../conceito.md) - [Roteiro de Integração](../../roteiro-integracao/roteiro-integracao-padrao.md) - [Regras de Negócio](../regras-de-negocio.md) - [Exemplos](../exemplos.md) --- # Exemplos — Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/exemplos Esta página apresenta dois cenários de criação. A interação do integrador é **fire-and-forget**: realiza apenas a chamada de criação e a QI Tech orquestra liquidação, finalização e cancelamento internamente. Não há webhook tenant-facing dedicado às transições de status do `event_conciliation` extraordinário; a confirmação do efeito da operação é observada via os relatórios e webhooks já existentes para a operação subjacente (ex.: `commercial_paper.operation_status_change`). ## Cenário 1: quitação antecipada parcial de uma parcela (early_amortization) Cobre uma única parcela futura, com pagamento parcial permitido. `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] } ``` Resposta: `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" } ] } ``` A partir desse 201 a integração está concluída do lado do integrador. Quando o pagamento de R$ 1.500,00 atingir a conta de liquidação correspondente, a QI Tech (account-liquidation-api) liquida o evento de conciliação da parcela internamente e atualiza o `paid_amount`; quando a soma cobre `total_expected_amount - tolerance_amount`, o parent transita para `paid`. Se o pagamento não entrar, o evento é cancelado ou finalizado pela rotina diária de settlement do security-service. ## Cenário 2: quitação total com desconto (present_amount com 2 installments) Cria uma amortização com desconto consolidado cobrindo duas parcelas. `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 } ``` Resposta `201 Created` — dois eventos de conciliação da parcela são gerados com os valores distribuídos conforme o engine de `present_amount` (juros → multa → principal). Veja [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md) para o shape completo da resposta. A partir do 201 a interação do integrador é a mesma do Cenário 1: a QI Tech liquida cada evento de conciliação da parcela quando os pagamentos correspondentes entram, e finaliza ou cancela o evento internamente caso os valores não cheguem dentro da janela de settlement. ## Troubleshooting Códigos de erro mais comuns ao chamar a criação. Para a lista completa, consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). - **`EVC100015`** (400, EarlyAmortizationRequiresSingleInstallment) — `early_amortization` aceita exatamente uma parcela em `installment_list`. Reduza para 1. - **`EVC000007`** (404, InstallmentNumberNotFound) — algum `installment_number` enviado em `installment_list` não existe na `security` alvo. Confira os números retornados em `GET /security/security/{security_key}` antes de chamar. - **`QIT000001`** (400) — schema rejeitado. Causa típica: enviar o campo legado `installment_key_list` (removido) ou itens não inteiros em `installment_list`. - **`EVC100016`** (400, EarlyAmortizationInstallmentOverdue) — a parcela alvo de `early_amortization` está vencida e não é elegível. Selecione uma parcela futura. - **`EVC100017`** (400, EarlyAmortizationAmountExceedsPresentValue) — em `early_amortization`, o `amount` excedeu o Valor Presente da parcela. Confirme o PV antes de chamar. - **`EVC100013`** (424, SecurityApiUnavailable) — Security API temporariamente indisponível ao buscar o Valor Presente; é transitório. Aguarde e repita a chamada. - **`SEC000031`** (400, PostFixedSecurityNotSupported) — ativos pós-fixados (CDI, IPCA, IGPM) não são suportados na V1. Use ativos `pre_price` ou `pre_sac`. ## Veja também - [Conceito](./conceito.md) - [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md) - [Regras de Negócio](./regras-de-negocio.md) - [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md) - [Consultar Amortização Extraordinária](./endpoints/consultar-amortizacao.md) - [Recompra de Operação](./recompra-de-operacao.md) - [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Amortização com Recompra URL: /documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao ## Visão geral A **recompra** é o fluxo em que uma **nova operação** de nota comercial é emitida para "recomprar" uma ou mais amortizações extraordinárias em aberto de uma operação existente. O cenário típico: o devedor tem uma operação em aberto e, junto com o investidor, decide recomprá-la — por refinanciamento ou por qualquer outro motivo negociado. Em vez de quitar a dívida com recursos próprios, eles estruturam uma nova operação cujo desembolso liquida automaticamente as amortizações extraordinárias escolhidas. A nova operação é emitida pelo **mesmo devedor** (`issuer`) dos eventos que estão sendo recomprados. A recompra pode abranger: - **Uma única amortização extraordinária** — o caso mais comum, recomprando uma operação. - **Múltiplos ativos** — passando várias `extraordinary_event_conciliation_key`, inclusive de `security` diferentes, quando o devedor quer recomprar mais de um ativo na mesma nova operação. A recompra não é uma chamada de API separada: ela é declarada **no momento da criação da nova operação**, informando a lista de chaves dos eventos extraordinários a recomprar. ## Pré-requisito Cada amortização extraordinária a ser recomprada precisa **já existir** — criada previamente pelo fluxo de [amortização extraordinária](./endpoints/criar-amortizacao.md) — e estar em `pending_conciliation` no momento em que a nova operação é criada. São essas chaves (`extraordinary_event_conciliation_key`) que você referencia na recompra. :::warning Datas precisam casar com o desembolso A `reference_date` e a `due_date` informadas **na criação do evento extraordinário** precisam corresponder à **data de desembolso** da nova operação de recompra. Se essas datas não baterem com o desembolso, os eventos **não são desembolsados corretamente e são cancelados automaticamente** — a recompra não se efetiva. Planeje a `reference_date`/`due_date` do evento extraordinário já considerando quando a nova operação será desembolsada. ::: ## Como acionar A recompra é declarada no [Cadastro de Operação de Nota Comercial](../emissao-de-notas/cadastro-operacao/criar-operacao.md) (`POST /commercial_paper/operation`): basta enviar, junto com os campos normais de criação da operação, o campo `extraordinary_event_conciliation_key_list` com as chaves dos eventos extraordinários que deseja recomprar. ```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" ] } ``` O `extraordinary_event_conciliation_key_list` é o **único** acréscimo em relação ao cadastro de operação comum — todos os demais campos seguem o [contrato de criação de operação](../emissao-de-notas/cadastro-operacao/criar-operacao.md). Consulte aquela página para a referência completa de cada campo (`issuer_key`, `issuer_bank_account`, `investors`, `issue_date`, `financial`). ### Campo | Campo | Tipo | Obrigatório | Descrição | |--------------------------------------------|-------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key_list`| array de string (UUID) | Não | Lista de chaves das amortizações extraordinárias a recomprar. Itens únicos; uma chave por ativo recomprado. Pode abranger múltiplos `security`. Omita o campo em operações sem recompra. | ## Regra de valor O valor da nova operação precisa ser suficiente para cobrir o que está sendo recomprado. A regra aplicada na **criação da operação** é: > A soma do `expected_amount` de todos os eventos referenciados em `extraordinary_event_conciliation_key_list` deve ser **menor ou igual** ao `released_amount` da nova operação. Caso contrário, a criação é rejeitada com **`COM000050`** (400). :::info `released_amount` e fees `released_amount` é o **valor de emissão líquido de fees financiados**. Por isso, na prática, o valor de emissão da nova operação precisa cobrir no mínimo o valor dos eventos recomprados **+ fees** — só assim o `released_amount` resultante alcança a soma dos `expected_amount`. ::: ## Desembolso > **Orquestração interna.** A recompra propriamente dita acontece no desembolso da nova operação e é executada internamente pela QI Tech — o integrador **não chama** nenhum endpoint adicional nesta etapa. Ao desembolsar a nova operação: 1. As amortizações extraordinárias referenciadas são **liquidadas automaticamente**, transitando de `pending_conciliation` para `paid`. 2. O **restante** — `released_amount − Σ expected_amount`, quando positivo — é **repassado ao devedor**. Ou seja, parte do desembolso quita os eventos recomprados e o que sobra vai para o devedor, em uma única operação. ## Veja também - [Conceito](./conceito.md) - [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md) - [Consultar Amortização Extraordinária](./endpoints/consultar-amortizacao.md) - [Regras de Negócio](./regras-de-negocio.md) - [Exemplos](./exemplos.md) - [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md) - [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Regras de Negócio — Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio Esta página consolida as invariantes que governam a criação, a liquidação e o cancelamento de uma amortização extraordinária. 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. ## Data de referência (`reference_date`) A `reference_date` é **fornecida pelo chamador** na requisição de criação e é a única referência temporal usada pelo serviço — o sistema **nunca usa** `date.today()`. Toda lógica dependente de data (classificação de parcelas vencidas, desconto pro-rata do Valor Presente, seleção de parcelas elegíveis para `early_amortization`) parte desse campo. ## Tipos de amortização Os 5 tipos suportados e como cada um se combina com os modos de criação: | Tipo | Modo | `installment_list` | Regra de distribuição | Permite pagamento parcial | |------------------------|------------------------|------------------------|--------------------------------------------------------------------|---------------------------| | `equal_amount` | Modo 2 (Acquittance) | Não envia | Proporcional, vencidas primeiro e depois futuras | Não | | `first_installments` | Modo 2 (Acquittance) | Não envia | Sequencial nas N primeiras parcelas | Não | | `present_amount` | Modo 1 (Targeted) | Envia | Explícita por parcela; desconto ordena juros → multa → principal | Não | | `matured_installments` | Modo 1 (Targeted) | Envia | Apenas parcelas já vencidas | Não | | `early_amortization` | Modo 1 (Targeted) | Envia (exatamente 1) | Uma única parcela futura com suporte a pagamento parcial | **Sim** | **Modo 1 — Targeted** (com `installment_list` — array de `installment_number` inteiros): usa o endpoint PV per-installment — uma chamada por parcela selecionada. O serviço resolve cada `installment_number` para a parcela correspondente da `security`. **Modo 2 — Acquittance** (sem `installment_list`): usa o endpoint PV bulk — uma única chamada devolve o PV de todas as parcelas. ## Amortização antecipada (`early_amortization`) `early_amortization` é o único tipo que permite pagamento parcial. Todas as seguintes condições se aplicam: - Exatamente **1** parcela em `installment_list` — caso contrário, `EVC100015`. - A parcela-alvo **não pode estar vencida** — caso contrário, `EVC100016`. - O `amount` deve ser **≤ Valor Presente** da parcela — caso contrário, `EVC100017`. - **Pagamento parcial é permitido.** O estado `paid_amount > 0 AND paid_amount = total_expected_amount - tolerance_amount`. ## Fluxo de liquidação > **Orquestração interna.** A liquidação dos eventos extraordinários é executada pela QI Tech (account-liquidation-api) ao detectar o pagamento — o integrador **não chama** nenhum endpoint nesta etapa, nem recebe webhook dedicado às transições de status. As regras abaixo descrevem o comportamento interno para você entender o que ocorre após a criação. **Liquidação ordinária emite o total completo (regra 4).** A liquidação ordinária na `due_date` continua emitindo o `total_amount` completo da parcela via SQS; não há subtração do `paid_amount`. O evento reconcilia o estado parcial-pago no seu próprio engine de `early_amortization`. ## Cancelamento e finalização > **Orquestração interna.** Cancelamento e finalização são disparados por uma rotina diária e — o integrador **não chama** nenhum endpoint para cancelar ou finalizar uma amortização extraordinária, e não há webhook tenant-facing dedicado a essas transições. A descrição abaixo é informativa. ## Veja também - [Conceito](./conceito.md) - [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md) - [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md) - [Consultar Amortização Extraordinária](./endpoints/consultar-amortizacao.md) - [Recompra de Operação](./recompra-de-operacao.md) - [Exemplos](./exemplos.md) - [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Catálogo de Erros URL: /documentation/escrituracao/catalogo-erros/catalogo-erros ## Formatação dos erros Todas APIs da integração de escrituração retornam os erros de API formatados segundo a descrição a seguir: 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" } ``` --- ## Tabela de erros possíveis no processo de homologação do emissor | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (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. | ## Tabela de erros possíveis no processo de homologação do investidor | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (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. | ## Tabela de erros possíveis no processo de emissão da nota comercial | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (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. | ## Tabela de erros possíveis no processo de integralização de cotas | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (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. | ## Tabela de erros possíveis no processo de amortização extraordinária | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (pt-BR) | |------------|----------------|--------------------|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------| | 404 | EVC000007 | Not Found | An integer in `installment_list` does not match any `installment_number` in the target security (`InstallmentNumberNotFound`). | Um inteiro de `installment_list` não corresponde a nenhum `installment_number` da `security` alvo. | | 400 | EVC100001 | Bad Request | The provided `amortization_type` is not one of the supported values. | O valor de `amortization_type` fornecido não é um dos tipos suportados. | | 400 | EVC100002 | Bad Request | `installment_list` is required for `present_amount`, `matured_installments`, and `early_amortization`. | `installment_list` é obrigatório para `present_amount`, `matured_installments` e `early_amortization`. | | 400 | EVC100003 | Bad Request | `number_of_installments` is required for `first_installments` when `installment_list` is not provided. | `number_of_installments` é obrigatório para `first_installments` quando `installment_list` não é enviado. | | 400 | EVC100004 | Bad Request | One or more installments do not belong to the target security. | Uma ou mais parcelas informadas não pertencem ao ativo informado. | | 400 | EVC100005 | Bad Request | The amount does not cover the sum of the selected installments. | O valor informado não cobre a soma das parcelas selecionadas. | | 400 | EVC100006 | Bad Request | `total_discount` exceeds the present value of the selected installments. | `total_discount` excede o Valor Presente das parcelas selecionadas. | | 400 | EVC100007 | Bad Request | For `matured_installments`, all selected installments must be overdue. | Para `matured_installments`, todas as parcelas selecionadas devem estar vencidas. | | 400 | EVC100008 | Bad Request | An extraordinary event already exists for the installment. | Já existe uma amortização extraordinária pendente para a parcela. | | 424 | EVC100013 | Failed Dependency | The Security API is temporarily unavailable. | A Security API está temporariamente indisponível. | | 400 | EVC100015 | Bad Request | `early_amortization` requires exactly one installment in `installment_list`. | `early_amortization` requer exatamente uma parcela em `installment_list`. | | 400 | EVC100016 | Bad Request | The target installment is not eligible for `early_amortization` (already overdue). | A parcela alvo de `early_amortization` está vencida e não é elegível. | | 400 | EVC100017 | Bad Request | The `early_amortization` amount exceeds the installment's present value. | O valor de `early_amortization` excede o Valor Presente da parcela. | | 404 | EVC100011 | Not Found | No extraordinary event conciliation was found for the provided `extraordinary_event_conciliation_key`. | Nenhuma amortização extraordinária encontrada para a `extraordinary_event_conciliation_key` informada. | | 400 | COM000050 | Bad Request | On a repurchase operation, the sum of the referenced extraordinary events' `expected_amount` cannot exceed the operation's `released_amount`. | Em uma operação de recompra, a soma do `expected_amount` dos eventos extraordinários referenciados não pode exceder o `released_amount` da operação. | | 400 | SEC000001 | Bad Request | The referenced security was not found. | O ativo (`security`) informado não foi encontrado. | | 404 | SEC000027 | Not Found | The referenced investment was not found. | O investimento (`investment`) informado não foi encontrado. | | 404 | SEC000029 | Not Found | The referenced installment was not found. | A parcela (`installment`) informada não foi encontrada. | | 400 | SEC000030 | Bad Request | The present value request is invalid (missing `investment_key` or malformed `reference_date`). | A requisição de Valor Presente é inválida (falta `investment_key` ou `reference_date` mal formatada). | | 400 | SEC000031 | Bad Request | Post-fixed securities (CDI, IPCA, IGPM) are not supported in V1. | Ativos pós-fixados (CDI, IPCA, IGPM) não são suportados na V1. | --- # Configuração de Webhooks URL: /documentation/escrituracao/configuracao-webhooks A API de Configuração de Webhooks permite gerenciar endpoints de webhook para receber notificações em tempo real sobre eventos da escrituração. Cada tenant pode ter múltiplas configurações de webhook, permitindo que os eventos sejam enviados para diferentes destinos. --- ## Modelo de Dados ### Configuração de Webhook ```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" } ``` --- ## Criar Configuração de Webhook (POST) ### Request ENDPOINT /outgoing_webhook/webhook_configuration MÉTODO 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 | Campo | Tipo | Descrição | | ---------------------- | ------ | --------------------------------------------------------- | | `tenant_key`* | string | UUID do tenant (UUID v4). | | `url`* | string | URL de destino para receber os webhooks. | | `hmac_signature_key`* | string | Chave secreta para assinatura HMAC dos webhooks. | | `headers` | object | Headers personalizados para incluir nas requisições. | --- ### 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 | Campo | Tipo | Descrição | | ---------------------- | ------ | --------------------------------------------------------- | | `configuration_key` | string | Chave única da configuração de webhook (UUID v4). | | `tenant_key` | string | UUID do tenant. | | `url` | string | URL de destino configurada. | | `headers` | object | Headers personalizados configurados. | | `hmac_signature_key` | string | Chave secreta para assinatura HMAC. | --- ## Listar Configurações de Webhook (GET) ### Request ENDPOINT /outgoing_webhook/webhook_configuration MÉTODO GET ### Query Params | Campo | Tipo | Descrição | | ------------ | ------- | ---------------------------------------------- | | `tenant_key`* | string | UUID do tenant para filtrar as configurações. | | `page` | integer | Número da página (padrão: 1). | | `page_size` | integer | Itens por página (padrão: 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 | Campo | Tipo | Descrição | | ---------------------- | ------- | --------------------------------------------------------- | | `data` | array | Lista de configurações de webhook. | | `pagination` | object | **[Objeto pagination](#objeto-pagination)**. | --- ## Obter Configuração de Webhook por Chave (GET) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | Chave única da configuração de webhook (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 | Campo | Tipo | Descrição | | ---------------------- | ------- | --------------------------------------------------------- | | `configuration_key` | string | Chave única da configuração de webhook (UUID v4). | | `tenant_key` | string | UUID do tenant. | | `url` | string | URL de destino configurada. | | `headers` | object | Headers personalizados configurados. | | `hmac_signature_key` | string | Chave secreta para assinatura HMAC. | --- ## Atualizar Configuração de Webhook (PUT) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY MÉTODO PUT ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | Chave única da configuração de webhook (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 | Campo | Tipo | Descrição | | --------------------- | ------ | --------------------------------------------------------- | | `url` | string | Nova URL de destino para receber os webhooks. | | `headers` | object | Novos headers personalizados para incluir nas requisições. | | `hmac_signature_key` | string | Nova chave secreta para assinatura HMAC dos 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 | Campo | Tipo | Descrição | | ---------------------- | ------- | --------------------------------------------------------- | | `configuration_key` | string | Chave única da configuração de webhook (UUID v4). | | `tenant_key` | string | UUID do tenant. | | `url` | string | URL de destino configurada. | | `headers` | object | Headers personalizados configurados. | | `hmac_signature_key` | string | Chave secreta para assinatura HMAC. | --- ## Deletar Configuração de Webhook (DELETE) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | Chave única da configuração de webhook (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json {} ``` --- # Cadastro de Lastro (Ativo Subjacente) URL: /documentation/escrituracao/emissao-cr/cadastro-lastro Este endpoint cadastra o **lastro** (ativo subjacente) de uma operação de CR. O lastro representa os direitos creditórios que dão suporte à securitização. O documento do ativo é enviado em base64 e seus dados estruturados acompanham a requisição. :::info O lastro é enviado **após a criação da operação**, em uma requisição separada. Podem ser cadastrados múltiplos lastros para a mesma operação. ::: --- ## **Request** ENDPOINT /cr/operation/ OPERATION-KEY /underlying_asset MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|------------------------------------|------------| | `OPERATION-KEY` * | string | Chave única da operação (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 | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------------|--------|------------------------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | Tipo do lastro. | **[Enumeradores underlying_asset_type](#enumeradores-underlying_asset_type)** | | `underlying_asset_base64` * | string | Documento do lastro em base64. | - | | `underlying_asset_data` * | object | Dados do lastro (estrutura livre). | - | ### Enumeradores underlying_asset_type | Enum | Descrição | |------------|-----------| | `contract` | Contrato. | ## **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 | Campo | Tipo | Descrição | |---------------------------|--------|------------------------------------| | `underlying_asset_key` * | string | Chave única do lastro cadastrado. | | `underlying_asset_type` * | string | Tipo do lastro. | | `underlying_asset_data` * | object | Dados do lastro. | --- --- # Cadastro de Operação de CR URL: /documentation/escrituracao/emissao-cr/cadastro-operacao Este endpoint cria uma operação de CR completa em uma única requisição. :::info O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados. ::: --- ## **Request** ENDPOINT /cr/create_operation MÉTODO POST O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo. Payload com os campos obrigatórios ```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 } ] } } ``` Payload completo (com partes relacionadas) ```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** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------- | ---------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Chave única do tenant. | - | | `issuer_key` * | string | Chave única do emissor (previamente cadastrado). | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `investors` * | array | Lista de investidores envolvidos. | **Objeto investors** | | `financial` * | object | Dados financeiros já calculados da operação. | **Objeto financial** | | `contract_number` | string | Número do contrato. | - | | `related_party_list` | array | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** | ### Objeto investors | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Chave única do investidor (previamente cadastrado). | | `bank_account` * | object | Conta bancária do investidor (**Objeto bank_account**). | | `subscription_percentage` | number | Percentual de subscrição. | | `subscription_quantity` | number | Quantidade subscrita. | ### Objeto bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`). | ### Objeto financial | Campo | Tipo | Descrição | | --------------------------- | ------- | -------------------------------------------------- | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `interest_type` * | string | Tipo de juros. | | `issue_amount` | number | Valor total emitido. | | `issue_quantity` | integer | Quantidade de unidades emitidas. | | `unit_price` | number | Preço unitário da emissão. | | `released_amount` | number | Valor líquido liberado. | | `cet` / `annual_cet` | number | Custo Efetivo Total (mensal e anual), em percentual. | | `number_of_installments` * | integer | Número de parcelas. | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | | `fine_delay_rate` | object | Taxa de multa por atraso. | | `contract_fine_rate` | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | | `installments` | array | Lista de parcelas já calculadas. | ### Objeto related_party Cada item de `related_party_list` representa uma parte envolvida na operação. | Campo | Tipo | Descrição | | ----------------- | ------- | ------------------------------------------------------------- | | `person_type` * | string | Tipo de pessoa (`natural` para PF, `legal` para PJ). | | `name` * | string | Nome da parte relacionada. | | `document_number` * | string | CPF (PF) ou CNPJ (PJ). | | `role_type` * | string | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** | | `street` * | string | Logradouro. | | `number` * | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `postal_code` * | string | CEP (formato "00000-000"). | | `city` * | string | Cidade. | | `state` * | string | UF (2 letras). | | `complement` | string | Complemento do endereço. | | `is_pep` | boolean | (PF) Indica se é Pessoa Politicamente Exposta. | | `marital_status` | string | (PF) Estado civil. | | `property_system` | string | (PF) Regime de bens. | | `birthdate` | string | (PF) Data de nascimento. | | `mother_name` | string | (PF) Nome da mãe. | | `occupation` | string | (PF) Ocupação. | | `trading_name` | string | (PJ) Nome fantasia. | | `cnae_code` | string | (PJ) Código CNAE (formato "00.00-0-00"). | | `company_type` | string | (PJ) Tipo de empresa. | | `foundation_date` | string | (PJ) Data de fundação. | :::warning Atenção Os campos obrigatórios variam conforme o `person_type`: - **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório. - **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios. ::: ### Enumeradores role_type | Enum | Descrição | |------|-----------| | `issuer` | Emissor. | | `investor` | Investidor. | | `cosigner` | Coobrigado. | | `fiduciary_debtor` | Devedor fiduciante. | | `solidary_debtor` | Devedor solidário. | | `guarantor` | Avalista. | | `bonafide_depositary` | Fiel depositário. | | `intervening_guarantor` | Interveniente garantidor. | | `intervening_consentor` | Interveniente anuente. | | `intervening_discharger` | Interveniente quitante. | | `assignor` | Cedente. | | `endorser` | Endossante. | | `consulting` | Consultoria. | | `fund_administrator` | Administrador do fundo. | | `fund_representative` | Representante do fundo. | | `company_representative` | Representante da empresa. | | `attestant` | Anuente / testemunha. | | `debtor` | Devedor. | | `bestowal` | Outorgante. | | `manager` | Gestor. | :::tip Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Cadastro de lastro** desta seção. ::: ### Enumeradores signature_method | Enum | Descrição | |------|-----------| | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | ## **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": { ... } } ``` A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado. --- # Envio de Documento URL: /documentation/escrituracao/emissao-cr/envio-documento Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints da operação sempre que for exigida a chave de um documento previamente enviado. --- ## **Request** ENDPOINT /cr/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |-------------------|--------|----------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | | `document_name` | string | Nome do documento. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|--------|-------------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento enviado (UUID v4). | 36 | --- --- # Enviar Documento Externo da Operação URL: /documentation/escrituracao/emissao-cr/envio-documento-externo Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador. :::warning Aviso Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal. ::: --- ## Enviar Documento Assinado (POST) ### Request ENDPOINT /cr/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|--------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|-----------------------------|-------------------------------------------------------------| | `contract_type` * | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Documento assinado em base64. | - | ### Enumeradores contract_type | Enum | Descrição | |---------------------|--------------------------------------------| | `securitization_term` | Termo de securitização do CR. | | `adhesion_term` | Termo de adesão do CR. | | `sa_minute` | Ata de aprovação de emissão do CR para empresa **SA**. | | `ltda_minute` | Ata de aprovação de emissão do CR para empresa **LTDA**. | | `cop_minute` | Ata de aprovação de emissão do CR para **Cooperativa**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Cadastro de Lastro (Ativo Subjacente) URL: /documentation/escrituracao/emissao-cra/cadastro-lastro Este endpoint cadastra o **lastro** (ativo subjacente) de uma operação de CRA. O lastro representa os direitos creditórios que dão suporte à securitização. O documento do ativo é enviado em base64 e seus dados estruturados acompanham a requisição. :::info O lastro é enviado **após a criação da operação**, em uma requisição separada. Podem ser cadastrados múltiplos lastros para a mesma operação. ::: --- ## **Request** ENDPOINT /cra/operation/ OPERATION-KEY /underlying_asset MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|------------------------------------|------------| | `OPERATION-KEY` * | string | Chave única da operação (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 | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------------|--------|------------------------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | Tipo do lastro. | **[Enumeradores underlying_asset_type](#enumeradores-underlying_asset_type)** | | `underlying_asset_base64` * | string | Documento do lastro em base64. | - | | `underlying_asset_data` * | object | Dados do lastro (estrutura livre). | - | ### Enumeradores underlying_asset_type | Enum | Descrição | |------------|-----------| | `contract` | Contrato. | ## **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 | Campo | Tipo | Descrição | |---------------------------|--------|------------------------------------| | `underlying_asset_key` * | string | Chave única do lastro cadastrado. | | `underlying_asset_type` * | string | Tipo do lastro. | | `underlying_asset_data` * | object | Dados do lastro. | --- --- # Cadastro de Operação de CRA URL: /documentation/escrituracao/emissao-cra/cadastro-operacao Este endpoint cria uma operação de CRA completa em uma única requisição. :::info O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados. ::: --- ## **Request** ENDPOINT /cra/create_operation MÉTODO POST O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo. Payload com os campos obrigatórios ```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 } ] } } ``` Payload completo (com partes relacionadas) ```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** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------- | ---------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Chave única do tenant. | - | | `issuer_key` * | string | Chave única do emissor (previamente cadastrado). | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `investors` * | array | Lista de investidores envolvidos. | **Objeto investors** | | `financial` * | object | Dados financeiros já calculados da operação. | **Objeto financial** | | `contract_number` | string | Número do contrato. | - | | `related_party_list` | array | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** | ### Objeto investors | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Chave única do investidor (previamente cadastrado). | | `bank_account` * | object | Conta bancária do investidor (**Objeto bank_account**). | | `subscription_percentage` | number | Percentual de subscrição. | | `subscription_quantity` | number | Quantidade subscrita. | ### Objeto bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`). | ### Objeto financial | Campo | Tipo | Descrição | | --------------------------- | ------- | -------------------------------------------------- | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `interest_type` * | string | Tipo de juros. | | `issue_amount` | number | Valor total emitido. | | `issue_quantity` | integer | Quantidade de unidades emitidas. | | `unit_price` | number | Preço unitário da emissão. | | `released_amount` | number | Valor líquido liberado. | | `cet` / `annual_cet` | number | Custo Efetivo Total (mensal e anual), em percentual. | | `number_of_installments` * | integer | Número de parcelas. | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | | `fine_delay_rate` | object | Taxa de multa por atraso. | | `contract_fine_rate` | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | | `installments` | array | Lista de parcelas já calculadas. | ### Objeto related_party Cada item de `related_party_list` representa uma parte envolvida na operação. | Campo | Tipo | Descrição | | ----------------- | ------- | ------------------------------------------------------------- | | `person_type` * | string | Tipo de pessoa (`natural` para PF, `legal` para PJ). | | `name` * | string | Nome da parte relacionada. | | `document_number` * | string | CPF (PF) ou CNPJ (PJ). | | `role_type` * | string | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** | | `street` * | string | Logradouro. | | `number` * | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `postal_code` * | string | CEP (formato "00000-000"). | | `city` * | string | Cidade. | | `state` * | string | UF (2 letras). | | `complement` | string | Complemento do endereço. | | `is_pep` | boolean | (PF) Indica se é Pessoa Politicamente Exposta. | | `marital_status` | string | (PF) Estado civil. | | `property_system` | string | (PF) Regime de bens. | | `birthdate` | string | (PF) Data de nascimento. | | `mother_name` | string | (PF) Nome da mãe. | | `occupation` | string | (PF) Ocupação. | | `trading_name` | string | (PJ) Nome fantasia. | | `cnae_code` | string | (PJ) Código CNAE (formato "00.00-0-00"). | | `company_type` | string | (PJ) Tipo de empresa. | | `foundation_date` | string | (PJ) Data de fundação. | :::warning Atenção Os campos obrigatórios variam conforme o `person_type`: - **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório. - **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios. ::: ### Enumeradores role_type | Enum | Descrição | |------|-----------| | `issuer` | Emissor. | | `investor` | Investidor. | | `cosigner` | Coobrigado. | | `fiduciary_debtor` | Devedor fiduciante. | | `solidary_debtor` | Devedor solidário. | | `guarantor` | Avalista. | | `bonafide_depositary` | Fiel depositário. | | `intervening_guarantor` | Interveniente garantidor. | | `intervening_consentor` | Interveniente anuente. | | `intervening_discharger` | Interveniente quitante. | | `assignor` | Cedente. | | `endorser` | Endossante. | | `consulting` | Consultoria. | | `fund_administrator` | Administrador do fundo. | | `fund_representative` | Representante do fundo. | | `company_representative` | Representante da empresa. | | `attestant` | Anuente / testemunha. | | `debtor` | Devedor. | | `bestowal` | Outorgante. | | `manager` | Gestor. | :::tip Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Cadastro de lastro** desta seção. ::: ### Enumeradores signature_method | Enum | Descrição | |------|-----------| | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | ## **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": { ... } } ``` A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado. --- # Envio de Documento URL: /documentation/escrituracao/emissao-cra/envio-documento Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints da operação sempre que for exigida a chave de um documento previamente enviado. --- ## **Request** ENDPOINT /cra/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |-------------------|--------|----------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | | `document_name` | string | Nome do documento. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|--------|-------------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento enviado (UUID v4). | 36 | --- --- # Enviar Documento Externo da Operação URL: /documentation/escrituracao/emissao-cra/envio-documento-externo Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador. :::warning Aviso Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal. ::: --- ## Enviar Documento Assinado (POST) ### Request ENDPOINT /cra/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|--------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|-----------------------------|-------------------------------------------------------------| | `contract_type` * | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Documento assinado em base64. | - | ### Enumeradores contract_type | Enum | Descrição | |---------------------|--------------------------------------------| | `securitization_term` | Termo de securitização do CRA. | | `adhesion_term` | Termo de adesão do CRA. | | `sa_minute` | Ata de aprovação de emissão do CRA para empresa **SA**. | | `ltda_minute` | Ata de aprovação de emissão do CRA para empresa **LTDA**. | | `cop_minute` | Ata de aprovação de emissão do CRA para **Cooperativa**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Cadastro de Lastro (Ativo Subjacente) URL: /documentation/escrituracao/emissao-cri/cadastro-lastro Este endpoint cadastra o **lastro** (ativo subjacente) de uma operação de CRI. O lastro representa os direitos creditórios que dão suporte à securitização. O documento do ativo é enviado em base64 e seus dados estruturados acompanham a requisição. :::info O lastro é enviado **após a criação da operação**, em uma requisição separada. Podem ser cadastrados múltiplos lastros para a mesma operação. ::: --- ## **Request** ENDPOINT /cri/operation/ OPERATION-KEY /underlying_asset MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|------------------------------------|------------| | `OPERATION-KEY` * | string | Chave única da operação (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 | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------------|--------|------------------------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | Tipo do lastro. | **[Enumeradores underlying_asset_type](#enumeradores-underlying_asset_type)** | | `underlying_asset_base64` * | string | Documento do lastro em base64. | - | | `underlying_asset_data` * | object | Dados do lastro (estrutura livre). | - | ### Enumeradores underlying_asset_type | Enum | Descrição | |------------|-----------| | `contract` | Contrato. | ## **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 | Campo | Tipo | Descrição | |---------------------------|--------|------------------------------------| | `underlying_asset_key` * | string | Chave única do lastro cadastrado. | | `underlying_asset_type` * | string | Tipo do lastro. | | `underlying_asset_data` * | object | Dados do lastro. | --- --- # Cadastro de Operação de CRI URL: /documentation/escrituracao/emissao-cri/cadastro-operacao Este endpoint cria uma operação de CRI completa em uma única requisição. :::info O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados. ::: --- ## **Request** ENDPOINT /cri/create_operation MÉTODO POST O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo. Payload com os campos obrigatórios ```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 } ] } } ``` Payload completo (com partes relacionadas) ```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** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------- | ---------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Chave única do tenant. | - | | `issuer_key` * | string | Chave única do emissor (previamente cadastrado). | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `investors` * | array | Lista de investidores envolvidos. | **Objeto investors** | | `financial` * | object | Dados financeiros já calculados da operação. | **Objeto financial** | | `contract_number` | string | Número do contrato. | - | | `related_party_list` | array | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** | ### Objeto investors | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Chave única do investidor (previamente cadastrado). | | `bank_account` * | object | Conta bancária do investidor (**Objeto bank_account**). | | `subscription_percentage` | number | Percentual de subscrição. | | `subscription_quantity` | number | Quantidade subscrita. | ### Objeto bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`). | ### Objeto financial | Campo | Tipo | Descrição | | --------------------------- | ------- | -------------------------------------------------- | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `interest_type` * | string | Tipo de juros. | | `issue_amount` | number | Valor total emitido. | | `issue_quantity` | integer | Quantidade de unidades emitidas. | | `unit_price` | number | Preço unitário da emissão. | | `released_amount` | number | Valor líquido liberado. | | `cet` / `annual_cet` | number | Custo Efetivo Total (mensal e anual), em percentual. | | `number_of_installments` * | integer | Número de parcelas. | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | | `fine_delay_rate` | object | Taxa de multa por atraso. | | `contract_fine_rate` | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | | `installments` | array | Lista de parcelas já calculadas. | ### Objeto related_party Cada item de `related_party_list` representa uma parte envolvida na operação. | Campo | Tipo | Descrição | | ----------------- | ------- | ------------------------------------------------------------- | | `person_type` * | string | Tipo de pessoa (`natural` para PF, `legal` para PJ). | | `name` * | string | Nome da parte relacionada. | | `document_number` * | string | CPF (PF) ou CNPJ (PJ). | | `role_type` * | string | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** | | `street` * | string | Logradouro. | | `number` * | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `postal_code` * | string | CEP (formato "00000-000"). | | `city` * | string | Cidade. | | `state` * | string | UF (2 letras). | | `complement` | string | Complemento do endereço. | | `is_pep` | boolean | (PF) Indica se é Pessoa Politicamente Exposta. | | `marital_status` | string | (PF) Estado civil. | | `property_system` | string | (PF) Regime de bens. | | `birthdate` | string | (PF) Data de nascimento. | | `mother_name` | string | (PF) Nome da mãe. | | `occupation` | string | (PF) Ocupação. | | `trading_name` | string | (PJ) Nome fantasia. | | `cnae_code` | string | (PJ) Código CNAE (formato "00.00-0-00"). | | `company_type` | string | (PJ) Tipo de empresa. | | `foundation_date` | string | (PJ) Data de fundação. | :::warning Atenção Os campos obrigatórios variam conforme o `person_type`: - **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório. - **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios. ::: ### Enumeradores role_type | Enum | Descrição | |------|-----------| | `issuer` | Emissor. | | `investor` | Investidor. | | `cosigner` | Coobrigado. | | `fiduciary_debtor` | Devedor fiduciante. | | `solidary_debtor` | Devedor solidário. | | `guarantor` | Avalista. | | `bonafide_depositary` | Fiel depositário. | | `intervening_guarantor` | Interveniente garantidor. | | `intervening_consentor` | Interveniente anuente. | | `intervening_discharger` | Interveniente quitante. | | `assignor` | Cedente. | | `endorser` | Endossante. | | `consulting` | Consultoria. | | `fund_administrator` | Administrador do fundo. | | `fund_representative` | Representante do fundo. | | `company_representative` | Representante da empresa. | | `attestant` | Anuente / testemunha. | | `debtor` | Devedor. | | `bestowal` | Outorgante. | | `manager` | Gestor. | :::tip Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Cadastro de lastro** desta seção. ::: ### Enumeradores signature_method | Enum | Descrição | |------|-----------| | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | ## **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": { ... } } ``` A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado. --- # Envio de Documento URL: /documentation/escrituracao/emissao-cri/envio-documento Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints da operação sempre que for exigida a chave de um documento previamente enviado. --- ## **Request** ENDPOINT /cri/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |-------------------|--------|----------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | | `document_name` | string | Nome do documento. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|--------|-------------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento enviado (UUID v4). | 36 | --- --- # Enviar Documento Externo da Operação URL: /documentation/escrituracao/emissao-cri/envio-documento-externo Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador. :::warning Aviso Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal. ::: --- ## Enviar Documento Assinado (POST) ### Request ENDPOINT /cri/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|--------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|-----------------------------|-------------------------------------------------------------| | `contract_type` * | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Documento assinado em base64. | - | ### Enumeradores contract_type | Enum | Descrição | |---------------------|--------------------------------------------| | `securitization_term` | Termo de securitização do CRI. | | `adhesion_term` | Termo de adesão do CRI. | | `sa_minute` | Ata de aprovação de emissão do CRI para empresa **SA**. | | `ltda_minute` | Ata de aprovação de emissão do CRI para empresa **LTDA**. | | `cop_minute` | Ata de aprovação de emissão do CRI para **Cooperativa**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Atualização da conta de desembolso da operação. URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso Este endpoint permite a atualização da conta de desembolso de uma operação. --- ## **Atualização da conta de desembolso da operação (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /issuer_bank_account MÉTODO PUT ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (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 ### **Objeto issuer_bank_account** | Campo | Tipo | Descrição | | --------------------------------------- | ------ | ------------------------------------------ | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` * | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`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** | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Chave única do tenant. | | `operation_key` * | string | Chave única da operação. | | `operation_status` * | string | Status da operação. | | `issuer_key` * | string | Chave única do emissor. | | `issuer_name` * | string | Nome do emissor. | | `issuer_document_number` * | string | Documento do emissor. | | `financial` * | object | **[Objeto financial](#objeto-financial-response)** | ### Objeto financial response | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-installments)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | | `daily_rate` * | number | Taxa de juros diária aplicada. | - | | `annual_rate` * | number | Taxa de juros anual aplicada. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Valor percentual da taxa. | - | | `fee_amount` * | number | Valor monetário correspondente à taxa. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Objeto installments | Campo | Tipo | Descrição | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Atualização de dados financeiros na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros Este endpoint permite a atualização dos dados financeiros em uma operação, seguindo o padrão de objeto financial, também enviado no endpoint de simulação. --- ## **Atualização de dados financeiros na Operação (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /financial MÉTODO PUT ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (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 | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_type` * | string | Tipo de juros aplicado. | **[Enumeradores interest_type](#enumeradores-interest_type)** | | `financial_base_date` * | string | Data base da operação (formato "YYYY-MM-DD"). | - | | `released_amount` * | number | Valor total liberado na operação. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | ### Objeto fine_delay_rate | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Base para cálculo da multa. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de multa mensal. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `amount` * | number | Valor da taxa aplicada. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Enumeradores interest_type | Enum | Descrição | |--------------------|------------------------------------------| | `pre_price` | Juros pré-fixados no modelo Price. | | `pre_price_days` | Juros pré-fixados no modelo Price por dias corridos. | | `pre_sac` | Juros pré-fixados no modelo SAC. | | `post_sac` | Juros pós-fixados no modelo SAC. | ### Enumeradores interest_base | Enum | Descrição | |--------------------|------------------------------------------| | `calendar_days` | Base de dias corridos. | | `calendar_days_365`| Base de 365 dias corridos. | | `workdays` | Base de dias úteis. | ### Enumeradores amount_type | Enum | Descrição | |-------------|---------------------------| | `percentage` | Valor em percentual. | | `absolute` | Valor absoluto em moeda. | ### Enumeradores fee_type | Enum | Descrição | |-------------------------------------|-------------------------------------------| | `bookkeeping_fee` | Taxa de escrituração financiada. | | `structuring_fee` | Taxa de estruturação financiada. | ### Enumeradores fee_recipient | Enum | Descrição | |-----------|-------------------------------------------------------| | `internal` | Taxa paga ao escriturador. | | `external` | Rebate pago ao originador. | ## **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** | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Chave única do tenant. | | `operation_key` * | string | Chave única da operação. | | `operation_status` * | string | Status da operação. | | `issuer_key` * | string | Chave única do emissor. | | `issuer_name` * | string | Nome do emissor. | | `issuer_document_number` * | string | Documento do emissor. | | `financial` * | object | **[Objeto financial](#objeto-financial-response)** | ### Objeto financial response | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-installments)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | | `daily_rate` * | number | Taxa de juros diária aplicada. | - | | `annual_rate` * | number | Taxa de juros anual aplicada. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Valor percentual da taxa. | - | | `fee_amount` * | number | Valor monetário correspondente à taxa. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Objeto installments | Campo | Tipo | Descrição | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Atualização do método de assinatura na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura Este endpoint permite a atualização do método de assinatura em uma operação. --- ## **Atualização do método de assinatura na Operação (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signature_method MÉTODO PUT ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "signature_method": "qi_sign" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `signature_method` * | string | Tipo de sistema de assinatura. | 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** | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Chave única do tenant. | | `operation_key` * | string | Chave única da operação. | | `operation_status` * | string | Status da operação. | | `issuer_key` * | string | Chave única do emissor. | | `issuer_name` * | string | Nome do emissor. | | `issuer_document_number` * | string | Documento do emissor. | | `financial` * | object | **[Objeto financial](#objeto-financial-response)** | ### Objeto financial response | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-installments)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | | `daily_rate` * | number | Taxa de juros diária aplicada. | - | | `annual_rate` * | number | Taxa de juros anual aplicada. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Valor percentual da taxa. | - | | `fee_amount` * | number | Valor monetário correspondente à taxa. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Objeto installments | Campo | Tipo | Descrição | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Envio de Garantia na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia Este conjunto de endpoints permite a **adição de garantias** associadas a uma operação. O **collateral será submetido para assinatura junto com os documentos da operação**. Cada tipo de garantia contém as suas regras de documentos necessários e todos os tipos de garantias estão contemplados aqui nesta documentação. --- ## **Envio de Garantia (POST)** ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- O sistema de garantias possibilita a adição de diferentes tipos de instrumentos, cada um com sua própria configuração de documentos adicionais. Nesta sessão, tratamos todos os modelos de garantia disponíveis e seus respectivos payloads. ### **Tipos de Garantias** **[1 - Alienação fiduciária de imóvel](#alienação-fiduciária-de-imóvel)** **[2 - Alienação fiduciária de veículo](#alienação-fiduciária-de-veículo)** **[3 - Alienação fiduciária de aeronave](#alienação-fiduciária-de-aeronave)** **[4 - Alienação fiduciária de equipamentos/produtos/Estoque](#alienação-fiduciária-de-equipamentos-produtos-e-estoque)** **[5 - Alienação fiduciária de obras de arte](#alienação-fiduciária-de-obras-de-arte)** **[6 - Alienação fiduciária de títulos e valores mobiliários](#alienação-fiduciária-de-títulos-e-valores-mobiliários)** **[7 - Alienação fiduciária de Ações e Cotas](#alienação-fiduciária-de-ações-e-cotas)** **[8 - Alienação fiduciária de diretos creditórios](#alienação-fiduciária-de-direitos-creditórios)** **[9 - Hipoteca de imóveis](#hipoteca-de-imóveis)** **[10 - Hipoteca de embarcações](#hipoteca-de-embarcações)** **[11 - Aval](#aval)** **[12 - Fiador](#fiador)** **[13 - Fiança Bancária](#fiança-bancária)** **[14 - Recebiveis de cartão](#recebiveis-de-cartão)** **[15 - Garantia de estoque](#garantia-de-estoque)** **[16 - Monitoramento de garantias](#monitoramento-de-garantias)** **[17 - Outras garantias](#outras-garantias)** ## **Alienação fiduciária de imóvel** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `property_appraisal_report`** | Laudo de Avaliação do Imóvel. | | `property_registration_updated`** | Matrícula atualizada. | | `property_full_content_certificate`** | Certidão de Inteiro Teor da Matrícula. | | `property_insurance_policy` | Apólice de Seguros (se exigível no contrato). | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de imóvel ::: ## **Alienação fiduciária de veículo** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `vehicle_appraisal_report`** | Laudo de Avaliação do Veículo (defasagem máxima de 30 dias) ou Tabela FIPE. | | `vehicle_inspection_report`** | Laudo vistoria. | | `vehicle_crv_certificate`** | Certificado de Registro de Veículo (CRLV) Atualizado. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de veículo ::: ## **Alienação fiduciária de aeronave** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `aircraft_certificate_anac`** | Certificado de Matrícula - ANAC. | | `aircraft_rab_consult`** | Consulta de Aeronave no Registro Aeronáutico Brasileiro. | | `aircraft_insurance_policy`** | Apólice de Seguro - Beneficiário o Fundo. | | `aircraft_appraisal_report`** | Laudo de Avaliação de Aeronave. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de aeronave ::: ## **Alienação fiduciária de equipamentos produtos e estoque** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `equipment_purchase_invoice`** | Nota Fiscal - Registro de Compra. | | `equipment_appraisal_report`** | Laudo de Avaliação de Equipamentos (defasagem máxima de 30 dias). | | `equipment_insurance_policy` | Apólice de Seguro de Equipamentos (se exigível no contrato). | | `fiduciary_depositary_declaration` | Declaração de Fiel Depositário. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de equipamentos/produto/estoque ::: ## **Alienação fiduciária de obras de arte** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `artwork_appraisal_report`** | Laudo de avaliação de Obras de Arte. | | `artwork_storage_certificate`** | Local de Armazenamento com Certificado de Adequação. | | `artwork_insurance_policy` | Apólice de Seguro (se exigível no contrato). | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de obras de arte ::: ## **Alienação fiduciária de títulos e valores mobiliários** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `securities_negotiation_block`** | Bloqueio para Negociação junto ao Custodiante. | | `securities_registration_gravame` | Local de Armazenamento com Certificado de Adequação. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de títulos valores mobiliários. ::: ## **Alienação fiduciária de Ações e Cotas** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `share_registration_book`** | Livro de Registro de Ações Nominativas com Anotação do Gravame. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária/Penhor de Ações/Cotas ::: ## **Alienação fiduciária de diretos creditórios** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_assignment_shares", } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `others` | Outros documentos. | ## **Hipoteca de imóveis** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `property_appraisal_report`** | Laudo de Avaliação de Imóvel. | | `property_registration`** | Registro de Propriedade Atualizado. | | `property_full_content_certificate`** | Certidão de Inteiro Teor da Matrícula. | | `property_insurance_policy` | Apólice de Seguros (se exigível no contrato). | | `others` | Outros documentos. | :::warning (**) Obrigatório para Hipoteca de imóveis. ::: ## **Hipoteca de Embarcações** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `ship_registration`** | Registro de Propriedade de Embarcação Atualizado. | | `ship_appraisal_report`** | Laudo de Avaliação de Embarcação (defasagem máxima de 3 meses). | | `ship_insurance_policy` | Apólice de Seguros de embarcação (se exigível no contrato). | | `others` | Outros documentos. | :::warning (**) Obrigatório para Hipoteca de embarcações. ::: ## **Aval** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `guarantor_civil_status_declaration`** | Declaração de Estado Civil do Avalista. | | `guarantor_personal_document`** | Documento pessoal do Avalista. | | `guarantor_income_tax_declaration` | Declaração de Imposto de Renda do Avalista. | | `others` | Outros documentos. | :::warning (**) Obrigatório para Aval. ::: ## **Fiador** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `surety_civil_status_declaration`** | Declaração de Estado Civil do Fiador. | | `surety_personal_document`** | Documento pessoal do Fiador. | | `surety_income_tax_declaration` | Declaração de Imposto de Renda do Fiador. | | `others` | Outros documentos. | :::warning (**) Obrigatório para Fiador. ::: ## **Fiança Bancária** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `others` | Outros documentos. | ## **Recebiveis de cartão** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `others` | Outros documentos. | ## **Garantia de estoque** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `others` | Outros documentos. | ## **Monitoramento de garantias** 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" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `guarantee_contract`** | Contrato de Garantia. | | `guarantee_agent_contract`** | Contrato de agente de Garantia. | | `others` | Outros documentos. | :::warning (**) Obrigatório para Monitoramento de Garantias.` ::: --- ## **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `collateral_document_key` * | string | Chave do instrumento de Garantia. | Sim | | `collateral_type` * | string | Tipo do collateral. | **[Enumeradores collateral_type](#enumeradores-collateral_type)** | | `collateral_data` | object | Estrutura de metadados relacionados ao collateral. | Sim | | `additional_documents` | list | Documentos relacionados ao collateral. | - | ### **additional_documents list** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `document_key` * | string | Chave do instrumento de Garantia. | Sim | | `document_type` * | string | Tipo do documento da Garantia. | Sim | ### **Enumeradores collateral_type** | Enum | Descrição | |-----------------|-----------------------------------| | `fiduciary_alienation_property` | Alienação fiduciária de imóvel. | | `fiduciary_alienation_vehicle` | Alienação fiduciária de veículo. | | `fiduciary_alienation_aircraft` | Alienação fiduciária de aeronave. | | `fiduciary_alienation_equipment` | Alienação fiduciária de equipamentos/produtos/Estoque. | | `fiduciary_alienation_artwork` | Alienação fiduciária de obras de arte. | | `fiduciary_alienation_securities` | Alienação fiduciária de títulos e valores mobiliários. | | `fiduciary_assignment_shares` | Alienação fiduciária/Penhor de Ações/Cotas. | | `fiduciary_assignment_credit_rights` | Alienação fiduciária de diretos creditórios. | | `mortgage_property` | Hipoteca de imóveis. | | `mortgage_ship` | Hipoteca de embarcações. | | `guarantor` | Aval. | | `surety` | Fiador. | | `bank_surety` | Fiança Bancária. | | `card_receivables` | Recebiveis de cartão. | | `stock_guarantee` | Garantia de estoque. | | `monitoring_guarantee` | Monitoramento de garantias. | | `others` | Outras garantias. | --- # Remoção de Garantia na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia Este endpoint permite a **remoção de garantias** associadas a uma operação. --- ## **Remoção de Collateral (DELETE)** ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral/ COLLATERAL-KEY MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `COLLATERAL-KEY` * | string | Chave única do collateral a ser removido (UUID v4). | 36 | ## **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Envio de documentos URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento Este endpoint permite o envio de **documentos** associados a uma operação. Tais documentos podem ser utilizados no sistema de garantias para realizar a adição de documentos acessórios, além do instrumento da garantia em si. --- ## **Envio de Documento (POST)** ## **Request** ENDPOINT /commercial_paper/upload MÉTODO POST Request Body ```json { "document_base64": "sringb64", } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ## **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|----------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento adicionado (UUID v4). | 36 | --- --- # Cadastro e Remoção de Metadata na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao Este conjunto de endpoints permite o cadastro e a remoção de metadados em uma operação. --- ## **Cadastro de Metadata na Operação (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | Chave do metadado. | 255 | | `metadata_value` * | string | Valor do metadado. | 1023 | ### **Response** STATUS 201 Response Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | Chave do metadado. | 255 | | `metadata_value` * | string | Valor do metadado. | 1023 | --- ## **Remoção de Metadata na Operação (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | Chave do metadado. | 255 | | `metadata_value` * | string | Valor do metadado. | 1023 | --- ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Envio e Remoção de Documentos de Representantes de Partes Relacionadas URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento Este conjunto de endpoints permite o envio e a remoção de documentos associados a representantes de partes relacionadas a uma operação. --- ## **Envio de Documento do Representante (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36 | Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|-----------------------------------------------------------------|-----------------| | `document_base64` * | string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | ## **Response** STATUS 201 Response Body **Cenário 1: Validação Automática (Sucesso no OCR)** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **Significado**: O documento foi processado e validado automaticamente pelo nosso OCR. **Cenário 2: Verificação Manual Necessária** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnh", "ocr_key": null } ``` **Significado**: O documento não pôde ser validado automaticamente pelo OCR e foi encaminhado para nossa fila de verificação manual. :::warning Atenção A resposta para requisições bem-sucedidas (sucesso no envio) apresenta dois comportamentos distintos, dependendo do resultado da validação automática (OCR). ::: ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|----------------------------------------------|-----------------| | `document_key` * | string | Identificador único do documento enviado. | 36 | | `document_type` * | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- ## **Remoção de Documento do Representante (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36 | | `DOCUMENT-KEY` * | string | Chave única do documento a ser removido. | 36 | ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** ### **Enumeradores document_type** | Enum | Descrição | |---------------------------|-----------------------------------------| | `proof_of_address` | Comprovante de Endereço. | | `letter_of_attorney` | Procuração. | | `company_statute` | Estatuto da Empresa. | | `cnh` | Carteira Nacional de Habilitação (CNH). | | `cnh_front` | Frente da CNH. | | `cnh_back` | Verso da CNH. | | `cnh_digital` | CNH Digital. | | `rg_front` | Frente do RG. | | `rg_back` | Verso do RG. | --- # Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes Este conjunto de endpoints permite o envio e a remoção de grupos de assinantes associados a representantes de partes relacionadas a uma operação. --- ## **Envio de Grupo de Assinantes (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (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** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|--------------------------------------------------------|-----------------| | `minimum_required_signers` * | integer | Número mínimo de assinantes necessários no grupo. | - | | `signers` * | array | Lista de assinantes do grupo. | **[Objeto signers](#objeto-signers)** | --- ### **Objeto signers** | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------------|----------|-------------------------------------------------|-----------------| | `name` * | string | Nome completo do assinante. | 255 | | `document_number` * | string | CPF do assinante (11 dígitos). | 11 | | `email` * | string | Endereço de e-mail do assinante. | 1023 | | `phone_number` * | string | Número de telefone do assinante, incluindo DDI. | 20 | | `is_group_mandatory` * | boolean | Indica se o assinante é obrigatório. | - | ## **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** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|-------------------------------------------------|-----------------| | `signer_group_key` * | string | Chave única do grupo de assinantes (UUID v4). | 36 | | `minimum_required_signers` * | integer | Número mínimo de assinantes no grupo. | - | | `signers` * | array | Lista de assinantes do grupo. | **[Objeto signers](#objeto-signers)** | --- ## **Remoção de Grupo de Assinantes (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group/ SIGNER-GROUP-KEY MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36 | | `SIGNER-GROUP-KEY` * | string | Chave única do grupo de assinantes. | 36 | ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Cadastro e Remoção de Partes Relacionadas de um documento específico URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento Este conjunto de endpoints permite o cadastro e a remoção de partes relacionadas a uma operação de um documento específico da operação. --- ## **Adicionar Parte Relacionada ao documento (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document /FORMALIZATION-DOCUMENT-KEY /related_party MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `FORMALIZATION-DOCUMENT-KEY` * | string | Chave única do documento da operação (UUID v4). | 36 | Request Body ```json { "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `related_party_key` * | string | Chave da Parte Relacionada | | 36 ## **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** ## **Remoção de Parte Relacionada (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document/ FORMALIZATION-DOCUMENT-KEY /related_party MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `FORMALIZATION-DOCUMENT-KEY` * | string | Chave única do documento da da operação (UUID v4). | 36 | Request Body ```json { "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Cadastro e Remoção de Partes Relacionadas URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada Este conjunto de endpoints permite o cadastro e a remoção de partes relacionadas a uma operação. :::warning Todas as partes relacionadas são adicionadas por padrão ao Termo Constitutivo (**commercial_paper**), caso deseje adicionar essa parte relacionada à um documento específico, preencher o campo **related_document_key** com a chave do documento desejado. ::: --- ## **Cadastro de Parte Relacionada (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | :::info Importante **Atenção ao tipo de pessoa ao montar o payload:** - **Pessoa Física (PF)**: `"person_type": "natural"` - **Pessoa Jurídica (PJ)**: `"person_type": "legal"` ::: Request Body - Pessoa Física (PF) ```json { "person_type": "natural", "name": "João da Silva", "document_number": "123.731.320-10", "street": "Rua dos Exemplos", "neighborhood": "Centro", "number": "123", "postal_code": "29173-509", "city": "São Paulo", "state": "SP", "role_type": "guarantor", "marital_status": "single", "birthdate": "2000-01-01", "mother_name": "Mãe do João", "father_name": "Pai do João", "occupation": "Desenvolvedor", "is_pep": false } ``` Request Body - Pessoa Jurídica (PJ) ```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** | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `person_type` * | string | Tipo da pessoa. | **[Enumeradores person_type](#enumeradores-person_type)** | | `name` * | string | Nome da parte relacionada. | 255 | | `document_number` * | string | CPF (formato "XXX.XXX.XXX-XX") ou CNPJ (formato "XX.XXX.XXX/XXXX-XX"). | 14 | | `street` * | string | Logradouro do endereço. | 500 | | `neighborhood` | string | Bairro do endereço. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (formato "XXXXX-XXX"). | 8 | | `city` * | string | Cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `role_type` * | string | Papel da parte relacionada. | **[Enumeradores role_type](#enumeradores-role_type)** | | `related_document_key` | string | Chave de identificação do documento (UUIDv4) | 36 ### **Enumeradores person_type** | Enum | Descrição | | ----------- | ---------------- | | `natural` | Pessoa Física | | `legal` | Pessoa Jurídica | ### **Campos adicionais para Pessoa Física** | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------------- | ------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------- | | `document_identification_number` | string | RG (sem formatação) | 20 | | `marital_status` | string | Estado civil. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system` | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `birthdate` | string | Data de nascimento (YYYY-MM-DD). | - | | `nationality` | string | Nacionalidade. | 255 | | `mother_name` | string | Nome da mãe. | 255 | | `father_name` | string | Nome do pai. | 255 | | `occupation` | string | Ocupação. | 255 | | `is_pep` * | boolean | Indica se a parte relacionada é uma Pessoa Politicamente Exposta (PEP). | | ### **Campos adicionais para Pessoa Jurídica** | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | -------------------------------------- | -------------------------------------------------------------- | | `trading_name` * | string | Nome fantasia da empresa. | 1023 | | `cnae_code` * | string | Código CNAE da empresa (10 dígitos). | 10 | | `company_type` * | string | Tipo da empresa. | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date` * | string | Data de fundação (YYYY-MM-DD). | - | ### **Enumeradores role_type** | Enum | Descrição | | -------------------------- | ------------------------ | | `cosigner` | Avalista | | `fiduciary_debtor` | Devedor Fiduciário | | `solidary_debtor` | Devedor Solidário | | `guarantor` | Fiador | | `bonafide_depositary` | Fiel Depositário | | `intervening_guarantor` | Interveniente Fiador | | `intervening_consentor` | Interveniente Anuente | | `intervening_discharger` | Interveniente Quitante | | `assignor` | Cedente | | `endorser` | Endossante | | `consulting` | Consultor | | `fund_administrator` | Administrador do Fundo | | `fund_representative` | Representante do Fundo | | `company_representative` | Representante da Empresa | | `attestant` | Testemunha | | `debtor` | Devedor | | `bestowal` | Outorga Uxória | | `manager` | Gestor | ### Enumeradores marital_status | Enum | Descrição | | ----------- | ---------------- | | `single` | Solteiro(a) | | `married` | Casado(a) | | `divorced` | Divorciado(a) | | `widowed` | Viúvo(a) | | `separated` | Separado(a) | | `stable_union`| União estável | ### Enumeradores property_system | Enum | Descrição | | --------------------------------- | -------------------------------------- | | `total_communion_of_goods` | Comunhão Total de Bens | | `partial_communion_of_goods` | Comunhão Parcial de Bens | | `total_separation_of_goods` | Separação Total de Bens | | `final_participation_of_acquisitions` | Participação Final nos Aquestos | | `compulsory_separation_of_goods` | Separação Obrigatória de Bens | ### Enumeradores company_type | Enum | Descrição | | ------------------- | ---------------------------- | | `ltda` | Sociedade Limitada | | `sa` | Sociedade Anônima | | `cop` | Cooperativa | ## **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** | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------------- | ------- | ---------------------------------------------------- | ------------------------------------------------------------ | | `related_party_key` * | string | Chave única da parte relacionada. | 36 | | `name` * | string | Nome da parte relacionada. | 255 | | `document_number` * | string | CPF/CNPJ da parte relacionada. | 14 | | `role_type` * | string | Papel da parte relacionada. | 50 | | `is_active` * | boolean | Indica se está ativa. | - | | `updated_at` | string | Data da última atualização (YYYY-MM-DD HH:mm:ss). | - | | `person_type` * | string | Tipo da pessoa. | **[Enumeradores person_type](#enumeradores-person_type)** | | `street` * | string | Logradouro. | 500 | | `neighborhood` | string | Bairro. | 100 | | `number` * | string | Número. | 10 | | `postal_code` * | string | CEP (somente números). | 8 | | `city` * | string | Cidade. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | --- ## **Remoção de Parte Relacionada (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada. | 36 | ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Cadastro de Operação de Nota Comercial URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao Este endpoint permite criar uma nova operação de nota comercial com base nos dados financeiros e de investidores. --- ## **Request** ENDPOINT /commercial_paper/operation MÉTODO 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** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------------- | ------ | ------------------------------------------------------ | ---------------------------------------------------------------- | | `issuer_key` * | string | Chave única do emissor. | - | | `issuer_bank_account` * | object | Conta bancária do emissor. | **[Objeto issuer_bank_account](#objeto-issuer_bank_account)** | | `investors` * | array | Lista de investidores envolvidos. | **[Objeto investors](#objeto-investors)** | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `financial` * | object | Dados financeiros da operação. | **[Objeto financial](#objeto-financial)** | ### **Objeto issuer_bank_account** | Campo | Tipo | Descrição | | --------------------------------------- | ------ | ------------------------------------------ | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` * | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`). | ### **Objeto investors** | Campo | Tipo | Descrição | | ----------------------------- | ------ | ------------------------------ | | `investor_key` * | string | Chave única do investidor. | | `subscription_percentage` * | number | Percentual de subscrição. | | `bank_account` * | object | Conta bancária do investidor. | ### **Objeto financial** | Campo | Tipo | Descrição | | ---------------------------- | ------- | -------------------------------------------- | | `interest_type` * | string | Tipo de juros. | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `released_amount` | number | Valor liberado. | | `issue_amount` | number | Valor de Emissão. | | `number_of_installments` * | integer | Número de parcelas. | | `installments` | array | **[Objeto installments](#objeto-installments)** | | `prefixed_interest_rate` * | object | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fine_delay_rate` * | object | Taxa de multa por atraso. | | `contract_fine_rate` * | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | :::warning Atenção O **objeto financial** deve conter uma combinação válida de parâmetros para ser processado. As combinações aceitas são: Valor de Emissão/Liberado + Taxa de Juros, Valor de Emissão/Liberado + Valor por Parcela, Valor por Parcela + Taxa de Juros, Valor de Emissão/Liberado + Taxa de Juros + Percentual de Amortização por Parcela. ::: ### Objeto installments | Campo | Tipo | Descrição | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------| | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | | `amount` | number | Valor total da parcela. | | `principal_amortization_percentage` | number | Valor percentual amortizado do principal. | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------| | `interest_base` * | string | Base de cálculo para os juros. | - | | `daily_rate` | number | Taxa de juros diária aplicada. | - | | `monthly_rate` | number | Taxa de juros mensal aplicada. | - | | `annual_rate` | number | Taxa de juros anual aplicada. | - | ### Enumeradores signature_method | Valor | Descrição | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | ## **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** | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Chave única do tenant. | | `operation_key` * | string | Chave única da operação. | | `operation_status` * | string | Status da operação. | | `issuer_key` * | string | Chave única do emissor. | | `issuer_name` * | string | Nome do emissor. | | `issuer_document_number` * | string | Documento do emissor. | | `financial` * | object | **[Objeto financial](#objeto-financial-response)** | ### Objeto financial response | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate-response)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-installments-response)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto prefixed_interest_rate response | Campo | Tipo | Descrição | | ------------------- | ------ | ------------------------------- | | `interest_base` * | string | Base de cálculo para os juros. | | `monthly_rate` | number | Taxa de juros mensal aplicada. | | `daily_rate` | number | Taxa de juros diária aplicada. | | `annual_rate` | number | Taxa de juros anual aplicada. | ### Objeto fees | Campo | Tipo | Descrição | | ----------------- | ------ | ---------------------------------------- | | `amount` * | number | Valor percentual da taxa. | | `fee_amount` * | number | Valor monetário correspondente à taxa. | | `amount_type` * | string | Tipo do valor da taxa. | | `fee_type` * | string | Tipo da taxa. | | `type` * | string | Destinatário da taxa. | ### Objeto installments response | Campo | Tipo | Descrição | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Campos Extras (Extra Fields) URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields Este conjunto de endpoints permite consultar os campos extras disponíveis em um template de documento e salvar valores personalizados para esses campos em uma operação. :::warning Para utilizar os campos extras, é necessário que o template do documento já tenha sido definido. Caso contrário, gere uma pré-visualização de minuta antes de utilizar estes endpoints. ::: :::info Importante Os campos extras são organizados por tipo de documento (`document_type`). Ao salvar campos extras via POST, os valores anteriores para aquele `document_type` são **substituídos integralmente** — não é feito merge com valores existentes. ::: --- ## **Consulta de Campos Extras Disponíveis (GET)** Retorna os campos extras disponíveis no template associado ao tipo de documento da operação. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | ### **Query Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `document_type` * | string | Tipo do documento. | **[Enumeradores document_type](#enumeradores-document_type)** | ### **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** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `document_type` * | string | Tipo do documento consultado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `template_key` * | string | Chave única do template associado (UUID v4). | 36 | | `extra_fields` * | array | Lista de campos extras disponíveis no template. | - | ### **Campos do objeto extra_fields** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `field_key` * | string | Identificador único do campo extra. | 255 | | `field_label` * | string | Rótulo descritivo do campo extra. | 255 | | `field_type` * | string | Tipo de dado do campo extra (ex: `string`). | 50 | --- ## **Salvar Campos Extras (POST)** Salva os valores dos campos extras para um tipo de documento específico em uma operação. Os valores enviados substituem integralmente os campos extras anteriores para o `document_type` informado. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (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** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `document_type` * | string | Tipo do documento. | **[Enumeradores document_type](#enumeradores-document_type)** | | `extra_fields` * | object | Objeto contendo os campos extras e seus valores. As chaves devem corresponder aos `field_key` retornados na consulta GET. Todos os valores devem ser strings. | - | :::warning As chaves enviadas no objeto `extra_fields` devem corresponder exatamente aos `field_key` disponíveis no template. Chaves inválidas resultarão em erro. ::: ### **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** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `document_type` * | string | Tipo do documento. | **[Enumeradores document_type](#enumeradores-document_type)** | | `extra_fields` * | object | Objeto contendo os campos extras salvos com seus respectivos valores. | - | --- ## **Enumeradores document_type** | Enum | Descrição | | -------------------- | ---------------------- | | `commercial_paper` | Termo Constitutivo | | `adhesion_term` | Termo de Adesão | --- ## **Erros** | Código | HTTP | Descrição | | ---------- | ---- | -------------------------------------------------------------------------------------------------------- | | `COM000007` | 404 | Operação não encontrada. | | `COM000008` | 403 | Operação não pertence ao tenant solicitante. | | `COM000044` | 400 | Template não definido para o tipo de documento. Gere uma pré-visualização de minuta antes de prosseguir. | | `COM000045` | 400 | Chaves de campos extras não disponíveis no template. | --- # Cancelar Operação URL: /documentation/escrituracao/emissao-de-notas/cancelar-operacao Este endpoint permite alterar o status de uma operação para "cancelado", status final para caso em que a operação não será mais finalizada pelo cliente. --- ## Cancelar Operação (PATCH) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body ```json { "operation_status": "canceled" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |--------------------|----------|------------------------------------------------------------|-------------| | `operation_status` | string | Status da operação. Deve ser definido como `canceled`. | Sim | --- ### Response O corpo da resposta é um JSON completo da operação atualizado. --- --- # Consulta do Link dos contratos assinados via QI SIGN da Operação URL: /documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign Este endpoint permite consultar todos os documentos assinados de uma operação específica via QI SIGN, utilizando sua chave única. --- :::warning Atenção O link do contrato assinado tem validade de 24 horas. Após isso, é necessário renovar o link fazendo uma nova requisição pelo endpoint. ::: ## Consulta de Link Assinado da Operação (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signed_url 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 { "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 | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `envelope_key` | string | Chave única do envelope (UUID v4). | 36 | | `status` | string | Status dos envelopes | [Enumeradores status](#enumeradores-operation-status) | `documents` | list | Lista de documentos do envelope | - | ### Objeto document | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_type` | string | Tipo do documento. | [Enumeradores document type](#enumeradores-document-type) | | `signed_url` | string | Url do contrato assinado para download | - | | `signers` | list | Lista de assinantes | - | ## **Enumeradores operation-status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `waiting_signature` | Aguardando assinaturas dos envolvidos. | | `signed` | Assinatura finalizada. | | `signature_rejected` | Assinatura rejeitada. | | `canceled` | Operação cancelada. | ## **Enumeradores document-type** | Enum | Descrição | |----------------------------------|------------------------------------------------------------------| | `contract` | Identificador do contrato. | | `ncom_pre_price` | Nota comercial Pre price. | | `ncom_pre_price_days` | Nota comercial Pre price days. | | `ncom_pre_sac` | Nota comercial Pre sac. | | `ncom_post_sac_cdi` | Nota comercial Pós sac vinculado ao CDI. | | `ncom_post_sac_ipca` | Nota comercial Pós sac vinculado ao IPCA. | | `ncom_post_sac_igpm` | Nota comercial Pós sac vinculado ao IGP-M. | | `ncom_post_price_cdi` | Nota comercial Pós price vinculado ao CDI. | | `ncom_post_price_ipca` | Nota comercial Pós price vinculado ao IPCA. | | `ncom_post_price_igpm` | Nota comercial Pós price vinculado ao IGP-M. | | `ncom_post_price_days_cdi` | Nota comercial Pós price days vinculado ao CDI. | | `ncom_post_price_days_ipca` | Nota comercial Pós price days vinculado ao IPCA. | | `ncom_post_price_days_igpm` | Nota comercial Pós price days vinculado ao IGP-M. | | `subscription_note` | Boletim de subscrição. | | `adhesion_term` | Termo de adesão. | --- # Consulta dos Links para assinatura via QI SIGN da Operação URL: /documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign Este endpoint permite consultar todos os links para assinatura de uma operação específica via QI SIGN, utilizando sua chave única. --- ## Consulta de Link para Assinatura da Operação (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signers 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 { "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 | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `envelope_key` | string | Chave única do envelope (UUID v4). | 36 | | `status` | string | Status dos envelopes | [Enumeradores operation status](#enumeradores-operation-status) | `documents` | list | Lista de documentos do envelope | - | ### Objeto document | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_type` | string | Tipo do documento. | [Enumeradores document type](#enumeradores-document-type) | | `signers` | list | Lista de assinantes | - | ### Objeto signer | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_number` | string | Documento do assinante. | 18 | | `signature_url` | string | Link do assinante | - | | `status` | string | Status do assinante. | [Enumeradores status](#enumeradores-status) | | `name` | string | nome do assinante | - | | `email` | string | email do assinante | - | ## **Enumeradores operation-status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `waiting_signature` | Aguardando assinaturas dos envolvidos. | | `signed` | Assinatura finalizada. | | `signature_rejected` | Assinatura rejeitada. | | `canceled` | Operação cancelada. | ## **Enumeradores status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `on_signature` | Aguardando assinaturas dos envolvidos. | | `analyzed` | Assinatura completa via API. | | `signed` | Assinatura finalizada. | | `signature_rejected` | Assinatura rejeitada. | | `canceled` | Operação cancelada. | | `created` | Assinatura criada. | | `submitted` | Enviado para o assinante. | | `sending_sign_receipt` | Enviando dossiê simplificado da assinatura. | | `analyzing` | Assinantes em análise. | | `completed` | Assinatura completa. | | `expired` | Assinatura expirada. | | `removed` | Assinante removido. | | `failed_waiting_for_manual_fix` | Criação da assinatura falhou, ação manual da QI necessária. | ## **Enumeradores document-type** | Enum | Descrição | |----------------------------------|------------------------------------------------------------------| | `contract` | Identificador do contrato. | | `ncom_pre_price` | Nota comercial Pre price. | | `ncom_pre_price_days` | Nota comercial Pre price days. | | `ncom_pre_sac` | Nota comercial Pre sac. | | `ncom_post_sac_cdi` | Nota comercial Pós sac vinculado ao CDI. | | `ncom_post_sac_ipca` | Nota comercial Pós sac vinculado ao IPCA. | | `ncom_post_sac_igpm` | Nota comercial Pós sac vinculado ao IGP-M. | | `ncom_post_price_cdi` | Nota comercial Pós price vinculado ao CDI. | | `ncom_post_price_ipca` | Nota comercial Pós price vinculado ao IPCA. | | `ncom_post_price_igpm` | Nota comercial Pós price vinculado ao IGP-M. | | `ncom_post_price_days_cdi` | Nota comercial Pós price days vinculado ao CDI. | | `ncom_post_price_days_ipca` | Nota comercial Pós price days vinculado ao IPCA. | | `ncom_post_price_days_igpm` | Nota comercial Pós price days vinculado ao IGP-M. | | `subscription_note` | Boletim de subscrição. | | `adhesion_term` | Termo de adesão. | --- # Consulta de Operação por Chave URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave Este endpoint permite consultar os detalhes completos de uma operação específica, utilizando sua chave única. --- ## Consulta de Operação (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY 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 { "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" } ], "integralization_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "security_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `tenant_key` * | string | Chave única do tenant (UUID v4). | 36 | | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `operation_type` * | string | Tipo da operação. `commercial_paper` | - | | `operation_status` * | string | Status da operação. | [Enumeradores operation_status](#enumeradores-operation_status) | | `issuer_key` * | string | Chave única do emissor (UUID v4). | 36 | | `issuer_name` * | string | Nome do emissor. | - | | `issuer_document_number` * | string | Número do documento do emissor (CNPJ). | 18 | | `issuer_bank_account` * | object | Dados bancários do emissor. | [Objeto bank_account](#objeto-bank_account) | | `issuer_onboarding_approved` * | boolean | Indica se o onboarding do emissor foi aprovado. | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `contract_number` * | string | Número do contrato. | - | | `issue_date` * | string | Data da emissão (formato ISO 8601). | - | | `financial_base_date` * | string | Data base financeira da operação (formato ISO 8601). | - | | `commercial_paper_template_key` * | string | Chave única do template do commercial paper. | 36 | | `commercial_paper_document_key` * | string | Chave do documento do commercial paper. | - | | `adhesion_term_template_key` * | string | Chave única do template do termo de adesão. | 36 | | `adhesion_term_document_key` * | string | Chave do documento do termo de adesão. | - | | `investor_list` * | object | Lista de investidores. | [Objeto investor](#objeto-investor) | ### Objeto bank_account | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_type` * | string | Tipo da conta (ex: checking). | - | | `account_digit` * | string | Dígito da conta bancária. | - | | `account_branch` * | string | Agência bancária. | - | | `account_number` * | string | Número da conta bancária. | - | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | - | | `financial_institution_code_number` * | string | Código da instituição financeira. | - | ### Objeto financial | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|-----------------------------------------------------------------|-----------------------------------------------------------------| | `financial_base_date` * | string | Data base financeira da operação (formato ISO 8601). | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | float | Preço unitário da emissão. | - | | `issue_amount` * | float | Valor total da emissão. | - | | `released_amount` * | float | Valor total liberado. | - | | `cet` * | float | Custo Efetivo Total da operação (%). | - | | `annual_cet` * | float | Custo Efetivo Total anualizado (%). | - | | `number_of_installments` * | integer | Número total de parcelas da operação. | - | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | [Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate) | | `fine_delay_rate` * | object | Taxa de multa por atraso | [Objeto fine_delay_rate](#objeto-fine_delay_rate). | | `contract_fine_rate` * | float | Taxa de multa contratual (%). | - | | `financial_index` | string | Índice financeiro de referência (caso exista). | - | | `post_fixed_interest_rate` | object | Taxa de juros pós-fixada (se aplicável). | - | | `fees` * | array | Lista de taxas aplicáveis.| [Objeto fees](#objeto-fees) | | `installment_list` * | array | Lista de parcelas. | [Objeto installment](#objeto-installment) | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------|--------|------------------------------------------------------------|-----------------| | `daily_rate` * | float | Taxa de juros diária (%). | - | | `annual_rate` * | float | Taxa de juros anualizada (%). | - | | `monthly_rate` * | float | Taxa de juros mensal (%). | - | | `interest_base` * | string | Base de cálculo da taxa de juros (`calendar_days_365`). | - | ## Objeto fine_delay_rate | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|--------------------------------------------------|-----------------| | `monthly_rate` * | float | Taxa de multa mensal por atraso (%). | - | | `interest_base` * | string | Base de cálculo da taxa de juros (`calendar_days_365`). | - | ## Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | |---------------|---------|------------------------------------------------|-----------------| | `type` * | string | Tipo da taxa (`internal`, `external`). | - | | `amount` * | float | Percentual da taxa aplicada. | - | | `fee_type` * | string | Tipo da taxa. | - | | `fee_amount` * | float | Valor absoluto da taxa aplicada. | - | | `amount_type` * | string | Tipo do valor (`percentage`, `fixed`). | - | ## Objeto installment | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------------|---------|----------------------------------------------------------|-----------------| | `installment_number` * | integer | Número da parcela. | - | | `workdays` * | integer | Quantidade de dias úteis até o vencimento. | - | | `calendar_days` * | integer | Quantidade de dias corridos até o vencimento. | - | | `principal_amortization_unit_price` * | float | Valor unitário de amortização do principal. | - | | `principal_amortization_amount` * | float | Valor total de amortização do principal. | - | | `interest_amount` * | float | Valor total dos juros da parcela. | - | | `amount` * | float | Valor total da parcela. | - | | `due_principal` * | float | Valor do principal a vencer após a parcela. | - | | `due_interest` * | float | Valor dos juros a vencer após a parcela. | - | | `due_date` * | string | Data de vencimento da parcela (formato ISO 8601). | - | | `has_interest` * | boolean | Indica se a parcela possui cobrança de juros. | - | ## Objeto investor | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------------------|---------|----------------------------------------------------------------------|----------------------------------------------| | `investor_key` * | string | Chave única do investidor (UUID v4). | 36 | | `investor_name` * | string | Nome do investidor. | - | | `investor_document_number` * | string | Número do documento do investidor (CNPJ/CPF). | 18 | | `subscription_percentage` * | float | Percentual de participação do investidor na operação. | - | | `subscription_quantity` * | integer | Quantidade de unidades subscritas pelo investidor. | - | | `investor_onboarding_approved` * | boolean | Indica se o onboarding do investidor foi aprovado. | - | | `bank_account` * | object | Informações bancárias do investidor. | [Objeto bank_account](#objeto-bank_account). | ## **Enumeradores operation_status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `in_filling` | Operação em fase de preenchimento. | | `in_analysis` | Operação em análise. | | `waiting_onboarding_approval` | Aguardando aprovação do onboarding do emissor. | | `pending_signature_submission` | Aguardando envio para assinatura. | | `waiting_signature` | Aguardando assinaturas dos envolvidos. | | `issued` | Operação emitida. | | `finished` | Operação concluída. | | `signature_rejected` | Assinatura rejeitada. | | `onboarding_reproved` | Onboarding do emissor reprovado. | | `compliance_reproved` | Reprovado por compliance. | | `canceled` | Operação cancelada. | --- # Consulta de Operações por Filtros URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros Este endpoint permite consultar operações de **nota comercial** utilizando filtros opcionais. --- ## **Request** ENDPOINT /commercial_paper/operation MÉTODO GET ### **Query Params** | Campo | Tipo | Descrição | Obrigatório | |----------------------------|----------|-----------------------------------------------|-------------| | `issuer_document_number` | string | Número do documento do emissor (CNPJ). | Não | | `investor_document_number` | string | Número do documento do investidor (CPF/CNPJ). | Não | | `operation_status` | string | Status da operação. | **[Enumeradores operation_status](#enumeradores-operation_status)** | Não | | `metadata_key` | array | Chave de metadado. | Não | | `metadata_value` | array | Valor de metadado. | Não | --- ## **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** #### **Objeto Data** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|-----------------------------------------------------------|-----------------| | `tenant_key` * | string | Chave única do tenant (UUID v4). | 36 | | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `operation_type` * | string | Tipo da operação. Sempre será `commercial_paper`. | 50 | | `operation_status` * | string | Status atual da operação. | **[Enumeradores operation_status](#enumeradores-operation_status)** | 50 | | `backoffice_analysis_status` | string | Status da análise de backoffice. | 50 | | `issuer_key` * | string | Chave única do emissor associado à operação (UUID v4). | 36 | | `issuer_name` * | string | Nome do emissor associado à operação. | 255 | | `issuer_document_number` * | string | Número do documento do emissor (CNPJ). | 14 | | `issue_number` * | integer | Número da emissão associada à operação. | - | | `contract_number` * | string | Número do contrato associado à operação. | 20 | #### **Objeto Pagination** | Campo | Tipo | Descrição | |-------------------|----------|----------------------------------------------------------| | `current_page` * | integer | Página atual da consulta. | | `next_page` | integer | Próxima página, caso exista. | | `rows_per_page` * | integer | Número de registros por página. | | `total_pages` * | integer | Total de páginas disponíveis. | | `total_rows` * | integer | Total de registros encontrados para os filtros aplicados. | --- ## **Enumeradores operation_status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `in_filling` | Operação em fase de preenchimento. | | `in_analysis` | Operação em análise. | | `waiting_onboarding_approval` | Aguardando aprovação do onboarding do emissor. | | `pending_signature_submission` | Aguardando envio para assinatura. | | `waiting_signature` | Aguardando assinaturas dos envolvidos. | | `issued` | Operação emitida. | | `finished` | Operação concluída. | | `signature_rejected` | Assinatura rejeitada. | | `onboarding_reproved` | Onboarding do emissor reprovado. | | `compliance_reproved` | Reprovado por compliance. | | `canceled` | Operação cancelada. | --- # Consulta do Próximo Número de Emissão por Emissor URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao Este endpoint retorna o próximo `issue_number` (número de emissão) disponível para o emissor identificado por `issuer_key`. O valor retornado considera a maior numeração já utilizada em operações **não canceladas** do emissor e o controle interno de numeração na configuração do emissor — sempre é devolvido o maior entre os dois. Caso ainda não exista configuração de numeração para o emissor, ela é criada automaticamente com `current_issue_number = 1` e esse valor é retornado. --- ## **Request** ENDPOINT /commercial_paper/issuer/ ISSUER-KEY /issue_number MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|-------------|---------------------------------------------------------------------------|-----------------| | `ISSUER-KEY` * | string/uuid | Identificador único (UUID v4) do emissor cadastrado no Issuer Management. | 36 | --- ## **Response** STATUS 200 Response Body ```json { "issue_number": 42 } ``` --- ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|---------|----------------------------------------------------------------------------------------------------------------------|-----------------| | `issue_number` * | integer | Próximo número de emissão sugerido para uma nova operação do emissor. Inicia em `1` para emissores sem operações nem configuração prévia. | - | --- # Enviar Atas de Aprovação Assinadas URL: /documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao Este endpoint permite enviar as atas de aprovação de empresas do tipo SA ou COP assinadas de forma externa para o sistema de escrituação, enviando um base64 que será analisado e aprovado pelo escriturador. --- ## Enviar Operação Assinada (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "sa_minute" } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `contract_type` * | string | Tipo de contrato assinado | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Contrato assinado em base64 ### Enumeradores contract_type | Enum | Descrição | |--------------------|------------------------------------------| | `sa_minute` | Ata de aprovação de emissão da nota comercial para empresa **SA**. | | `coo_minute` | Ata de aprovação de emissão da nota comercial para empresa **COOPERATIVA**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Enviar Operação para Análise URL: /documentation/escrituracao/emissao-de-notas/envio-para-analise Este endpoint permite alterar o status de uma operação para "em análise", enviando-a para o processo de validação de compliance pelo escriturador. --- ## Enviar Operação para Análise (PATCH) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body ```json { "operation_status": "in_analysis" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |--------------------|----------|------------------------------------------------------------|-------------| | `operation_status` | string | Status da operação. Deve ser definido como `in_analysis`. | Sim | --- ### Response O corpo da resposta é um JSON completo da operação atualizado. --- --- # Enviar Operação para Assinatura URL: /documentation/escrituracao/emissao-de-notas/envio-para-assinatura :::warning Aviso Operações aprovadas pelo compliance são enviadas automaticamente para assinatura periodicamente. Este endpoint deve ser usado apenas para realizar um envio imediato, caso necessário. ::: --- ## Enviar Operação para Assinatura (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /send_to_signature MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Nenhum corpo de requisição é necessário. --- ### Response O corpo da resposta é um JSON completo da operação atualizado. --- --- # Alterar Template do Termo de Adesão URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta Este endpoint permite a alteração do template do Termo de Adesão para uma operação específica. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- Request Body ```json { "adhesion_term_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------------|----------|--------------------------------------------------|-------------| | `adhesion_term_template_key` * | string | Chave única do novo template a ser utilizado (UUID v4). | Sim | ## Response O corpo da resposta é um JSON completo da operação atualizado. --- # Alterar Template do Termo Constitutivo URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc Este endpoint permite a alteração do template do Termo Constitutivo para uma operação específica. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- Request Body ```json { "commercial_paper_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------------|----------|--------------------------------------------------|-------------| | `commercial_paper_template_key` * | string | Chave única do novo template a ser utilizado (UUID v4). | Sim | ## Response O corpo da resposta é um JSON completo da operação atualizado. --- # Pré-visualizar Termo de Adesão URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao Este endpoint permite a pré-visualização de uma minuta do Termo de Adesão para uma operação específica, utilizando um template predefinido. --- ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_adhesion_term MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------------|----------|--------------------------------------------------|-------------| | `template_key` * | string | Chave única do novo template a ser utilizado (UUID v4). | Sim | ## **Response** STATUS 201 Response Body ```json { "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "document_type": "adhesion_term", "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|------------------------------------------------|-----------------| | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `document_type` * | string | Tipo do documento gerado. Sempre será `adhesion_term`. | 50 | | `document_base64` * | string | Conteúdo do documento gerado, codificado em Base64. | - | --- # Pré-visualizar Termo Constitutivo URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato Este endpoint permite a geração de uma minuta do Termo Constitutivo para uma operação específica, utilizando um template predefinido. --- ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_commercial_paper MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------------|----------|--------------------------------------------------|-------------| | `template_key` * | string | Chave única do novo template a ser utilizado (UUID v4). | Sim | ## **Response** STATUS 201 Response Body ```json { "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "document_type": "commercial_paper", "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|------------------------------------------------|-----------------| | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `document_type` * | string | Tipo do documento gerado. Sempre será `commercial_paper`. | 50 | | `document_base64` * | string | Conteúdo do documento gerado, codificado em Base64. | - | --- # Introdução à Emissão de Notas Comerciais URL: /documentation/escrituracao/emissao-de-notas/inicio As notas comerciais são instrumentos financeiros utilizados por empresas para captar recursos diretamente no mercado. Este processo envolve diversas etapas, desde o cadastro de emissores e investidores, passando pela definição de condições financeiras, até a emissão formal dos títulos. Cada etapa é crucial para garantir a conformidade regulatória e a eficiência no processo de captação. --- ## Visão Geral do Processo de Emissão O processo de emissão de notas comerciais é estruturado em várias etapas, que garantem transparência, segurança e controle. Abaixo, estão os principais passos do processo: 1. **Cadastro de Emissores e Investidores** Empresas que desejam emitir notas comerciais e investidores interessados em adquirir esses títulos precisam ser cadastrados no sistema. O cadastro inclui informações detalhadas, como documentos e contas bancárias. 2. **Definição das Condições da Operação** O emissor define as condições financeiras da operação, incluindo taxas de juros, número de parcelas, datas de emissão e vencimento, além de eventuais taxas e encargos. 3. **Simulação** Antes da emissão formal, é realizada uma simulação para calcular os valores de emissão, o fluxo de parcelas e outros detalhes financeiros. Esta etapa permite ajustar as condições da operação de acordo com as necessidades do emissor e dos investidores. 4. **Cadastro de Partes Relacionadas e Documentação** Inclui o registro de partes envolvidas, como garantidores e coobrigados, e o envio de documentos relevantes, como contratos e termos. 5. **Geração e Assinatura de Documentos** São geradas as minutas dos principais documentos, como o **Termo de Adesão** e o **Termo Constitutivo**. Após aprovação, os documentos são enviados para assinatura eletrônica. 6. **Envio para Análise e Aprovação** A operação é submetida para análise de compliance e backoffice, garantindo que todas as exigências regulatórias e contratuais sejam atendidas. 7. **Emissão Formal e Registro** Após aprovação, as notas comerciais são formalmente emitidas e disponibilizadas para os investidores. A partir das próximas páginas, exploraremos em detalhes cada etapa do processo de emissão de notas comerciais, incluindo endpoints e exemplos práticos para integrar seu sistema à API. --- # Simulação de condições financeiras URL: /documentation/escrituracao/emissao-de-notas/simulacao Este endpoint permite simular as condições financeiras e o fluxo de pagamentos de uma operação --- :::warning Atenção O **Request Body** deve conter uma combinação válida de parâmetros para ser processado. As combinações aceitas são: - Valor de Emissão/Liberado + Taxa de Juros - Valor de Emissão/Liberado + Valor por Parcela - Valor por Parcela + Taxa de Juros - Valor de Emissão/Liberado + Taxa de Juros + Percentual de Amortização por Parcela. ::: ## Request ENDPOINT /commercial_paper/simulation MÉTODO POST ## Operação pré-fixada Valor de emissão + Taxa ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-01-20", "issue_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" } ], "first_due_date_delay": 60, } ``` Valor desembolsado + Taxa ```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": "bookkeeping_fee", "type": "external" } ], "first_due_date": "2026-01-31" } ``` Valor da parcela + taxa de juros ```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": "structuring_fee", "type": "external" } ] } ``` Valor de emissão + Percentual de amortização da parcela + taxa de juros ```json { "interest_type": "pre_sac", "financial_base_date": "2025-01-20", "issue_amount": 1000000, "number_of_installments": 3, "installments": [ { "due_date": "2026-01-01", "principal_amortization_percentage": 0.1 }, { "due_date": "2026-02-01", "principal_amortization_percentage": 0.1 }, { "due_date": "2026-03-01", "principal_amortization_percentage": 0.8 } ], "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", "type": "external" } ] } ``` Valor de emissão + Valor das parcelas ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-01-20", "issue_amount": 700000, "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", }, "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" } ] } ``` ## Operação pós-fixada Valor de emissão + Taxa + Pós fixado ```json { "interest_type": "post_price_days", "financial_base_date": "2025-01-20", "issue_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": 1000, "amount_type": "absolute", "fee_type": "structuring_fee", "type": "external" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` Valor desembolsado + Taxa + Pós fixado ```json { "interest_type": "post_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": "bookkeeping_fee", "type": "external" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` Valor da parcela + taxa de juros + Pós fixado ```json { "interest_type": "post_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": "structuring_fee", "type": "external" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` Valor de emissão + Percentual de amortização da parcela + taxa de juros + Pós fixado ```json { "interest_type": "post_sac", "financial_base_date": "2025-01-20", "issue_amount": 1000000, "number_of_installments": 3, "installments": [ { "due_date": "2026-01-01", "principal_amortization_percentage": 0.1 }, { "due_date": "2026-02-01", "principal_amortization_percentage": 0.1 }, { "due_date": "2026-03-01", "principal_amortization_percentage": 0.8 } ], "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" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` Valor de emissão + Valor das parcelas + Pós fixado ```json { "interest_type": "post_price_days", "financial_base_date": "2025-01-20", "issue_amount": 700000, "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", }, "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" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_type` * | string | Tipo de juros aplicado. | **[Enumeradores interest_type](#enumeradores-interest_type)** | | `financial_base_date` * | string | Data base da operação (formato "YYYY-MM-DD"). | - | | `released_amount` | number | Valor total liberado na operação. | - | | `issue_amount` | number | Valor de emissão da operação. | `number_of_installments` * | integer | Número total de parcelas. | - | | `installments` | array | Objeto contendo detalhes sobre cada parcela. | **[Objeto installments](#objeto-installments)** | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `post_fixed_interest_rate` | number | Valor da taxa pós fixada prefixada. | - | | `financial_index` | string | Tipo de Taxa pós-fixada. | **[Enumeradores financial_index](#enumeradores-financial_index)** | | `first_due_date` | date | Data da primeira parcela | - | | `first_due_date_delay` | number | Dias para o ínicio do pagamento da primeira parcela. | - | ### Objeto installments | Campo | Tipo | Descrição | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------| | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | | `amount` | number | Valor total da parcela. | | `principal_amortization_percentage` | number | Valor percentual amortizado do principal. | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `daily_rate` | number | Taxa de juros diária aplicada. | - | | `monthly_rate` | number | Taxa de juros mensal aplicada. | - | | `annual_rate` | number | Taxa de juros anual aplicada. | - | ### Objeto fine_delay_rate | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Base para cálculo da multa. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de multa mensal. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `amount` * | number | Valor da taxa aplicada. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Enumeradores interest_type | Enum | Descrição | |--------------------|------------------------------------------| | `pre_price` | Juros pré-fixados no modelo Price. | | `pre_price_days` | Juros pré-fixados no modelo Price por dias corridos. | | `pre_sac` | Juros pré-fixados no modelo SAC. | | `post_sac` | Juros pós-fixados no modelo SAC. | | `post_price_days` | Juros pós-fixados no modelo Price por dias corridos. | ### Enumeradores financial_index | Enum | Descrição | |--------------------|------------------------------------------| | `CDI` | Pós fixado de CDI | | `IPCA` | Pós fixado de IPCA | | `IGPM` | Pós fixado de IGPM | ### Enumeradores interest_base | Enum | Descrição | |--------------------|------------------------------------------| | `calendar_days` | Base de dias corridos. | | `calendar_days_365`| Base de 365 dias corridos. | | `workdays` | Base de dias úteis. | ### Enumeradores amount_type | Enum | Descrição | |-------------|---------------------------| | `percentage` | Valor em percentual. | | `absolute` | Valor absoluto em moeda. | ### Enumeradores fee_type | Enum | Descrição | |-------------------------------------|-------------------------------------------| | `bookkeeping_fee` | Taxa de escrituração financiada. | | `structuring_fee` | Taxa de estruturação financiada. | ### Enumeradores fee_recipient | Enum | Descrição | |-----------|-------------------------------------------------------| | `internal` | Taxa paga ao escriturador. | | `external` | Rebate pago ao originador. | ## 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 | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------|-----------------| | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-response-prefixed_interest_rate)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-response-installments)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto Response prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | |---------------|----------|------------------------------------------------------------|-----------------| | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | | `daily_rate` * | number | Taxa de juros diária aplicada. | - | | `annual_rate` * | number | Taxa de juros anual aplicada. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | |------------|--------|------------------------------------------------------------|-----------------| | `amount` * | number | Valor percentual da taxa. | - | | `fee_amount` * | number | Valor monetário correspondente à taxa. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Objeto Response installments | Campo | Tipo | Descrição | |----------------------------|----------|--------------------------------------------------------| | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Cadastro de Operação de Debênture URL: /documentation/escrituracao/emissao-debentures/cadastro-operacao Este endpoint cria uma operação de Debênture completa em uma única requisição. :::info O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados. ::: --- ## **Request** ENDPOINT /debenture/create_operation MÉTODO POST O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo. Payload com os campos obrigatórios ```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 } ] } } ``` Payload completo (com partes relacionadas) ```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** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------- | ---------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Chave única do tenant. | - | | `issuer_key` * | string | Chave única do emissor (previamente cadastrado). | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `investors` * | array | Lista de investidores envolvidos. | **Objeto investors** | | `financial` * | object | Dados financeiros já calculados da operação. | **Objeto financial** | | `contract_number` | string | Número do contrato. | - | | `related_party_list` | array | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** | ### Objeto investors | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Chave única do investidor (previamente cadastrado). | | `bank_account` * | object | Conta bancária do investidor (**Objeto bank_account**). | | `subscription_percentage` | number | Percentual de subscrição. | | `subscription_quantity` | number | Quantidade subscrita. | ### Objeto bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`). | ### Objeto financial | Campo | Tipo | Descrição | | --------------------------- | ------- | -------------------------------------------------- | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `interest_type` * | string | Tipo de juros. | | `issue_amount` | number | Valor total emitido. | | `issue_quantity` | integer | Quantidade de unidades emitidas. | | `unit_price` | number | Preço unitário da emissão. | | `released_amount` | number | Valor líquido liberado. | | `cet` / `annual_cet` | number | Custo Efetivo Total (mensal e anual), em percentual. | | `number_of_installments` * | integer | Número de parcelas. | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | | `fine_delay_rate` | object | Taxa de multa por atraso. | | `contract_fine_rate` | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | | `installments` | array | Lista de parcelas já calculadas. | ### Objeto related_party Cada item de `related_party_list` representa uma parte envolvida na operação. | Campo | Tipo | Descrição | | ----------------- | ------- | ------------------------------------------------------------- | | `person_type` * | string | Tipo de pessoa (`natural` para PF, `legal` para PJ). | | `name` * | string | Nome da parte relacionada. | | `document_number` * | string | CPF (PF) ou CNPJ (PJ). | | `role_type` * | string | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** | | `street` * | string | Logradouro. | | `number` * | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `postal_code` * | string | CEP (formato "00000-000"). | | `city` * | string | Cidade. | | `state` * | string | UF (2 letras). | | `complement` | string | Complemento do endereço. | | `is_pep` | boolean | (PF) Indica se é Pessoa Politicamente Exposta. | | `marital_status` | string | (PF) Estado civil. | | `property_system` | string | (PF) Regime de bens. | | `birthdate` | string | (PF) Data de nascimento. | | `mother_name` | string | (PF) Nome da mãe. | | `occupation` | string | (PF) Ocupação. | | `trading_name` | string | (PJ) Nome fantasia. | | `cnae_code` | string | (PJ) Código CNAE (formato "00.00-0-00"). | | `company_type` | string | (PJ) Tipo de empresa. | | `foundation_date` | string | (PJ) Data de fundação. | :::warning Atenção Os campos obrigatórios variam conforme o `person_type`: - **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório. - **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios. ::: ### Enumeradores role_type | Enum | Descrição | |------|-----------| | `issuer` | Emissor. | | `investor` | Investidor. | | `cosigner` | Coobrigado. | | `fiduciary_debtor` | Devedor fiduciante. | | `solidary_debtor` | Devedor solidário. | | `guarantor` | Avalista. | | `bonafide_depositary` | Fiel depositário. | | `intervening_guarantor` | Interveniente garantidor. | | `intervening_consentor` | Interveniente anuente. | | `intervening_discharger` | Interveniente quitante. | | `assignor` | Cedente. | | `endorser` | Endossante. | | `consulting` | Consultoria. | | `fund_administrator` | Administrador do fundo. | | `fund_representative` | Representante do fundo. | | `company_representative` | Representante da empresa. | | `attestant` | Anuente / testemunha. | | `debtor` | Devedor. | | `bestowal` | Outorgante. | | `manager` | Gestor. | :::tip Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Envio de garantia** desta seção. ::: ### Enumeradores signature_method | Enum | Descrição | |------|-----------| | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | ## **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": { ... } } ``` A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado. --- # Envio de Documento URL: /documentation/escrituracao/emissao-debentures/envio-documento Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints — por exemplo, no `collateral_document_key` e nos `additional_documents` do [Envio de garantia](./envio-garantia.md). --- ## **Request** ENDPOINT /debenture/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |-------------------|--------|----------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | | `document_name` | string | Nome do documento. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|--------|-------------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento enviado (UUID v4). | 36 | --- --- # Enviar Documento Externo da Operação URL: /documentation/escrituracao/emissao-debentures/envio-documento-externo Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador. :::warning Aviso Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal. ::: --- ## Enviar Documento Assinado (POST) ### Request ENDPOINT /debenture/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|--------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "debenture" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|-----------------------------|-------------------------------------------------------------| | `contract_type` * | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Documento assinado em base64. | - | ### Enumeradores contract_type | Enum | Descrição | |---------------------|--------------------------------------------| | `debenture` | Escritura de emissão da debênture. | | `adhesion_term` | Termo de adesão da debênture. | | `sa_minute` | Ata de aprovação de emissão da debênture para empresa **SA**. | | `ltda_minute` | Ata de aprovação de emissão da debênture para empresa **LTDA**. | | `cop_minute` | Ata de aprovação de emissão da debênture para **Cooperativa**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Envio de Garantia na Operação URL: /documentation/escrituracao/emissao-debentures/envio-garantia Este endpoint permite a **adição de garantias (collateral)** a uma operação de Debênture. A garantia é submetida para assinatura junto com os documentos da operação. Cada tipo de garantia (`collateral_type`) possui suas próprias regras de documentos obrigatórios, listadas abaixo. :::info Origem do `document_key` Os campos `collateral_document_key` e `document_key` (em `additional_documents`) referenciam documentos previamente enviados. Cada chave é obtida no endpoint [Envio de documento](./envio-documento.md) (`POST /debenture/upload`), que recebe o arquivo em Base64 e retorna o `document_key` correspondente. ::: --- ## **Request** ENDPOINT /debenture/operation/ OPERATION-KEY /collateral MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- ## Tipos de garantia :::warning Documentos marcados como **obrigatórios** são exigidos para o respectivo tipo de garantia. ::: ### Alienação fiduciária de imóvel (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `property_appraisal_report` | Laudo de avaliação do imóvel. | Sim | | `property_registration_updated` | Matrícula atualizada. | Sim | | `property_full_content_certificate` | Certidão de inteiro teor da matrícula. | Sim | | `property_insurance_policy` | Apólice de seguro (se exigível no contrato). | - | | `others` | Outros documentos. | - | ### Alienação fiduciária de veículo (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `vehicle_appraisal_report` | Laudo de avaliação do veículo ou Tabela FIPE. | Sim | | `vehicle_inspection_report` | Laudo de vistoria. | Sim | | `vehicle_crv_certificate` | CRLV atualizado. | Sim | | `others` | Outros documentos. | - | ### Alienação fiduciária de aeronave (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `aircraft_certificate_anac` | Certificado de matrícula - ANAC. | Sim | | `aircraft_rab_consult` | Consulta no Registro Aeronáutico Brasileiro (RAB). | Sim | | `aircraft_insurance_policy` | Apólice de seguro - beneficiário o fundo. | Sim | | `aircraft_appraisal_report` | Laudo de avaliação da aeronave. | Sim | | `others` | Outros documentos. | - | ### Alienação fiduciária de equipamentos/produtos/estoque (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `equipment_purchase_invoice` | Nota fiscal de compra. | Sim | | `equipment_appraisal_report` | Laudo de avaliação de equipamentos. | Sim | | `equipment_insurance_policy` | Apólice de seguro de equipamentos (se exigível). | - | | `fiduciary_depositary_declaration` | Declaração de fiel depositário. | - | | `others` | Outros documentos. | - | ### Alienação fiduciária de obras de arte (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `artwork_appraisal_report` | Laudo de avaliação de obras de arte. | Sim | | `artwork_storage_certificate` | Certificado de adequação do local de armazenamento. | Sim | | `artwork_insurance_policy` | Apólice de seguro (se exigível). | - | | `others` | Outros documentos. | - | ### Alienação fiduciária de títulos e valores mobiliários (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `securities_negotiation_block` | Bloqueio para negociação junto ao custodiante. | Sim | | `securities_registration_gravame` | Registro do gravame. | - | | `others` | Outros documentos. | - | ### Alienação fiduciária / penhor de ações e cotas (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `share_registration_book` | Livro de registro de ações nominativas com anotação do gravame. | Sim | | `others` | Outros documentos. | - | ### Hipoteca de imóveis (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `property_appraisal_report` | Laudo de avaliação do imóvel. | Sim | | `property_registration` | Registro de propriedade atualizado. | Sim | | `property_full_content_certificate` | Certidão de inteiro teor da matrícula. | Sim | | `property_insurance_policy` | Apólice de seguro (se exigível no contrato). | - | | `others` | Outros documentos. | - | ### Hipoteca de embarcações (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `ship_registration` | Registro de propriedade da embarcação atualizado. | Sim | | `ship_appraisal_report` | Laudo de avaliação da embarcação. | Sim | | `ship_insurance_policy` | Apólice de seguro da embarcação (se exigível). | - | | `others` | Outros documentos. | - | ### 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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `guarantor_civil_status_declaration` | Declaração de estado civil do avalista. | Sim | | `guarantor_personal_document` | Documento pessoal do avalista. | - | | `guarantor_income_tax_declaration` | Declaração de imposto de renda do avalista. | - | | `others` | Outros documentos. | - | ### Fiança (fiador) (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `surety_civil_status_declaration` | Declaração de estado civil do fiador. | Sim | | `surety_personal_document` | Documento pessoal do fiador. | Sim | | `surety_income_tax_declaration` | Declaração de imposto de renda do fiador. | Sim | | `others` | Outros documentos. | - | ### Seguro (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `insurance_policy_endorsed` | Apólice de seguro endossada. | Sim | | `insurance_policy_with_expiration_and_renewal` | Apólice de seguro com vigência e renovação. | Sim | | `others` | Outros documentos. | - | ### Monitoramento de garantias (`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" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `guarantee_contract` | Contrato de garantia. | Sim | | `guarantee_agent_contract` | Contrato de agente de garantia. | Sim | | `others` | Outros documentos. | - | --- ## Request Body Params | Campo | Tipo | Descrição | Obrigatório | |-------|------|-----------|-------------| | `collateral_document_key` * | string | Chave do documento do instrumento de garantia. | Sim | | `collateral_type` * | string | Tipo da garantia. | **[Enumeradores collateral_type](#enumeradores-collateral_type)** | | `additional_documents` | array | Documentos adicionais da garantia. | - | ### additional_documents | Campo | Tipo | Descrição | Obrigatório | |-------|------|-----------|-------------| | `document_key` * | string | Chave do documento. | Sim | | `document_type` * | string | Tipo do documento. | Sim | ### Enumeradores collateral_type | Enum | Descrição | |------|-----------| | `fiduciary_alienation_property` | Alienação fiduciária de imóvel. | | `fiduciary_alienation_vehicle` | Alienação fiduciária de veículo. | | `fiduciary_alienation_aircraft` | Alienação fiduciária de aeronave. | | `fiduciary_alienation_equipment` | Alienação fiduciária de equipamentos/produtos/estoque. | | `fiduciary_alienation_artwork` | Alienação fiduciária de obras de arte. | | `fiduciary_alienation_securities` | Alienação fiduciária de títulos e valores mobiliários. | | `fiduciary_assignment_shares` | Alienação fiduciária / penhor de ações e cotas. | | `mortgage_property` | Hipoteca de imóveis. | | `mortgage_ship` | Hipoteca de embarcações. | | `guarantor` | Aval. | | `surety` | Fiança (fiador). | | `insurance` | Seguro. | | `monitoring_guarantee` | Monitoramento de garantias. | | `bank_surety` | Fiança bancária. | | `fiduciary_assignment_credit_rights` | Cessão fiduciária de direitos creditórios. | | `card_receivables` | Recebíveis de cartão. | | `stock_guarantee` | Garantia de estoque. | | `others` | Outras garantias. | ## Response O corpo da resposta é um JSON completo da operação atualizada, com a nova garantia em `collateral_list`. --- --- # Alteração de Cadastro do Emissor URL: /documentation/escrituracao/homologacao-emissor/alteracao-cadastro/ Para realizar alterações no cadastro do Emissor, é necessário que seu status seja definido para "in_filling", isto irá habilitar novamente todos os endpoints de inclusão/remoção. Após realizadas as modificações, o cadastro deve ser novamente enviado para análise com o status "in_analysis". --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "issuer_status": "in_filling" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | | ------------------ | ------ | ---------------------------------------------------- | ------------ | | `issuer_status`* | string | Novo status do emissor. Valor aceito:`in_filling`. | Sim | ## Response A resposta é um json completo atualizado do emissor. --- # Cadastro de Grupos de Assinantes do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor Este endpoint permite o cadastro de grupos de assinantes associados a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- | | `minimum_required_signers` * | integer | Número mínimo de assinantes necessários para validar o grupo. | - | | `signers` * | array | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** | ### Objeto Signer | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Nome completo do assinante. | 255 | | `document_number` * | string | CPF do assinante (formatação "XXX.XXX.XXX-XX"). | 11 | | `email` * | string | Endereço de email do assinante. | 1023 | | `phone_number`* | string | Número de telefone do assinante (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20 | | `is_group_mandatory` * | boolean | Indica se o assinante é obrigatório ou opcional dentro do grupo. | - | ## 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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- | | `signer_group_key` | string | Identificador único do grupo de assinantes (UUID v4). | 36 | | `minimum_required_signers` | integer | Número mínimo de assinantes necessários no grupo. | - | | `signers` * | array | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** | --- # Remoção de Grupos de Assinantes do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao Este endpoint permite a remoção de grupos de assinantes associados a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group/ SIGNER-GROUP-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|----------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `SIGNER-GROUP-KEY` | string | Chave única do grupo de assinantes a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro Básico do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico Este endpoint permite cadastrar as informações básicas de um emissor. ## Request ENDPOINT /issuer_management/issuer MÉTODO 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 | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- | | `name` * | string | Nome completo da empresa. | 255 | | `document_number` * | string | CNPJ da empresa (formato "XX.XXX.XXX/XXXX-XX"). | 14 | | `trading_name`* | string | Nome fantasia da empresa. | 1023 | | `cnae_code`* | string | Código CNAE da empresa (formato "XX.XX-X-XX"). | 7 | | `company_type`* | string | Tipo da empresa. | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date`* | string | Data de fundação da empresa (formato "YYYY-MM-DD"). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address) | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `is_in_national_financial_system` | boolean | Indicador se o cedente é integrante do SFN. | - | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` * | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (formato "XXXXX-XXX"). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores company_type | Enum | Description | | -------- | ------------------ | | `ltda` | Limitada | | `sa` | Sociedade Anônima | | `cop` | Cooperativa | ## 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 | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------------- | ------ | ----------------------------------- | -------------------------------------------------------------- | | `issuer_key` | string | Chave única do emissor (UUID). | 36 | | `name` | string | Nome completo do emissor. | 255 | | `document_number` | string | CNPJ do emissor. | 14 | | `status` | string | Status do emissor. | - | | `person_type` | string | Tipo de pessoa | **[Enumeradores person_type](#enumeradores-person_type)** | | `trading_name` | string | Nome fantasia do emissor. | 1023 | | `cnae_code` | string | Código CNAE do emissor. | 7 | | `company_type` | string | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date` | string | Data de fundação do emissor. | - | | `address` | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `registration_datetime` | string | Data e hora de registro do emissor. | - | | `expiration_date` | string | Data de expiração do emissor. | - | | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `is_in_national_financial_system` | boolean | Indicador se o cedente é integrante do SFN. | - | ### Enumeradores person_type | Enum | Description | | ----------- | ---------------- | | `legal` | Pessoa Jurídica | | `natural` | Pessoa Física | :::warning Aviso Ao cadastrar um emissor é reservada uma conta interna que será aberta somente se uma operação for concretizada. ::: ### Objeto payment_bank_account | Campo | Tipo | Descrição | Caracteres Máx. | | -------------------- | ------ | --------------------------- | ---------------- | | `account_digit` * | string | Dígito da conta bancária. | - | | `account_branch` * | string | Agência bancária. | - | | `account_number` * | string | Número da conta bancária. | - | --- # Cadastro de Conta Bancária do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor Este endpoint permite o cadastro de conta bancária associada a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (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 | Campo | Tipo | Descrição | Máximo de Caracteres | | -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. Deve conter apenas dígitos. | 20 | | `account_digit` * | string | Dígito verificador da conta. Deve conter um único dígito. | 1 | | `account_branch` * | string | Número da agência bancária. Deve conter apenas dígitos. | 6 | | `financial_institution_code_number`* | string | Código da instituição financeira (3 dígitos). | 3 | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira (8 dígitos). | 8 | | `account_type` * | string | Tipo da conta bancária. | **[Enumeradores account_type](#enumeradores-account_type)** | ### Enumeradores account_type | Enum | Description | | ------------ | ------------------ | | `checking` | Conta corrente | | `savings` | Conta Poupança | | `salary` | Conta Salário | | `payment` | Conta de Pagamento | ## 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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `bank_account_key` | string | Identificador único da conta bancária cadastrada (UUID v4). | 36 | | `account_number` | string | Número da conta bancária. | 20 | | `account_digit` | string | Dígito verificador da conta bancária. | 1 | | `account_branch` | string | Número da agência bancária. | 6 | | `financial_institution_code_number` | string | Código da instituição financeira. | 3 | | `financial_institution_ispb` | string | Código ISPB da instituição financeira. | 8 | | `account_type` | string | Tipo da conta bancária. | **[Enumeradores account_type](#enumeradores-account_type)** | --- # Definição de Conta Bancária Principal do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal Este endpoint promove uma conta bancária existente do emissor a conta principal (`is_default: true`). A conta anteriormente marcada como principal passa automaticamente a `is_default: false`. --- ## Trocando a conta bancária principal do emissor O emissor pode ter várias contas bancárias cadastradas, e apenas uma é marcada como principal. Para corrigir uma conta principal com dados incorretos (dígito, agência, ISPB), use o fluxo abaixo. :::warning Pré-requisito O emissor precisa estar no status `in_filling`. Após esse status, a conta principal não pode ser alterada — comportamento intencional, dado que a conta principal é referenciada em operações financeiras. ::: ### Fluxo de troca (3 chamadas) 1. **POST** `.../bank_account` → cria a nova conta (correta). 2. **POST** `.../bank_account/{key}/set_default` → promove a nova conta a principal. 3. **DELETE** `.../bank_account/{old_key}` → remove a conta antiga. A mesma restrição de ordem se aplica: como não é permitido deletar a conta principal, a promoção precisa vir antes da remoção. Tentar inverter retorna `HTTP 400 / ISS0000012`. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY /set_default MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|--------------------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `BANK-ACCOUNT-KEY` | string | Chave única da conta bancária que será promovida a principal (UUID v4). | 36 | ### Request Body Nenhum conteúdo é enviado no corpo da requisição. --- ## Response STATUS 204 Conta promovida a principal. Nenhum conteúdo é retornado no corpo da resposta. --- ## Erros | HTTP | Código | Cenário | |------|--------------|------------------------------------------------------------------------| | 400 | `ISS0000011` | Emissor não está em `in_filling`. | | 403 | `ISS000011` | Tenant não tem acesso a esse emissor. | | 404 | `ISS000005` | `bank_account_key` não encontrado para esse emissor. | | 404 | `ISS000009` | `issuer_key` não encontrado. | --- # Remoção de Conta Bancária do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao Este endpoint permite a remoção de conta bancária associada a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `BANK-ACCOUNT-KEY` | string | Chave única da conta bancária a ser removida (UUID v4).| 36 | --- ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- ## Observações - Não é permitido remover a conta marcada como principal (`is_default: true`). A tentativa retorna `HTTP 400 / ISS0000012`. Para trocar a conta principal, veja o fluxo completo em [Definição de conta bancária principal](./conta-bancaria-emissor-principal.md). - Alterações em conta principal só são permitidas com o emissor em `in_filling`. Fora desse status, a operação retorna `HTTP 400 / ISS0000011`. --- --- # Envio de Documentos do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor Este endpoint permite o envio de documentos associados a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "proof_of_address" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ------------------------------------------------------- | ---------------------------------------------------------------- | | `document_base64` * | string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | ### Enumeradores document_type | Enum | Description | | ------------------------------- | ---------------------------------- | | `proof_of_address` | Comprovante de Endereço | | `letter_of_attorney` | Procuração | | `company_statute` * | Contrato ou Estatuto Social | | `commercial_board_certificate` | Certificado da Junta Comercial | | `board_election_record` | Ata de Eleição da Diretoria | | `manager_declaration` | Declaração do Gestor | | `financial_statement` | Balanço Financeiro | | `credit_report` | Relatório de Crédito | | `manager_statement` | Declaração do Administrador | | `compliance_statement` | Declaração de Conformidade | | `cnpj_card` | Cartão CNPJ | | `additional_document` | Documento Adicional | :::warning Atenção O **company_statute** é obrigatório para todos os cadastros. ::: ## Response STATUS 201 Response Body **Cenário 1: Validação Automática (Sucesso no OCR)** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_address", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **Significado**: O documento foi processado e validado automaticamente pelo nosso OCR. **Cenário 2: Verificação Manual Necessária** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnpj_card", "ocr_key": null } ``` **Significado**: O documento não pôde ser validado automaticamente pelo OCR e foi encaminhado para nossa fila de verificação manual. :::warning Atenção A resposta para requisições bem-sucedidas (sucesso no envio) apresenta dois comportamentos distintos, dependendo do resultado da validação automática (OCR). ::: ### Response Body Params | Field | Type | Description | Max Length | | ----------------- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------- | | `document_key` | string | Identificador único do documento enviado (UUID v4). | 36 | | `document_type` | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- # Remoção de Documentos do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao Este endpoint permite a remoção de documentos enviados para o cadastro do emissor. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------|--------|------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Envio de Documentos do Representante do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor Este endpoint permite o envio de documentos associados a um representante de um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | Chave única do representante do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------| | `document_base64` *| string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. Valores aceitos: | **[Enumeradores document_type](#enumeradores-document_type)** | ### Enumeradores document_type | Enum | Description | | ------------------------------- | ---------------------------------- | | `cnh` | Carteira Nacional de Habilitação | | `cnh_front` | Frente da CNH | | `cnh_back` | Verso da CNH | | `cnh_digital` | CNH Digital | | `rg_front` | Frente do RG | | `rg_back` | Verso do RG | | `proof_of_address` | Comprovante de Endereço | | `letter_of_attorney` | Procuração | | `passport` | Passaporte | | `national_registry_of_foreigners`| Registro Nacional de Estrangeiros | :::warning Atenção É obrigatório para todos os cadastros pelo menos um documento identificador (cnh, rg, passport ou national_registry_of_foreigners) e caso o tipo do representante seja **attorney**, é necessário também uma procuração (letter_of_attorney). ::: ## Response STATUS 201 Response Body **Cenário 1: Validação Automática (Sucesso no OCR)** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **Significado**: O documento foi processado e validado automaticamente pelo nosso OCR. **Cenário 2: Verificação Manual Necessária** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnh", "ocr_key": null } ``` **Significado**: O documento não pôde ser validado automaticamente pelo OCR e foi encaminhado para nossa fila de verificação manual. :::warning Atenção A resposta para requisições bem-sucedidas (sucesso no envio) apresenta dois comportamentos distintos, dependendo do resultado da validação automática (OCR). ::: ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |------------------|----------|-----------------------------------------------------|-----------------------| | `document_key` | string | Identificador único do documento enviado (UUID v4). | 36 | | `document_type` | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- # Remoção de Documentos do Representante do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao Este endpoint permite a remoção de documentos associados a um representante de um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | Chave única do representante do emissor (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro de Informações de Contato do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor Este endpoint permite o cadastro de informações de contato associadas a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (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 | Campo | Tipo | Descrição | Máximo de Caracteres | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Nome completo do contato. | 255 | | `document_number` * | string | Número do documento do contato (formato CPF, formato "XXX.XXX.XXX-XX"). | 14 | | `email`* | string | Endereço de email do contato. | 1023 | | `phone_number`* | string | Número de telefone do contato (formatação completa: código do país, DDD e número. Exemplo: +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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ---------------------------------- | ------ | --------------------------------------------------------------------- | --------------------- | | `issuer_contact_information_key` | string | Identificador único da informação de contato cadastrada (UUID v4). | 36 | | `name` | string | Nome completo do contato. | 255 | | `document_number` | string | Número do documento do contato (CPF). | 11 | | `email` | string | Endereço de email do contato. | 1023 | | `phone_number` | string | Número de telefone do contato. | 20 | --- # Definição de Contato Principal do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal Este endpoint promove um contato existente do emissor a contato principal (`is_default: true`). O contato anteriormente marcado como principal passa automaticamente a `is_default: false`. --- ## Trocando o contato principal do emissor O emissor pode ter múltiplos contatos cadastrados, mas apenas um é marcado como principal. Caso o contato principal tenha sido cadastrado com um dado incorreto (typo no e-mail, dígito errado no telefone), use o fluxo abaixo para substituí-lo. :::warning Pré-requisito O emissor precisa estar no status `in_filling`. Após o emissor sair desse status, alterações em contato/conta principal não são permitidas — o endpoint retornará `HTTP 400 / ISS0000011`. ::: ### Fluxo de troca (3 chamadas) 1. **POST** `.../issuer_contact_information` → cria o novo contato (correto). 2. **POST** `.../issuer_contact_information/{key}/set_default` → promove o novo contato a principal. 3. **DELETE** `.../issuer_contact_information/{old_key}` → remove o contato antigo (com o typo). A ordem importa: como não é permitido deletar um contato marcado como principal, é obrigatório promover o novo contato antes de deletar o antigo. Tentar inverter retorna `HTTP 400 / ISS0000013`. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY /set_default MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------------------------|--------|-----------------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-CONTACT-INFORMATION-KEY` | string | Chave única do contato que será promovido a principal (UUID v4).| 36 | ### Request Body Nenhum conteúdo é enviado no corpo da requisição. --- ## Response STATUS 204 Contato promovido a principal. Nenhum conteúdo é retornado no corpo da resposta. --- ## Erros | HTTP | Código | Cenário | |------|--------------|------------------------------------------------------------------------| | 400 | `ISS0000011` | Emissor não está em `in_filling`. | | 403 | `ISS000011` | Tenant não tem acesso a esse emissor. | | 404 | `ISS000008` | `issuer_contact_information_key` não encontrado para esse emissor. | | 404 | `ISS000009` | `issuer_key` não encontrado. | --- # Remoção de Informações de Contato do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao Este endpoint a remoção de informações de contato associadas a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------------------------|--------|-----------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-CONTACT-INFORMATION-KEY` | string | Chave única da informação de contato a ser removida (UUID v4).| 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- ## Observações - Não é permitido remover o contato marcado como principal (`is_default: true`). A tentativa retorna `HTTP 400 / ISS0000013`. Para trocar o contato principal, veja o fluxo completo em [Definição de contato principal](./informacao-contato-emissor-principal.md). - Alterações em contato principal só são permitidas com o emissor em `in_filling`. Fora desse status, a operação retorna `HTTP 400 / ISS0000011`. --- # Cadastro de Representantes do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor Este endpoint permite o cadastro de representantes associados a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ---------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | `name` * | string | Nome completo do representante do emissor. | 255 | | `document_number` * | string | Número do documento (CPF, no formato "XXX.XXX.XXX-XX"). | 11 | | `birthdate` | string | Data de nascimento do representante no formato ISO 8601 (YYYY-MM-DD). | - | | `document_identification_number` | string | Número do documento de identificação. | 255 | | `marital_status` | string | Estado civil do representante. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system` | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `mother_name` | string | Nome completo da mãe do representante. | 1023 | | `father_name` | string | Nome completo do pai do representante. | 1023 | | `occupation` | string | Ocupação ou profissão do representante. | 255 | | `is_pep` | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `related_party_type` * | enumerador | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (formato "XXXXX-XXX"). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores marital_status | Enum | Description | | ---------------- | ------------------ | | `single` | Solteiro(a) | | `married` | Casado(a) | | `widower` | Viúvo(a) | | `separated` | Separado(a) | | `stable_union` | em União Estável | | `divorced` | Divorciado(a) | ### Enumeradores property_system | Enum | Description | | --------------------------------------- | --------------------------------- | | `total_communion_of_goods` | Comunhão Total de Bens | | `partial_communion_of_goods` | Comunhão Parcial de Bens | | `total_separation_of_goods` | Separação Total de Bens | | `final_participation_of_acquisitions` | Participação Final nos Aquestos | | `compulsory_separation_of_goods` | Separação Compulsória de Bens | ### Related Party Type | Enumerador | Descrição | | ----------------------- | ------------- | | **president** | Presidente | | **partner** | Sócio | | **administrator** | Administrador | | **director** | Diretor | | **manager** | Gestor | | **attorney** | Procurador | --- ## 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 | Campo | Tipo | Descrição | Máximo de Caracteres | | --------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | `issuer_representative_key` | string | Identificador único do representante do emissor (UUID v4). | 36 | | `name` | string | Nome completo do representante do emissor. | 255 | | `document_number` | string | Número do documento do representante (formato "XXX.XXX.XXX-XX"). | 11 | | `document_identification_number` | string | Número do documento de identificação. | 255 | | `marital_status` | string | Estado civil do representante. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system` | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `birthdate` | string | Data de nascimento do representante. | - | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `mother_name` | string | Nome completo da mãe do representante. | 1023 | | `father_name` | string | Nome completo do pai do representante. | 1023 | | `occupation` | string | Ocupação ou profissão do representante. | 255 | | `is_pep` | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `issuer_representative_document_list` | array | Lista de documentos associados ao representante. | - | | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `related_party_type` * | enumerador | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | --- # Remoção de Representante do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao Este endpoint permite a remoção de representantes enviados para o cadastro do emissor. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|--------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | Chave única do representante a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Consulta de Emissor URL: /documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave Este endpoint permite consultar os detalhes completos de um emissor cadastrado no sistema, utilizando sua chave única. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ## Response RESPONSE STATUS 200 Response Body com status *in_filling* ```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 STATUS 200 Response Body com status *reproved* ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "reproved", "backoffice_analysis_status": "reproved", "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", "bank_account_list": [ { "bank_account_key": "b6546f3b-329a-4703-addd-ac2fb34a8eea", "account_number": "7567236", "account_digit": "9", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking", "is_default": true } ], "signer_group_list": [ { "minimum_required_signers": 1, "signers": [ { "name": "Jose Representante", "document_number": "037.208.830-94", "email": "037.208.830-94@yopmail.com", "is_group_mandatory": false } ] } ], "issuer_representative_list": [ { "name": "Jose Representante", "document_number": "037.208.830-94", "nationality": "BRA", "related_party_type": "partner", "issuer_representative_document_list": [] } ], "issuer_contact_information_list": [ { "name": "Fabrica Exemplo S.A.", "phone_number": "+5516282399722", "is_default": true, "email": "email@yopmail.com", "document_number": "96.146.194/0001-07" } ], "issuer_document_list": [], "issuer_analysis_list": [], "last_analysis": { "analysis_key": "a274106e-5dbe-4a87-8999-6e41020f09b9", "analysis_number": 3, "status": "reproved", "analysis_datetime": "2025-10-24 02:52:15.886432", "analysis_related_parties": [ { "analysis_related_party_key": "e634cbb5-6b6a-42b6-9348-7cb449f646ca", "name": "Jose Representante", "document_number": "037.208.830-94", "analysis_roles": [ { "related_party_type": "partner" } ], "documents": [ { "document_key": "2b8ab03b-3896-43e9-9e5a-5e3c461164ef", "status": "canceled", "document_type": "cnh", "observation": null }, { "document_key": "77f38757-4688-4027-a19a-b7066747b3b5", "status": "valid", "document_type": "cnh", "observation": null } ] } ], "documents": [ { "document_key": "0ced115e-c008-4fae-93cd-b78c3f7d384d", "document_type": "social_contract", "status": "valid", "observation": null } ], "annotations": [], "last_updated": "2025-10-24 02:52:20.169204", "analysis_origin_type": "nce_integration", "reproval_reason": "missing_related_parties", "reproval_details": "parte relacionada João Representante consta no contrato social mas não está cadastrado" }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` RESPONSE STATUS 200 Response Body com status *approved* ```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", "bank_account_list": [ { "bank_account_key": "b6546f3b-329a-4703-addd-ac2fb34a8eea", "account_number": "7567236", "account_digit": "9", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking", "is_default": true } ], "signer_group_list": [ { "minimum_required_signers": 1, "signers": [ { "name": "Jose Representante", "document_number": "037.208.830-94", "email": "037.208.830-94@yopmail.com", "is_group_mandatory": false } ] } ], "issuer_representative_list": [ { "name": "Jose Representante", "document_number": "037.208.830-94", "nationality": "BRA", "related_party_type": "partner", "issuer_representative_document_list": [] } ], "issuer_contact_information_list": [ { "name": "Fabrica Exemplo S.A.", "phone_number": "+5516282399722", "is_default": true, "email": "email@yopmail.com", "document_number": "96.146.194/0001-07" } ], "issuer_document_list": [], "issuer_analysis_list": [], "last_analysis": { "analysis_key": "a274106e-5dbe-4a87-8999-6e41020f09b9", "analysis_number": 3, "status": "approved", "analysis_datetime": "2025-10-24 02:52:15.886432", "analysis_related_parties": [ { "analysis_related_party_key": "e634cbb5-6b6a-42b6-9348-7cb449f646ca", "name": "Jose Representante", "document_number": "037.208.830-94", "analysis_roles": [ { "related_party_type": "partner" } ], "documents": [ { "document_key": "2b8ab03b-3896-43e9-9e5a-5e3c461164ef", "status": "canceled", "document_type": "cnh", "observation": null }, { "document_key": "77f38757-4688-4027-a19a-b7066747b3b5", "status": "valid", "document_type": "cnh", "observation": null } ] } ], "documents": [ { "document_key": "0ced115e-c008-4fae-93cd-b78c3f7d384d", "document_type": "social_contract", "status": "valid", "observation": null } ], "annotations": [], "last_updated": "2025-10-24 02:52:20.169204", "analysis_origin_type": "nce_integration", "reproval_reason": null, "reproval_details": null }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |--------|----------|--------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | Identificador único do emissor. | 36 | | `name` | string | Nome completo do emissor. | 255 | | `document_number` | string | Número do documento do emissor (CNPJ). | 14 | | `status` | string | Status do emissor | **[Enumeradores status](#enumeradores-status)** | | `backoffice_analysis_status`| string | Status de análise do backoffice. | - | | `person_type` | string | Tipo de pessoa (`legal` ou `natural`). | - | | `trading_name` | string | Nome fantasia do emissor. | 1023 | | `cnae_code` | string | Código CNAE do emissor. | 10 | | `company_type` | string | Tipo de empresa: ´sa´, ´ltda´, ´cop´, ´-´ | 50 | | `foundation_date` | string | Data de fundação do emissor. | - | | `signer_group_list` | array | Lista de grupos de assinantes associados ao emissor. | - | | `bank_account_list` | array | Lista de contas bancárias associadas ao emissor. | - | | `issuer_representative_list` | array | Lista de representantes do emissor. | - | | `issuer_contact_information_list` | array | Lista de informações de contato associadas ao emissor. | - | | `issuer_document_list` | array | Lista de documentos cadastrados para o emissor. | - | | `address` | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `is_in_national_financial_system` | boolean | Indicador se o cedente é integrante do SFN. | - | | `last_analysis` | object | Objeto de análise. | **[Definição de Análise](#definição-de-análise)**. | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` | string | Número do endereço. | 10 | | `postal_code` | string | CEP do endereço (somente números). | 8 | | `city` | string | Nome da cidade do endereço. | 255 | | `state` | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | ### Objeto payment_bank_account | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_digit` | string | Dígito da conta bancária. | - | | `account_branch` | string | Agência bancária. | - | | `account_number` | string | Número da conta bancária. | - | ### Definição de Análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_key` | string | Identificador da análise. | 36 | | `analysis_number` | integer | Número sequencial da análise. | - | | `status` | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. | | `analysis_related_parties` | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. | | `documents` | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | | `analysis_data` | object | Payload da request que originou a análise. | - | | `analysis_datetime` | string | Objeto date time da criação da análise. | - | | `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. | | `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - | --- ### Analysis Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_documents** | Pendente Documentos | | **sent_to_analysis** | Enviado para Análise | | **pending_internal_validation** | Em Validação de documentos | | **in_manual_analysis** | Em Análise Manual de Compliance | | **approved** | Aprovado | | **reproved** | Reprovado | --- ### Definição de Documentos | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` | string | Identificador do documento. | 36 | | `document_type` | string | Tipo do documento. | | | `status` | string | Status do documento. | | | `observation` | string | Observações enviadas. | - | --- ### Definição de Partes Relacionadas de análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_related_party_key` | string | Identificador da parte relacionada. | 36 | | `document_number` | string | Número de documento da parte relacionada. | 14 a 18 | | `name` | string | Nome da parte relacionada. | 1 a 255 | | `documents` | array | Documentos da anáise da parte relacionada. | | --- ### Analysis Reproval Reason | Enum | Description | |--------------|---------------| | **assignor_update** | Análise cancelada devido à atualização cadastral posterior | | **insuficient_documents** | Documentação mínima para comprovação de poderes não enviada | | **compliance_reproval** | Reprovação de vínculo por análise do time de compliance | | **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado | | **invalid_documents** | Documentação inválida/expirada | | **missing_related_parties** | Parte relacionada obrigatória não enviada | --- --- # Consulta de Emissores por filtros URL: /documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro Este endpoint permite consultar emissores cadastrados no sistema utilizando o número de documento (CNPJ) ou Nome. --- ## Request ENDPOINT /issuer_management/issuer MÉTODO GET ### Query Params | Campo | Tipo | Descrição | Obrigatório | |-------------------|----------|------------------------------------|-------------| | `document_number` | string | Número do documento do emissor. | Não | | `name` | string | Nome do emissor. | Não | | `page` | integer | Página atual da consulta. | Não | | `rows_per_page` | integer | Número de registros por página. | Não | ## 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 | Campo | Tipo | Descrição | | |--------------|--------|---------------------|-----------------------------------------------------------------| | `data` | list | Lista de resultados | **[Objeto Emissor Simplificado](#objeto-emissor-simplificado)** | | `pagination` | object | Dados de paginação | **[Objeto Paginação](#objeto-paginacao)** | ### Objeto Emissor Simplificado | Campo | Tipo | Descrição | Máximo de Caracteres | |-------------------|----------|-------------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | Identificador único do emissor (UUID v4). | 36 | | `name` | string | Nome completo do emissor. | 255 | | `document_number` | string | Número do documento do emissor (CNPJ). | 14 | | `status` | string | Status atual do emissor. | **[Enumeradores status](#enumeradores-status)** | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | ### Objeto Pagination | Campo | Tipo | Descrição | |-------------------|----------|------------------------------------------| | `current_page` | integer | Página atual da consulta. | | `next_page` | integer | Próxima página, caso exista. | | `rows_per_page` | integer | Número de registros por página. | | `total_pages` | integer | Número total de páginas. | | `total_rows` | integer | Número total de registros encontrados. | --- # Envio para Análise do Emissor URL: /documentation/escrituracao/homologacao-emissor/envio-analise/ Este endpoint permite alterar o status de um emissor para análise, enviando-o para o processo de validação. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "issuer_status": "in_analysis" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | | ----------------- | ------ | ------------------------------------------------------- | ------------ | | `issuer_status` | string | Novo status do emissor. Valor aceito: `in_analysis`. | Sim | ## Response A resposta é um json completo atualizado do emissor. --- # Introdução URL: /documentation/escrituracao/homologacao-emissor/inicio A parte de cadastro de Emissores é essencial para o início da emissão de Notas Comerciais. Nessa seção iremos explicar todo o fluxo, desde o envio das primeiras informações, até o envio para análise. Para ter acesso aos serviços discutidos nas próximas sessões, entre em contato com o time [suporte.dcm@qitech.com.br](mailto:suporte.dcm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox) quanto em ambiente de produção. ### Cadastro do Emissor Nessa etapa, deve-se enviar todas as informações tanto do Emissor quanto dos seus representantes, documentos, informações de contato, grupos de assinantes e contas bancárias. Uma vez que o envio das informações estiver concluído, o cadastro é enviado para análise do time de cadastro de cedentes e após aprovação este emissor estará apto a participar da emissão de Notas. Caso o cadastro já tenha sido feito na plataforma da QI CTVM de cadastro de cedentes, é possível reaproveitar esse cadastro de forma simples, utilizando o endpoint de solicitação de acesso ao cadastro. ### Atualização de Emissor Em caso de necessidade de atualização cadastral, deve-se enviar novamente todas as informações do Emissor com as modificações desejadas. Após envio, é gerada uma nova Análise para validação. Assim que esta nova Análise for aprovada, os novos dados cadastrais do Emissor são efetivamente alterados. --- # Solicitação de Acesso aos Dados do Emissor URL: /documentation/escrituracao/homologacao-emissor/solicitacao-acesso Clientes que cadastraram um emissor que já possui um **cadastro na homologação de cedente** precisam **solicitar acesso aos dados do emissor** para que possam emitir operações com esse emissor como parte no sistema de escrituração. --- ## **Solicitação de Acesso (POST)** ### **Request** ENDPOINT /issuer_management/issuer/data_access_request MÉTODO 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 | Campo | Tipo | Descrição | Máximo de Caracteres | |--------|----------|--------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | Identificador único do emissor. | 36 | | `name` | string | Nome completo do emissor. | 255 | | `document_number` | string | Número do documento do emissor (CNPJ). | 14 | | `status` | string | Status do emissor | **[Enumeradores status](#enumeradores-status)** | | `backoffice_analysis_status`| string | Status de análise do backoffice. | - | | `person_type` | string | Tipo de pessoa (`legal` ou `natural`). | - | | `trading_name` | string | Nome fantasia do emissor. | 1023 | | `cnae_code` | string | Código CNAE do emissor. | 10 | | `company_type` | string | Tipo de empresa Aceitos: ´sa´, ´ltda´, ´cop´ | 50 | | `foundation_date` | string | Data de fundação do emissor. | - | | `signer_group_list` | array | Lista de grupos de assinantes associados ao emissor. | - | | `bank_account_list` | array | Lista de contas bancárias associadas ao emissor. | - | | `issuer_representative_list` | array | Lista de representantes do emissor. | - | | `issuer_contact_information_list` | array | Lista de informações de contato associadas ao emissor. | - | | `issuer_document_list` | array | Lista de documentos cadastrados para o emissor. | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (somente números). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | ### Objeto payment_bank_account | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_digit` * | string | Dígito da conta bancária. | - | | `account_branch` * | string | Agência bancária. | - | | `account_number` * | string | Número da conta bancária. | - | --- # Alteraçao de Cadastro do Investidor URL: /documentation/escrituracao/homologacao-investidor/alteracao-cadastro/ Para realizar alterações no cadastro do Investidor, é necessário que seu status seja definido para "in_filling", isto irá habilitar novamente todos os endpoints de inclusão/remoção. Após realizadas as modificações, o cadastro deve ser novamente enviado para análise com o status "in_analysis". --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "investor_status": "in_filling" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |------------------|----------|-----------------------------------------------------|-------------| | `investor_status` | string | Novo status do investidor. Valor aceito: `in_filling`. | Sim | ## Response A resposta é um json completo atualizado do investidor. --- # Cadastro de Grupos de Assinantes do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor Este endpoint permite o cadastro de grupos de assinantes associados a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Chave única do investidor (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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- | | `minimum_required_signers` * | integer | Número mínimo de assinantes necessários para validar o grupo. | - | | `signers` * | array | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** | ### Objeto Signer | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Nome completo do assinante. | 255 | | `document_number` * | string | CPF do assinante (formato "XX.XXX.XXX/XXXX-XX"). | 11 | | `email` * | string | Endereço de email do assinante. | 1023 | | `phone_number`* | string | Número de telefone do assinante (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20 | | `is_group_mandatory` * | boolean | Indica se o assinante é obrigatório ou opcional dentro do grupo. | - | ## 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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- | | `signer_group_key` | string | Identificador único do grupo de assinantes (UUID v4). | 36 | | `minimum_required_signers` | integer | Número mínimo de assinantes necessários no grupo. | - | | `signers` * | array | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** | --- # Remoção de Grupos de Assinantes do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao Este endpoint permite a remoção de grupos de assinantes associados a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group/ SIGNER-GROUP-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|----------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `SIGNER-GROUP-KEY` | string | Chave única do grupo de assinantes a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro Básico do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico Este endpoint permite cadastrar as informações básicas de um investidor. ## Request ENDPOINT /investor_management/investor MÉTODO 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" } } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- | | `name` * | string | Nome completo da empresa. | 255 | | `document_number` * | string | CNPJ da empresa (formato "XX.XXX.XXX/XXXX-XX"). | 14 | | `trading_name`* | string | Nome fantasia da empresa. | 1023 | | `cnae_code`* | string | Código CNAE da empresa (formato "XXXXX-XXX"). | 7 | | `company_type`* | string | Tipo da empresa. | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date`* | string | Data de fundação da empresa (formato "YYYY-MM-DD"). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | -------------------------------------------- | ---------------- | | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` * | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (formatação "XXXXX-XXX"). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores company_type | Enum | Description | | -------- | ------------------ | | `ltda` | Limitada | | `sa` | Sociedade Anônima | | `cop` | Cooperativa | ## Response STATUS 201 Response Body ```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" } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------------- | ------ | -------------------------------------- | -------------------------------------------------------------- | | `investor_key` | string | Chave única do investidor (UUID). | 36 | | `name` | string | Nome completo do investidor. | 255 | | `document_number` | string | CNPJ do investidor. | 14 | | `status` | string | Status do investidor. | - | | `person_type` | string | Tipo de pessoa | **[Enumeradores person_type](#enumeradores-person_type)** | | `trading_name` | string | Nome fantasia do investidor. | 1023 | | `cnae_code` | string | Código CNAE do investidor. | 7 | | `company_type` | string | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date` | string | Data de fundação do investidor. | - | | `address` | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `registration_datetime` | string | Data e hora de registro do investidor. | - | | `expiration_date` | string | Data de expiração do investidor. | - | ### Enumeradores person_type | Enum | Description | | ----------- | ---------------- | | `legal` | Pessoa Jurídica | | `natural` | Pessoa Física | --- # Cadastro de Conta Bancária do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor Este endpoint permite o cadastro de conta bancária associada a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Chave única do investidor (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 | Campo | Tipo | Descrição | Máximo de Caracteres | | -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. Deve conter apenas dígitos. | 20 | | `account_digit` * | string | Dígito verificador da conta. Deve conter um único dígito. | 1 | | `account_branch` * | string | Número da agência bancária. Deve conter apenas dígitos. | 6 | | `financial_institution_code_number`* | string | Código da instituição financeira (3 dígitos). | 3 | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira (8 dígitos). | 8 | | `account_type` * | string | Tipo da conta bancária. | **[Enumeradores account_type](#enumeradores-account_type)** | ### Enumeradores account_type | Enum | Description | | ------------ | ------------------ | | `checking` | Conta corrente | | `savings` | Conta Poupança | | `salary` | Conta Salário | | `payment` | Conta de Pagamento | ## 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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `bank_account_key` | string | Identificador único da conta bancária cadastrada (UUID v4). | 36 | | `account_number` | string | Número da conta bancária. | 20 | | `account_digit` | string | Dígito verificador da conta bancária. | 1 | | `account_branch` | string | Número da agência bancária. | 6 | | `financial_institution_code_number` | string | Código da instituição financeira. | 3 | | `financial_institution_ispb` | string | Código ISPB da instituição financeira. | 8 | | `account_type` | string | Tipo da conta bancária. | **[Enumeradores account_type](#enumeradores-account_type)** | --- # Remoção de Conta Bancária do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao Este endpoint permite a remoção de conta bancária associada a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account/ BANK-ACCOUNT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `BANK-ACCOUNT-KEY` | string | Chave única da conta bancária a ser removida (UUID v4).| 36 | --- ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- --- # Envio de Documentos do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor Este endpoint permite o envio de documentos associados a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |---------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "proof_of_address" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------|----------|------------------------------------------------------------------------------------------|---------------------------------------------------------------| | `document_base64` *| string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | ### Enumeradores document_type | Enum | Description | |--------|-----------------------------| | `danfe` | DANFE | | `proof_of_address` | Comprovante de Endereço | | `letter_of_attorney` | Procuração | | `company_statute` | Contrato ou Estatuto Social | ## 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 | Identificador único do documento enviado (UUID v4). | 36 | | `document_type` | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- # Remoção de Documentos do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao Este endpoint permite a remoção de documentos enviados para o cadastro do investidor. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Envio de Documentos do Representante do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor Este endpoint permite o envio de documentos associados a um representante de um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | Chave única do representante do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------| | `document_base64` *| string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. Valores aceitos: | **[Enumeradores document_type](#enumeradores-document_type)** | ### Enumeradores document_type | Enum | Description | |--------|-------------------------| | `cnh` | CNH | | `cnh_front` | Frente da CNH | | `cnh_back` | Verso da CNH | | `cnh_digital` | PDF CNH DIGITAL | `rg_front` | Frente do RG | | `rg_back` | Verso do RG | | `danfe` | DANFE | | `proof_of_address` | Comprovante de Endereço | | `letter_of_attorney` | Procuração | ## 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 | Campo | Tipo | Descrição | Máximo de Caracteres | |------------------|----------|-----------------------------------------------------|-----------------------| | `document_key` | string | Identificador único do documento enviado (UUID v4). | 36 | | `document_type` | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- # Remoção de Documentos do Representante do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao Este endpoint permite a remoção de documentos associados a um representante de um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | Chave única do representante do investidor (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro de Informações de Contato do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor Este endpoint permite o cadastro de informações de contato associadas a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Chave única do investidor (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 | Campo | Tipo | Descrição | Máximo de Caracteres | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Nome completo do contato. | 255 | | `document_number` * | string | Número do documento do contato (formato CPF, "XX.XXX.XXX/XXXX-XX"). | 11 | | `email`* | string | Endereço de email do contato. | 1023 | | `phone_number`* | string | Número de telefone do contato (formatação completa: código do país, DDD e número. Exemplo: +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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------------ | ------ | --------------------------------------------------------------------- | --------------------- | | `investor_contact_information_key` | string | Identificador único da informação de contato cadastrada (UUID v4). | 36 | | `name` | string | Nome completo do contato. | 255 | | `document_number` | string | Número do documento do contato (CPF). | 11 | | `email` | string | Endereço de email do contato. | 1023 | | `phone_number` | string | Número de telefone do contato. | 20 | --- # Remoção de Informações de Contato do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao Este endpoint a remoção de informações de contato associadas a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information/ INVESTOR-CONTACT-INFORMATION-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------------------------|--------|-----------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `INVESTOR-CONTACT-INFORMATION-KEY` | string | Chave única da informação de contato a ser removida (UUID v4).| 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro de Representantes do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor Este endpoint permite o cadastro de representantes associados a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Chave única do investidor (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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ----------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | `name` * | string | Nome completo do representante do investidor. | 255 | | `document_number` * | string | Número do documento (CPF, formato "XX.XXX.XXX/XXXX-XX"). | 11 | | `birthdate`* | string | Data de nascimento do representante no formato ISO 8601 (YYYY-MM-DD). | - | | `document_identification_number`* | string | Número do documento de identificação. | 255 | | `marital_status`* | string | Estado civil do representante. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system`* | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `nationality`* | string | Nacionalidade do representante do investidor. | 255 | | `mother_name` | string | Nome completo da mãe do representante. | 1023 | | `father_name` | string | Nome completo do pai do representante. | 1023 | | `occupation`* | string | Ocupação ou profissão do representante. | 255 | | `is_pep`* | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (somente números). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores marital_status | Enum | Description | | ---------------- | ------------------ | | `single` | Solteiro(a) | | `married` | Casado(a) | | `widower` | Viúvo(a) | | `separated` | Separado(a) | | `stable_union` | em União Estável | | `divorced` | Divorciado(a) | ### Enumeradores property_system | Enum | Description | | --------------------------------------- | --------------------------------- | | `total_communion_of_goods` | Comunhão Total de Bens | | `partial_communion_of_goods` | Comunhão Parcial de Bens | | `total_separation_of_goods` | Separação Total de Bens | | `final_participation_of_acquisitions` | Participação Final nos Aquestos | | `compulsory_separation_of_goods` | Separação Compulsória de Bens | ## 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 | Campo | Tipo | Descrição | Máximo de Caracteres | | ----------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | `investor_representative_key` | string | Identificador único do representante do investidor (UUID v4). | 36 | | `name` | string | Nome completo do representante do investidor. | 255 | | `document_number` | string | Número do documento do representante (formato CPF). | 11 | | `document_identification_number` | string | Número do documento de identificação. | 255 | | `marital_status` | string | Estado civil do representante. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system` | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `birthdate` | string | Data de nascimento do representante. | - | | `nationality` | string | Nacionalidade do representante do investidor. | 255 | | `mother_name` | string | Nome completo da mãe do representante. | 1023 | | `father_name` | string | Nome completo do pai do representante. | 1023 | | `occupation` | string | Ocupação ou profissão do representante. | 255 | | `is_pep` | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `investor_representative_document_list` | array | Lista de documentos associados ao representante. | - | --- # Remoção de Representante do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao Este endpoint permite a remoção de representantes enviados para o cadastro do investidor. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|--------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | Chave única do representante a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Consulta de Investidor URL: /documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave Este endpoint permite consultar os detalhes completos de um investidor cadastrado no sistema, utilizando sua chave única. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (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 | Campo | Tipo | Descrição | Máximo de Caracteres | |--------|----------|--------------------------------------------------------|-----------------------| | `investor_key` | string | Identificador único do investidor. | 36 | | `name` | string | Nome completo do investidor. | 255 | | `document_number` | string | Número do documento do investidor (CNPJ). | 14 | | `status` | string | Status do investidor | **[Enumeradores status](#enumeradores-status)** | | `backoffice_analysis_status`| string | Status de análise do backoffice. | - | | `person_type` | string | Tipo de pessoa (`legal` ou `natural`). | - | | `trading_name` | string | Nome fantasia do investidor. | 1023 | | `cnae_code` | string | Código CNAE do investidor. | 7 | | `company_type` | string | Tipo de empresa Aceitos: ´sa´, ´ltda´, ´cop´ | 50 | | `foundation_date` | string | Data de fundação do investidor. | - | | `signer_group_list` | array | Lista de grupos de assinantes associados ao investidor. | - | | `bank_account_list` | array | Lista de contas bancárias associadas ao investidor. | - | | `investor_representative_list` | array | Lista de representantes do investidor. | - | | `investor_contact_information_list` | array | Lista de informações de contato associadas ao investidor. | - | | `investor_document_list` | array | Lista de documentos cadastrados para o investidor. | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)**| ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (somente números). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | --- # Consulta de Investidores por filtros URL: /documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro Este endpoint permite consultar investidores cadastrados no sistema utilizando o número de documento (CNPJ) ou Nome. --- ## Request ENDPOINT /investor_management/investor MÉTODO GET ### Query Params | Campo | Tipo | Descrição | Obrigatório | |-------------------|----------|------------------------------------|-------------| | `document_number` | string | Número do documento do investidor. | Não | | `name` | string | Nome do investidor. | Não | | `page` | integer | Página atual da consulta. | Não | | `rows_per_page` | integer | Número de registros por página. | Não | ## 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 | Campo | Tipo | Descrição | | |--------------|--------|---------------------|-----------------------------------------------------------------| | `data` | list | Lista de resultados | **[Objeto Investidor Simplificado](#objeto-investidor-simplificado)** | | `pagination` | object | Dados de paginação | **[Objeto Paginação](#objeto-paginacao)** | ### Objeto Investidor Simplificado | Campo | Tipo | Descrição | Máximo de Caracteres | |-------------------|----------|-------------------------------------------------------------|-------------------------------------------------| | `investor_key` | string | Identificador único do investidor (UUID v4). | 36 | | `name` | string | Nome completo do investidor. | 255 | | `document_number` | string | Número do documento do investidor (CNPJ). | 14 | | `status` | string | Status atual do investidor. | **[Enumeradores status](#enumeradores-status)** | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | ### Objeto Pagination | Campo | Tipo | Descrição | |-------------------|----------|------------------------------------------| | `current_page` | integer | Página atual da consulta. | | `next_page` | integer | Próxima página, caso exista. | | `rows_per_page` | integer | Número de registros por página. | | `total_pages` | integer | Número total de páginas. | | `total_rows` | integer | Número total de registros encontrados. | --- # Envio para Análise do Investidor URL: /documentation/escrituracao/homologacao-investidor/envio-analise/ Este endpoint permite alterar o status de um investidor para análise, enviando-o para o processo de validação. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "investor_status": "in_analysis" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |------------------|----------|-------------------------------------------------|-------------| | `investor_status` | string | Novo status do investidor. Valor aceito: `in_analysis`. | Sim | ## Response A resposta é um json completo atualizado do investidor. --- # Introdução URL: /documentation/escrituracao/homologacao-investidor/inicio A parte de cadastro de Investidores é essencial para o início da emissão de Notas Comerciais. Nessa seção iremos explicar todo o fluxo, desde o envio das primeiras informações, até o envio para análise. Para ter acesso aos serviços discutidos nas próximas sessões, entre em contato com o time [suporte.dcm@qitech.com.br](mailto:suporte.dcm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox) quanto em ambiente de produção. ### Cadastro do Investidor Nessa etapa, deve-se enviar todas as informações tanto do Investidor quanto dos seus representantes, documentos, informações de contato, grupos de assinantes e contas bancárias. Uma vez que o envio das informações estiver concluído, o cadastro é enviado para análise e após aprovação este investidor estará apto a participar da emissão de Notas. ### Atualização de Investidor Em caso de necessidade de atualização cadastral, deve-se enviar novamente todas as informações do Investidor com as modificações desejadas. Após envio, é gerada uma nova Análise para validação. Assim que esta nova Análise for aprovada, os novos dados cadastrais do Investidor são efetivamente alterados. --- # **Solicitação de Acesso aos Dados do Investidor** URL: /documentation/escrituracao/homologacao-investidor/solicitacao-acesso Clientes que cadastraram um investidor que já possui um **cadastro único** precisam **solicitar acesso aos dados do investidor** para que possam emitir operações com esse investidor como parte. Ao realizar essa solicitação, o **investidor receberá um e-mail com instruções para aprovar ou recusar o acesso**. --- ## **Solicitação de Acesso (POST)** ### **Request** ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |---------------|--------|-----------------------------------------------|-----------------| | `INVESTOR-KEY` * | string | Chave única do investidor (UUID v4). | 36 | --- ## **Request Body** Nenhum corpo de requisição é necessário. --- ## **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** | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------------------|----------|-------------------------------------------------------------|-----------------| | `data_access_request_key` * | string | Chave única da solicitação de acesso (UUID v4). | 36 | | `requested_at` * | string | Data e hora da solicitação (formato ISO 8601). | - | | `responded_at` | string | Data e hora da resposta à solicitação, se já respondida. | - | | `data_access_request_status` * | string | Status da solicitação. | **[Enumeradores data_access_request_status](#enumeradores-data_access_request_status)** | --- ## **Consulta do Status da Solicitação (GET)** Os clientes podem verificar se sua solicitação foi aprovada, recusada ou ainda está em análise. ## **Request** ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |---------------|--------|-----------------------------------------------|-----------------| | `INVESTOR-KEY` * | string | Chave única do investidor (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** | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------------------|----------|-------------------------------------------------------------|-----------------| | `data_access_request_key` * | string | Chave única da solicitação de acesso (UUID v4). | 36 | | `requested_at` * | string | Data e hora da solicitação (formato ISO 8601). | - | | `responded_at` | string | Data e hora da resposta à solicitação, se já respondida. | - | | `data_access_request_status` * | string | Status da solicitação. | **[Enumeradores data_access_request_status](#enumeradores-data_access_request_status)** | --- ## **Enumeradores data_access_request_status** | Enum | Descrição | |-------------|------------------------------------------------------| | `in_analysis` | A solicitação está em análise pelo investidor. | | `approved` | O acesso foi aprovado e o cliente pode visualizar os dados do investidor. | | `reproved` | A solicitação foi recusada e o cliente não poderá acessar os dados do investidor. | --- # Consulta de Comprovante de Transação URL: /documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao Este endpoint permite obter o comprovante (PDF + metadados) de uma das TEDs executadas pela QI Tech para uma integralização. Em um ciclo de integralização (pagamento do investidor → tarifas → desembolso) podem ser geradas múltiplas TEDs — você escolhe qual delas quer pelo parâmetro `transaction_type`. Quando houver mais de uma TED do mesmo tipo para a mesma integralização (por exemplo, vários `extraordinary_event_payment`), o endpoint retorna apenas a mais recente. Para listar todas, utilize **[Consulta de Transações da Integralização](./consulta-transacoes-integralizacao.md)**. --- ## Consulta de Comprovante (GET) ### Request ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transaction_receipt MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------|--------|--------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | ### Query Params | Campo | Tipo | Descrição | Obrigatório | |--------------------|--------|------------------------------------------------------------------------------------------|-------------| | `transaction_type` | string | Tipo da TED a ser consultada. **[Enumeradores transaction_type](#enumeradores-transaction_type)** | Sim | --- ### 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 | Campo | Tipo | Descrição | |----------------------|--------|----------------------------------------------------------------------------------------------------| | `transaction_key` | string | Chave única da TED no BaaS — mesmo valor retornado por `consulta-transacoes-integralizacao`. | | `transaction_amount` | number | Valor da TED conforme registrado pela QI Tech. | | `transaction_status` | string | Status da TED no BaaS (ex.: `settled`, `paid`). | | `pdf_encoded_string` | string | Comprovante bancário em base64. Decodifique para obter o PDF. | --- ### Enumeradores transaction_type | Enum | Descrição | |-------------------------------|----------------------------------------------------------------------------------------| | `disbursement` | TED de desembolso do valor líquido para a conta bancária do emissor. | | `bookkeeping_fee_internal` | TED para a QI CTVM referente à tarifa de escrituração interna. | | `bookkeeping_fee_external` | TED para a conta de escrituração externa do cliente. | | `structuring_fee` | TED para a conta de estruturação do cliente. | | `extraordinary_event_payment` | TED para um investidor referente a um evento extraordinário de liquidação. | --- ### Erros | HTTP | Código | Quando ocorre | |------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | 400 | `HTTPMissingParam` | Parâmetro `transaction_type` não foi informado. | | 400 | `HTTPInvalidParam` | `transaction_type` não corresponde a nenhum dos valores permitidos. | | 404 | `ACL000004` (`IntegralizationTransactionNotFound`) | Não existe TED do tipo informado para essa integralização, OU a integralização nunca foi liquidada (sem TEDs). | :::note O 404 com `ACL000004` é retornado de forma idêntica em todos os cenários (chave inexistente, integralização nunca liquidada, ou tipo de TED ausente) — por design, não diferenciamos os casos. Se precisar saber se a integralização existe, liste suas transações primeiro. ::: --- # Consulta de Conta de Liquidação URL: /documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao Este endpoint permite consultar os detalhes da conta de liquidação de um emissor — dados bancários (agência, conta, dígito), status e, quando a conta já está aberta, informações do titular e saldos. Enquanto a conta ainda não foi aberta no BaaS, o endpoint retorna apenas os dados básicos com `account_status: "pending"`. Após a abertura, a resposta inclui os campos adicionais do titular e de saldo. --- ## Consulta de Conta de Liquidação (GET) ### Request ENDPOINT /account_liquidation/issuer/ ISSUER-KEY 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 — conta aberta ```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 — conta pendente ```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 | Campo | Tipo | Descrição | |-------------------------|--------|---------------------------------------------------------------------------------------------| | `issuer_key` | string | Chave única do emissor. | | `tenant_key` | string | Chave única do cliente dono da conta. | | `bank_account_key` | string | Chave única da conta bancária no BaaS. | | `request_account_key` | string | Chave única da solicitação de abertura da conta. | | `account_key` | string | Chave única da conta no BaaS. Presente apenas quando a conta já foi aberta. | | `account_branch` | string | Agência da conta. | | `account_number` | string | Número da conta. | | `account_digit` | string | Dígito da conta. | | `account_status` | string | Status da conta. `pending` enquanto a abertura não foi concluída. | | `account_type` | string | Tipo da conta no BaaS. Presente apenas quando a conta já foi aberta. | | `account_documents` | array | Documentos associados à conta. Presente apenas quando a conta já foi aberta. | | `balance` | number | Saldo disponível da conta. Presente apenas quando a conta já foi aberta. | | `blocked_balance` | number | Saldo bloqueado da conta. Presente apenas quando a conta já foi aberta. | | `owner_document_number` | string | CPF/CNPJ do titular da conta. Presente apenas quando a conta já foi aberta. | | `owner_name` | string | Nome do titular da conta. Presente apenas quando a conta já foi aberta. | | `owner_person_key` | string | Chave única do titular no BaaS. Presente apenas quando a conta já foi aberta. | | `created_at` | string | Data de criação da conta. Presente apenas quando a conta já foi aberta. | --- ### Erros | HTTP | Código | Quando ocorre | |------|---------------------------------------------------------|-------------------------------------------------------------------------------| | 404 | `ACL000002` (`IssuerAccountLiquidationNotFound`) | Não existe conta de liquidação para o emissor informado. | | 400 | `ACL000003` (`IssuerAccountLiquidationNotBelongToTenant`) | A conta de liquidação do emissor não pertence ao cliente que fez a requisição. | --- # Consulta de Integralização por Chave URL: /documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao Este endpoint permite consultar os detalhes de um processo de integralização utilizando sua chave única. --- ## Consulta de Processo de Integralização (GET) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------------|--------|------------------------------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única da integralização (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 | Campo | Tipo | Descrição | |------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------| | `tenant_key` | string | Chave única do tenant associado à integralização. | | `integralization_key` | string | Chave única da integralização. | | `operation_key` | string | Chave única da operação associada. | | `operation_type` | string | Tipo da operação. Valores possíveis: `commercial_paper`. | | `contract_number` | string | Número do contrato associado à integralização. | | `issue_number` | integer | Número da emissão associada à integralização. | | `issue_series` | integer | Série da emissão associada à integralização. | | `issuer_key` | string | Chave única do emissor associado. | | `issuer_name` | string | Nome do emissor associado à integralização. | | `issuer_document_number` | string | Número do documento do emissor | | `issuer_bank_account` | object | Dados da conta bancária do emissor. | | `issuer_bank_account.account_type` | string | Tipo da conta bancária (`checking`, etc.). | | `issuer_bank_account.account_digit` | string | Dígito verificador da conta bancária. | | `issuer_bank_account.account_branch` | string | Agência bancária. | | `issuer_bank_account.account_number` | string | Número da conta bancária. | | `issuer_bank_account.financial_institution_ispb` | string | ISPB da instituição financeira. | | `issuer_bank_account.financial_institution_code_number` | string | Código da instituição financeira. | | `subscripted_quantity` | integer | Quantidade total de cotas subscritas. | | `subscripted_total_amount` | number | Valor total das cotas subscritas. | | `integralized_quantity` | integer | Quantidade total de cotas integralizadas. | | `issue_quantity` | integer | Quantidade total de cotas emitidas na operação. | | `integralization_status` | string | **[Enumeradores integralization_status](#enumeradores-integralization_status)** | | `subscription_list` | array | Lista de subscrições associadas à integralização. **[Objeto subscription](#objeto-subscription)** | ### Objeto subscription | Campo | Tipo | Descrição | |------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------------------------------------| | `subscription_key` | string | Chave única da subscrição. | | `investor_key` | string | Chave única do investidor associado à subscrição. | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Número do documento do investidor (CPF ou CNPJ). | | `investor_bank_account` | object | Dados bancários do investidor. | | `subscription_date` | string | Data da subscrição (formato: YYYY-MM-DD). | | `financial_base_date` | string | Data base financeira da subscrição (formato: YYYY-MM-DD). | | `subscripted_quantity` | integer | Quantidade de cotas subscritas. | | `unit_price` | number | Preço unitário das cotas. | | `expected_amount` | number | Valor total esperado da subscrição. | | `paid_amount` | number | Valor pago ja confrimado da subscrição. | | `subscription_note_template_key` | string | Chave do template da nota de subscrição. | | `subscription_note_document_key` | string | Chave do documento da nota de subscrição. | | `subscription_note_signature_status` | string | Status da assinatura da nota de subscrição. | | `subscription_payment_list` | array | Lista de pagamentos associados à subscrição. **[Objeto subscription_payment](#objeto-subscription_payment)]** | ### Objeto subscription_payment | Campo | Tipo | Descrição | |------------------------------------------------------------------------|------------|----------------------------------------------------------------------------------------| | `subscription_payment_key` | string | Chave única do pagamento da subscrição. | | `payment_receipt_document_key` | string | Chave do documento do comprovante de pagamento. | | `description` | string | Descrição do comprovante de pagamento. | | `amount` | number | Valor do pagamento registrado. | | `subscription_payment_status` | string | Status do pagamento. Valores possíveis: `waiting_confirmation`, `confirmed`, `denied`. | | `updated_at` | string | Data e hora da última atualização do pagamento (formato: ISO 8601). | ### Enumeradores integralization_status | Enum | Description | | ------------------------------- | ---------------------------------- | | `pending` | Pendente Subscrição. | | `finished` | Integralização finalizada. | | `canceled` | Integralização cancelada. | --- # Consulta de Transações da Integralização URL: /documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao Este endpoint retorna os metadados de todas as TEDs executadas pela QI Tech para uma integralização — sem o PDF. Útil para descobrir quantos comprovantes existem, em qual ordem foram executados e os respectivos `transaction_key`. Para obter o PDF de uma TED específica, use **[Consulta de Comprovante de Transação](./consulta-comprovante-transacao.md)**. A resposta vem em ordem cronológica (`created_at` ASC) e inclui todas as TEDs do ciclo (desembolso, tarifas e eventos extraordinários). Quando há múltiplas TEDs do mesmo tipo (por exemplo, vários `extraordinary_event_payment`), todas aparecem aqui — diferente do endpoint de comprovante, que retorna apenas a mais recente. --- ## Consulta de Transações (GET) ### Request ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transactions MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------|--------|--------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única da integralização (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 | Campo | Tipo | Descrição | |----------------------|--------|----------------------------------------------------------------------------------------------------------| | `transaction_key` | string | Chave única da TED no BaaS. | | `external_id` | string | `integralization_key` à qual a TED pertence. | | `transaction_amount` | number | Valor registrado pela QI Tech para a TED. Não use como fonte oficial para conciliação contábil. | | `transaction_type` | string | Tipo da TED. **[Enumeradores transaction_type](./consulta-comprovante-transacao.md#enumeradores-transaction_type)** | | `transaction_status` | string | Status atual da TED (ex.: `paid`, `settled`). | | `created_at` | string | Data e hora de criação do registro (ISO 8601). | --- # Introdução à Integralização de Cotas URL: /documentation/escrituracao/integralizacao-cotas/inicio Após a conclusão do processo de Emissão da Nota Comercial, a operação restará no status emitido (issued). Por padrão o processo de subscrição de cotas para integralização ocorre de forma automática após a assinatura do termo constitutivo. Ao consultar uma operação no estado emitida, estará disponível um campo chamado `integralization_key` pelo quando o processo de integralização poderá ser acompanhado. O processo de integralização consiste de - Subscrição de cotas - Assinatura do boletim de subscrição - Registro de Pagamento - Confirmação de Pagamento --- # Cadastro de Subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao Este endpoint permite registrar a intenção de um investidor em subscrever uma quantidade específica de cotas de uma integralização. --- ## Cadastro de Subscrição (POST) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ----------------------- | ------ | ------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | --- ### Request Body 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 | Campo | Tipo | Descrição | | ------------------------------------------------------------ | ------- | ------------------------------------------------------- | | `investor_key`* | string | Chave única do investidor (UUID v4). | | `investor_bank_account`* | object | Dados da conta bancária do investidor. | | `investor_bank_account.account_number`* | string | Número da conta bancária do investidor. | | `investor_bank_account.account_digit`* | string | Dígito verificador da conta bancária do investidor. | | `investor_bank_account.account_branch`* | string | Agência bancária do investidor. | | `investor_bank_account.financial_institution_code_number`* | string | Código da instituição financeira do investidor. | | `investor_bank_account.financial_institution_ispb`* | string | ISPB da instituição financeira do investidor. | | `subscripted_quantity`* | integer | Quantidade de cotas que o investidor deseja subscrever. | | `financial_base_date`* | string | Data base financeira. | | `subscription_date`* | string | Data da subscrição. | | `subscription_note_template_key`* | string | Template do boletim de subscrição. | --- ### 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** | Campo | Tipo | Descrição | | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | `subscription_key` | string | Chave única da subscrição (UUID v4). | | `investor_key` | string | Chave única do investidor associado à subscrição (UUID v4). | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Número do documento do investidor (CPF ou CNPJ). | | `investor_bank_account` | object | **[Objeto investor_bank_account](#objeto-investor_bank_account)**. | | `subscription_date` | string | Data da subscrição (formato: YYYY-MM-DD). | | `financial_base_date` | string | Data base financeira da subscrição (formato: YYYY-MM-DD). | | `subscripted_quantity` | integer | Quantidade de cotas subscritas. | | `unit_price` | number | Preço unitário das cotas subscritas. | | `expected_amount` | number | Valor total esperado da subscrição. | | `paid_amount` | number | Valor total pago na subscrição. | | `subscription_note_template_key` | string | Chave única do template da nota de subscrição (UUID v4). | | `subscription_note_document_key` | string | Chave única do documento da nota de subscrição. | | `envelope_signature_status` | string | Status de assinatura da nota de subscrição. | | `envelope_signature_url` | string | URL de assinatura da nota de subscrição. | | `envelope_key` | string | Chave do envelope de assinatura. | | `subscription_payment_list` | array | Lista de pagamentos associados à subscrição.**[Objeto subscription_payment_list](#objeto-subscription_payment_list)**. | --- ### Objeto investor_bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ----------------------------------------------------- | | `account_number` | string | Número da conta bancária do investidor. | | `account_digit` | string | Dígito verificador da conta bancária do investidor. | | `account_branch` | string | Agência bancária do investidor. | | `financial_institution_code_number` | string | Código da instituição financeira do investidor. | | `financial_institution_ispb` | string | ISPB da instituição financeira do investidor. | ### Objeto subscription_payment_list | Campo | Tipo | Descrição | | -------------------------------- | ------ | -------------------------------------------------------------------------------------------- | | `subscription_payment_key` | string | Chave única do pagamento da subscrição (UUID v4). | | `payment_receipt_document_key` | string | Chave do documento do comprovante de pagamento. | | `description` | string | Descrição do comprovante de pagamento. | | `amount` | number | Valor do pagamento registrado. | | `subscription_payment_status` | string | Status do pagamento. Valores possíveis:`waiting_confirmation`, `confirmed`, `denied`. | | `updated_at` | string | Data e hora da última atualização do pagamento (formato: ISO 8601). | --- # Cancelar subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao --- ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|------------------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única do processo de integralização (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Chave única da subscrição (UUID v4). | 36 | --- ### Request Body ```json { "subscription_status": "canceled" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |-------------------|----------|-----------------------------------------|-------------| | `subscription_status` | string | Valores aceitos: `canceled`. | Sim | --- ### Response STATUS 200 Será retornado um exemplar atualizado da Subscrição. --- --- # Confirmação ou Rejeição do Pagamento de Subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento Este endpoint permite confirmar ou rejeitar o pagamento associado a uma subscrição de integralização. O status do pagamento é atualizado conforme o valor fornecido no corpo da requisição. --- ## Atualização do Status do Pagamento (PATCH) ### Request ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment/ SUBSCRIPTION-PAYMENT-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------------------- | ------ | ---------------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Chave única da subscrição associada (UUID v4). | 36 | | `SUBSCRIPTION-PAYMENT-KEY` | string | Chave única do pagamento da subscrição (UUID v4). | 36 | --- ### Request Body ```json { "subscription_payment_status": "confirmed" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | | -------------------------------- | ------ | ------------------------------------------------------------------------- | ------------ | | `subscription_payment_status`* | string | Novo status do pagamento. Valores possíveis:`confirmed` ou `denied`. | Sim | --- ### 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 | Campo | Tipo | Descrição | | ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | | `subscription_payment_key` | string | Chave única do pagamento da subscrição (UUID v4). | | `amount` | number | Valor declarado do pagamento registrado. | | `description` | number | Descrição do conteudo do recibo. | | `subscription_payment_status` | string | Status atualizado do pagamento. Valores possíveis:`waiting_confirmation` `confirmed`, `denied`. | | `updated_at` | string | Data e hora da atualização do status do pagamento (formato: ISO 8601). | --- # Consulta de Subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas Este endpoint permite consultar uma subcrição em andamento. --- ## Consulta de Subscrição (GET) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------|--------|------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Chave única da subscrição (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** | Campo | Tipo | Descrição | |-----------------------------------------------------------|------------|---------------------------------------------------------------------------| | `subscription_key` | string | Chave única da subscrição (UUID v4). | | `investor_key` | string | Chave única do investidor associado à subscrição (UUID v4). | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Número do documento do investidor (CPF ou CNPJ). | | `investor_bank_account` | object | **[Objeto investor_bank_account](#objeto-investor_bank_account)**. | | `subscription_date` | string | Data da subscrição (formato: YYYY-MM-DD). | | `financial_base_date` | string | Data base financeira da subscrição (formato: YYYY-MM-DD). | | `subscripted_quantity` | integer | Quantidade de cotas subscritas. | | `unit_price` | number | Preço unitário das cotas subscritas. | | `expected_amount` | number | Valor total esperado da subscrição. | | `paid_amount` | number | Valor total pago na subscrição. | | `subscription_note_template_key` | string | Chave única do template da nota de subscrição (UUID v4). | | `subscription_note_document_key` | string | Chave única do documento da nota de subscrição. | | `envelope_signature_status` | string | Status de assinatura da nota de subscrição. | | `envelope_signature_url` | string | URL de assinatura da nota de subscrição. | | `envelope_key` | string | Chave do envelope de assinatura. | | `subscription_payment_list` | array | Lista de pagamentos associados à subscrição. **[Objeto subscription_payment_list](#objeto-subscription_payment_list)**. | --- ### Objeto investor_bank_account | Campo | Tipo | Descrição | |--------------------------------|------------|---------------------------------------------------------| | `account_number` | string | Número da conta bancária do investidor. | | `account_digit` | string | Dígito verificador da conta bancária do investidor. | | `account_branch` | string | Agência bancária do investidor. | | `financial_institution_code_number` | string | Código da instituição financeira do investidor. | | `financial_institution_ispb` | string | ISPB da instituição financeira do investidor. | ### Objeto subscription_payment_list | Campo | Tipo | Descrição | |-----------------------------------------------------------|------------|---------------------------------------------------------------------------| | `subscription_payment_key` | string | Chave única do pagamento da subscrição (UUID v4). | | `payment_receipt_document_key` | string | Chave do documento do comprovante de pagamento. | | `description` | string | Descrição do comprovante de pagamento. | | `amount` | number | Valor do pagamento registrado. | | `subscription_payment_status` | string | Status do pagamento. Valores possíveis: `waiting_confirmation`, `confirmed`, `denied`. | | `updated_at` | string | Data e hora da última atualização do pagamento (formato: ISO 8601). | --- # Registro de Pagamento de Subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento Este endpoint permite registrar um pagamento associado a uma subscrição de integralização. O pagamento inclui um valor declarado e um comprovante em Base64. --- ## Registro de Pagamento (POST) ### Request ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ----------------------- | ------ | ------------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Chave única da subscrição associada (UUID v4). | 36 | --- ### Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "amount": 100000.00, "description": "Comprovante de pagamento Itau R$100.000,00" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | | -------------------- | ------- | ---------------------------------------------- | ------------ | | `document_base64`* | string | Comprovante de pagamento codificado em Base64. | Sim | | `amount`* | number | Valor declarado do pagamento realizado. | Sim | | `description` | *number | Descrição do conteúdo do comprovante. | Sim | --- ### 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 | Campo | Tipo | Descrição | | ------------------------------- | ------ | ----------------------------------------------------------------------------------------------- | | `subscription_payment_key` | string | Chave única do pagamento da subscrição (UUID v4). | | `amount` | number | Valor declarado do pagamento registrado. | | `subscription_payment_status` | string | Status atual do pagamento. Valores possíveis:`waiting_confirmation` `confirmed` `denied` | | `description` | number | Descrição do conteúdo do comprovante. | --- --- # Recebimento de Webhooks URL: /documentation/escrituracao/introducao/autenticacao_webhooks A assinatura dos Webhooks utiliza-se de uma estratégia de criptografia com chaves simétricas, ou seja, tanto a QI CTVM quanto o Parceiro integrador compartilham de uma mesma chave. Ao realizarmos uma configuração de Webhooks, iremos gerar uma Signature Key e disponibiliza-lá. Toda requisição originada no sistema da QI, irá carregar um header SIGNATURE que será um JWT assinado com essa chave. O encoding é realizado com o algoritmo HS256. Abaixo temos um exemplo em python de como realizar o decoding da assinatura: ```python from jose import jwt signature_key = "CHAVE UNICA CONFIGURADA" signature_token = headers["SIGNATURE"] decoded_token = jwt.decode(signature_token, key=signature_key, algorithms=["HS256"]) print(decoded_token) ``` Sugerimos que, além de comparar a assinatura, o parceiro integrador valide o nosso IP, dado que todas as nossas requisições são originadas de um mesmo IP, conforme o ambiente: |Ambiente| IP | |--------|----| |Produção| - | |Sandbox | - | :::danger Atenção! Os webhooks da QI CTVM não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs. ::: --- # Escrituração de Notas Comerciais URL: /documentation/escrituracao/introducao/ Essa documentação tem como objetivo descrever os fluxos, endpoints e estruturas de dados necessárias para operar e emissão de **Notas Comerciais**. Obs.: Em caso de dúvidas em qualquer etapa do processo favor entre em contato com [suporte.dcm@qitech.com.br](mailto:suporte.dcm@qitech.com.br) detalhando seu problema/dúvida que te auxiliaremos. ## Ambientes (Hosts) A QI CTVM possui dois ambientes, SANDBOX e PRODUÇÃO. Ambos os ambientes possuem código e comportamento completamente idênticos, porém, o ambiente de SANDBOX apresenta valores monetários totalmente fictícios, e o ambiente de Produção realiza transações financeiras válidas. O ambiente Sandbox foi criado para os desenvolvedores realizarem suas integrações, e quando estiverem prontos para entrada em produção, atualizarem apenas as variáveis de ambiente com os parâmetros de Produção. | Ambiente | Host | |----------|----------------------------------------------| | Sandbox | https://api.sandbox.securities.qidtvm.com.br | | Produção | https://api.securities.qidtvm.com.br | --- # Endpoints de teste URL: /documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste ## Método GET ### Request ENDPOINT /authentication_test MÉTODO GET ### Response STATUS 200 Response Body ```json { "success": "Congrats!" } ``` ## Metodo POST ### Request ENDPOINT /authentication_test MÉTODO POST Request Body ```json { "name": "QI Tech" } ``` ### Response STATUS 200 Response Body ```json { "name": "QI Tech", "success": "Congrats!" } ``` --- # Teste de autenticação URL: /documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao ### 1. Introdução Nessa seção iremos explicar como deve funcionar a requisição para que possa ser aceita pelo nosso sistema. Em primeiro Lugar deve-se colocar no header API-CLIENT-KEY a Api Key fornecida pelo time da QI CTVM. Depois deve-se criar um Header de AUTHORIZATION assinando com a Chave Privada do parceiro integrador; Abaixo iremos ensinar o passo a passo utilizando de Python para exemplificar o processo de criação da AUTHORIZATION. ### 2. Importar bibliotecas Neste exemplo em python estamos usando 5 bibliotecas para poder realizar o processo de autenticação. ```python from datetime import datetime import json from jose import jwt from hashlib import md5 import requests ``` ### 3. Inserir a chave privada e a chave de integração ```python title="Dados da criptografia" 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. Definir variáveis Definir as variáveis método, endpoint e conteúdo particular a cada requisição (neste exemplo, utilizaremos o método "POST" para o endpoint "/authentication_test") ```python title="Dados da requisição" 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. Construir Dicionário Base de Assinatura ```python title="Dicionário base" dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint} ``` #### 5.1. Se necessário, adicionar o conteúdo Para as requisições que tenham _body_, deve-se adicionar o md5 do bytes desse conteúdo. Como todas as requisições no nosso sistema são através de JSON, pode-se usar o seguinte: ```python title="Dicionário base" 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. Realizar criptografia do header Realizar criptografia utilizando biblioteca JWT (neste exemplo de código, utilizamos jsonwebtoken como jwt em 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. Montando o header final ```python headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token} ``` ```python title="Definindo url final" url = f"{base_url}{endpoint}" ``` ### Realizando requisição ```python resp = requests.post(url=url, headers=headers, json=body) print(resp.json()) ``` --- # Troca de Chaves URL: /documentation/escrituracao/introducao/troca_de_chaves ## 1. Requisição Assinada Todas as requisições em nossas APIs devem usar o protocolo **HTTPs**, utilizando **TLS 1.2 ou 1.3**, contendo dois Headers: 1. API-CLIENT-KEY: Uma chave disponibilizada pelo nosso time de Integração que identifica uma integração específica; 2. AUTHORIZATION: Uma assinatura da requisição que deve ser realizada conforme explicado nesse manual; Como padrão a QI CTVM utiliza-se do padrão de chaves assimétricas, onde existem duas chaves diferentes, uma para assinatura, denominada chave privada , e uma para leitura, denominada de chave pública . Com a chave privada, o parceiro integrador deverá realizar a assinatura utilizando-se do padrão JWT. O parceiro integrador é responsável por gerar o par e fornecer ao time da QI CTVM a chave pública para que possamos validar as suas requisições. :::caution **Atenção** A chave privada é de uso exclusivo do parceiro integrador, e deve ser armazenada com segurança. A QI CTVM nunca irá pedir, em hipótese alguma, que voce a compartilhe conosco. ::: ## 2. Gerando o par Para gerar uma chave privada em um computador UNIX faça: ```bash $ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key ``` E a partir desta chave privada gere sua chave pública. ```bash $ openssl ec -in private.key -pubout -outform PEM -out public.key.pub ``` A chave pública gerada (arquivo public.key.pub) deve ser enviada para o time da QI Tech, e aguardar a integração ser configurada; --- # Consulta de Ativo URL: /documentation/escrituracao/operacoes-ativas/consulta-security Este endpoint permite consultar os detalhes de um ativo utilizando sua chave única. --- ## **Request** ENDPOINT /security/security/ SECURITY-KEY MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres | |--------------|--------|-----------------------------------------------|------------| | `SECURITY-KEY` | string | Chave única do security (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** | Campo | Tipo | Descrição | |------------------------------|----------|--------------------------------------------------------------| | `tenant_key` | string | Chave única do tenant associado ao security. | | `security_key` | string | Chave única do security. | | `operation_key` | string | Chave única da operação associada ao security. | | `operation_type` | string | Tipo da operação. Valores possíveis: `commercial_paper`. | | `contract_number` | string | Número do contrato associado ao security. | | `issuer_key` | string | Chave única do emissor associado. | | `issuer_name` | string | Nome do emissor do security. | | `issuer_document_number` | string | Número do documento do emissor (CPF/CNPJ). | | `issuer_bank_account` | object | **[Objeto issuer_bank_account](#objeto-bank_account)**. | | `financial_base_date` | string | Data base financeira do security. | | `current_unit_price` | number | Preço unitário atual do security. | | `latest_accrual_date` | string | Data do último accrual realizado. | | `integralized_quantity` | integer | Quantidade total de cotas integralizadas. | | `issue_quantity` | integer | Quantidade total de cotas emitidas na operação. | | `security_status` | string | Status do security. Valores possíveis: `active`, `inactive`. | | `is_defaulted` | boolean | Indica se o security está inadimplente (`true` ou `false`). | | `financial` | object | **[Objeto financial](#objeto-financial)**. | | `investment_list` | array | Lista de investimentos. **[Objeto investment](#objeto-investment)**. | --- ### **Objeto bank_account** | Campo | Tipo | Descrição | |--------------------------------|----------|-------------------------------------------------| | `account_number` | string | Número da conta bancária do emissor. | | `account_digit` | string | Dígito verificador da conta bancária do emissor. | | `account_branch` | string | Agência bancária do emissor. | | `financial_institution_ispb` | string | ISPB da instituição financeira do emissor. | | `financial_institution_code_number` | string | Código da instituição financeira do emissor. | --- ### **Objeto financial** | Campo | Tipo | Descrição | |--------------------------------|----------|-------------------------------------------------| | `financial_base_date` | string | Data base financeira. | | `issue_quantity` | integer | Quantidade de cotas emitidas. | | `unit_price` | number | Preço unitário das cotas. | | `issue_amount` | number | Valor total da emissão. | | `released_amount` | number | Valor total liberado. | | `cet` | number | Custo efetivo total (CET). | | `annual_cet` | number | Custo efetivo total anualizado. | | `number_of_installments` | integer | Número total de parcelas. | | `prefixed_interest_rate` | object | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)**. | | `post_fixed_interest_rate` | object | **[Objeto post_fixed_interest_rate](#objeto-post_fixed_interest_rate)**. | | `financial_index` | object | **[Objeto financial_index](#objeto-financial_index)**. | | `fine_delay_rate` | object | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)**. | | `contract_fine_rate` | number | Multa contratual. | | `fees` | array | Lista de taxas. **[Objeto fees](#objeto-fees)**. | | `installment_list` | array | Lista de parcelas. **[Objeto installment](#objeto-installment)**. | --- ### **Objeto investment** | Campo | Tipo | Descrição | |--------------------------------|----------|-------------------------------------------------| | `investment_key` | string | Chave única do investimento. | | `acquisition_date` | string | Data de aquisição do investimento. | | `acquisition_unit_price` | number | Preço unitário na aquisição. | | `acquisition_amount` | number | Valor total da aquisição. | | `acquisition_quantity` | integer | Quantidade de cotas adquiridas. | | `investor_key` | string | Chave única do investidor. | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Documento do investidor (CPF/CNPJ). | | `investor_bank_account` | object | **[Objeto investor_bank_account](#objeto-bank_account)**. | | `total_sell_amount` | number | Valor total de vendas realizadas. | | `total_yield_amount` | number | Valor total de rendimentos. | | `total_amortization_amount` | number | Valor total de amortizações. | | `current_quantity` | integer | Quantidade atual de cotas. | | `investment_transaction_list` | array | Lista de transações. **[Objeto investment_transaction](#objeto-investment_transaction)**. | --- ### **Objeto investment_transaction** | Campo | Tipo | Descrição | |--------------------------------|----------|-------------------------------------------------| | `transaction_type` | string | Tipo da transação (`integralization`, `maturity`). | | `transaction_date` | string | Data da transação. | | `transaction_unit_price` | number | Preço unitário na transação. | | `transaction_amount` | number | Valor total da transação. | | `transaction_quantity` | integer | Quantidade de cotas transacionadas. | | `amortization_amount` | number | Valor de amortização na transação. | | `yield_amount` | number | Valor de rendimento na transação. | | `old_quantity` | integer | Quantidade de cotas antes da transação. | | `new_quantity` | integer | Quantidade de cotas após a transação. | | `investment_transaction_origin`| string | Origem da transação (`subscription`, `settlement_process_payment`). | | `investment_transaction_origin_key` | string | Chave da origem da transação. | ### **Objeto prefixed_interest_rate** | Campo | Tipo | Descrição | |---------------------|--------|--------------------------------------------------| | `daily_rate` | number | Taxa de juros diária prefixada. | | `annual_rate` | number | Taxa de juros anual prefixada. | | `monthly_rate` | number | Taxa de juros mensal prefixada. | | `interest_base` | string | Base de cálculo dos juros (`calendar_days_365`). | --- ### **Objeto post_fixed_interest_rate** | Campo | Tipo | Descrição | |---------------------|--------|---------------------------------------------------| | `daily_rate` | number | Taxa de juros diária pós-fixada. | | `annual_rate` | number | Taxa de juros anual pós-fixada. | | `monthly_rate` | number | Taxa de juros mensal pós-fixada. | | `interest_base` | string | Base de cálculo dos juros (`calendar_days_365`). | --- ### **Objeto financial_index** | Campo | Tipo | Descrição | |------------------|--------|-------------------------------------------------| | `index_type` | string | Tipo do índice financeiro (`CDI`, `IPCA`, etc.). | | `index_value` | number | Valor do índice financeiro. | --- ### **Objeto fine_delay_rate** | Campo | Tipo | Descrição | |---------------------|--------|------------------------------------------------| | `daily_rate` | number | Taxa de juros diária para atraso no pagamento. | | `annual_rate` | number | Taxa de juros anual para atraso no pagamento. | | `monthly_rate` | number | Taxa de juros mensal para atraso no pagamento. | | `interest_base` | string | Base de cálculo dos juros (`calendar_days_365`).| --- ### **Objeto fees** | Campo | Tipo | Descrição | |-------------|---------|--------------------------------------------| | `type` | string | Tipo da taxa (`internal`, `external`). | | `amount` | number | Percentual ou valor absoluto da taxa. | | `fee_type` | string | Tipo da taxa. | | `fee_amount`| number | Valor monetário da taxa aplicada. | | `amount_type` | string | Tipo do valor (`percentage`, `absolute`). | --- ### **Objeto installment** | Campo | Tipo | Descrição | |----------------------------------------|---------|-----------------------------------------------------------| | `installment_key` | string | Chave única da parcela. | | `installment_status` | string | Status da parcela | | `installment_number` | integer | Número da parcela na sequência do cronograma. | | `workdays` | integer | Quantidade de dias úteis até o vencimento. | | `calendar_days` | integer | Quantidade de dias corridos até o vencimento. | | `principal_amortization_unit_price` | number | Valor unitário da amortização do principal. | | `principal_amortization_amount` | number | Valor total da amortização do principal. | | `interest_amount` | number | Valor total dos juros da parcela. | | `interest_amount_unit_price` | number | Valor unitário dos juros da parcela. | | `post_fixed_interest_amount` | number | Valor total dos juros pós-fixados da parcela. | | `post_fixed_interest_amount_unit_price` | number | Valor unitário dos juros pós-fixados da parcela. | | `amount` | number | Valor total da parcela. | | `due_principal` | number | Valor do principal pendente antes da parcela. | | `due_interest` | number | Valor dos juros pendentes antes da parcela. | | `due_date` | string | Data de vencimento da parcela. | | `has_interest` | boolean | Indica se a parcela contém juros (`true` ou `false`). | | `current_unit_price` | number | Preço unitário atualizado da parcela. | | `latest_accrual_date` | string | Data do último accrual da parcela. | | `paid_at` | string | Data do pagamento da parcela (se aplicável). | | `paid_amount` | number | Valor total pago da parcela (se aplicável). | | `settlement_process_list` | array | Lista de processos de liquidação. **[Objeto settlement_process](#objeto-settlement_process)** | ### **Objeto settlement_process** | Campo | Tipo | Descrição | |-----------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------| | `settlement_process_key` | string | Chave única do processo de liquidação. | | `installment_key` | string | Chave única da parcela associada à liquidação. | | `due_date` | string | Data de vencimento da parcela associada. | | `reference_date` | string | Data de referência da liquidação. | | `current_integralized_quantity` | integer | Quantidade de cotas integralizadas no momento da liquidação. | | `principal_amortization_amount` | number | Valor da amortização do principal. | | `interest_amount` | number | Valor total dos juros pagos na liquidação. | | `post_fixed_interest_amount` | number | Valor dos juros pós-fixados pagos na liquidação. | | `fine_amount` | number | Valor da multa aplicada (se houver). | | `total_amount` | number | Valor total da liquidação. | | `expected_total_amount` | number | Valor total esperado da liquidação. | | `paid_amount` | number | Valor total pago na liquidação. | | `settlement_process_status` | string | Status da liquidação (`waiting_payment`, `paid`, `canceled`). | | `paid_at` | string | Data do pagamento da liquidação (se aplicável). | | `settlement_process_payment_list` | array | Lista de pagamentos associados à liquidação. **[Objeto settlement_process_payment](#objeto-settlement_process_payment)** | ### **Objeto settlement_process_payment** | Campo | Tipo | Descrição | |---------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------| | `settlement_process_payment_key` | string | Chave única do pagamento do processo de liquidação. | | `investment` | object | Informações do investimento. **[Objeto investment](#objeto-investment)**. | | `investment_quantity` | integer | Quantidade de cotas do investimento envolvidas no pagamento. | | `amount` | number | Valor do pagamento realizado. | | `paid_at` | string | Data e hora do pagamento (formato ISO 8601). | | `settlement_process_payment_status` | string | Status do pagamento (`waiting_payment`, `paid`, `canceled`). | | `settlement_process_payment_type` | string | Tipo do pagamento (`manual`). | | `settlement_process_payment_receipt_list` | array | Lista de recibos do pagamento. **[Objeto settlement_process_payment_receipt](#objeto-settlement_process_payment_receipt)**. | ### **Objeto settlement_process_payment_receipt** | Campo | Tipo | Descrição | |---------------------------------------------|--------|-------------------------------------------------------------------| | `settlement_process_payment_receipt_key` | string | Chave única do recibo de pagamento do processo de liquidação. | | `settlement_process_payment_receipt_status` | string | Status do recibo (`waiting_confirmation`, `confirmed`, `denied`). | | `amount` | number | Valor do recibo. | | `updated_at` | string | Data e hora da última atualização do recibo (formato ISO 8601). | ### **Enumeradores security_status** | Enum | Descrição | |-----------|------------------------------------------------------| | `issued` | A security foi emitida, mas ainda não está ativa. | | `active` | A security está ativa e em andamento. | | `matured` | A security chegou ao vencimento. | | `canceled` | A security foi cancelada. | ### **Enumeradores installment_status** | Enum | Descrição | |-----------------------------|-----------------------------------------------------------------------| | `created` | A parcela foi criada, mas ainda não está disponível para pagamento. | | `opened` | A parcela está aberta. | | `waiting_payment` | A parcela está aguardando o pagamento pelo investidor. | | `paid_partial` | A parcela foi parcialmente paga. | | `paid` | A parcela foi totalmente paga. | | `paid_early` | A parcela foi paga antecipadamente. | | `overdue` | A parcela venceu e não foi paga. | | `paid_partial_overdue` | A parcela foi parcialmente paga após o vencimento. | | `paid_overdue` | A parcela foi paga após o vencimento. | | `canceled` | A parcela foi cancelada e não precisa ser paga. | | `unmonitored` | A parcela não é monitorada para pagamentos. | --- # Consulta de Posição do Investidor URL: /documentation/escrituracao/operacoes-ativas/posicao-investidor Este endpoint permite consultar a posição consolidada de um investidor, retornando informações sobre suas participações em securities. --- ## Request ENDPOINT /security/investor/ INVESTOR-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|-----------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (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 | Campo | Tipo | Descrição | |----------------------------|----------|--------------------------------------------------------------------| | `investor_key` | string | Chave única do investidor. | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Número do documento do investidor (CNPJ). | | `total_current_amount` | number | Valor total consolidado do investidor. | | `investment_list` | array | Lista das participações do investidor em securities. **[Objeto investment](#objeto-investment)** | ### Objeto investment | Campo | Tipo | Descrição | |-----------------------|----------|--------------------------------------------------| | `current_unit_price` | number | Preço unitário atual da security. | | `current_quantity` | integer | Quantidade atual da security do investidor. | | `security_key` | string | Chave única da security associada. | | `contract_number` | string | Número do contrato da security. | | `investment_key` | string | Chave única do investimento do investidor. | | `current_amount` | number | Valor atual da participação do investidor. | --- # Webhooks de Escrituração URL: /documentation/escrituracao/webhooks-escrituracao ## Visão Geral Os webhooks de escrituração permitem que você receba notificações em tempo real sobre mudanças de status e eventos importantes relacionados ao processo de emissão de Notas Comerciais. Quando um evento ocorre, a QI Tech envia automaticamente um payload HTTP POST para a URL configurada em seu sistema. ## Configuração de Webhooks Para receber webhooks, você precisa configurar uma URL de endpoint em seu sistema. Consulte a [documentação de configuração de webhooks](./introducao/autenticacao_webhooks.md) para mais detalhes sobre como cadastrar e gerenciar suas URLs de webhook. ### Autenticação e Segurança Todos os webhooks enviados pela QI Tech incluem uma assinatura HMAC-SHA256 no header `Signature`. Esta assinatura deve ser validada em seu sistema para garantir a autenticidade e integridade dos dados recebidos. Para mais informações sobre o processo de validação, consulte a [documentação de autenticação de webhooks](./introducao/autenticacao_webhooks.md). ## Eventos Disponíveis ### Gestão de Emissores #### Cadastro Emissor Aprovado Enviado quando o cadastro de um emissor é aprovado pelo 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" } } ``` #### Cadastro Emissor Reprovado Enviado quando o cadastro de um emissor é reprovado pelo 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" } } ``` ### Gestão de Investidores #### Cadastro Investidor Aprovado Enviado quando o cadastro de um investidor é aprovado pelo 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" } } ``` #### Cadastro Investidor Reprovado Enviado quando o cadastro de um investidor é reprovado pelo 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" } } ``` ### Gestão de Operações #### Operação Aprovada Enviado quando uma operação é aprovada pelo compliance e está pronta para ser enviada para assinatura. **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" } } ``` #### Operação Enviada para Assinatura Enviado quando uma operação é enviada para assinatura das partes envolvidas. **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" } } ``` #### Operação Assinada e Emitida Enviado quando uma operação é assinada por todas as partes. Este evento confirma que a Nota Comercial foi emitida com sucesso. **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" } } ``` #### Operação Cancelada Enviado quando uma operação é cancelada. **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" } } ``` ### Gestão de Subscrições #### Subscrição Enviada para Assinatura Enviado quando uma subscrição é criada e enviada para assinatura do investidor. **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" } } ``` #### Subscrição Assinada Enviado quando a subscrição é assinada por todas as partes e está aguardando o pagamento. **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" } } ``` #### Subscrição Finalizada Enviado quando a subscrição é completamente finalizada após a confirmação do pagamento. **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" } } ``` ### Gestão de Pagamentos de Subscrição #### Comprovante de Pagamento Incluído Enviado quando um comprovante de pagamento é incluído e está aguardando confirmação. **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" } } ``` #### Comprovante de Pagamento Aprovado Enviado quando o comprovante de pagamento é aprovado e confirmado. **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" } } ``` ## Fluxo de Eventos ### Fluxo de Emissão de Nota Comercial 1. **Cadastro do Emissor** → `issuer_status_change` (approved/reproved) 2. **Cadastro do Investidor** → `investor_status_change` (approved/reproved) 3. **Criação da Operação** → `operation_status_change` (pending_signature_submission) 4. **Envio para Assinatura** → `operation_status_change` (waiting_signature) 5. **Operação Emitida** → `operation_status_change` (issued) ### Fluxo de Subscrição 1. **Criação da Subscrição** → `subscription_status_change` (waiting_signature) 2. **Assinatura Concluída** → `subscription_status_change` (waiting_payment) 3. **Inclusão do Comprovante** → `subscription_payment_status_change` (waiting_confirmation) 4. **Pagamento Confirmado** → `subscription_payment_status_change` (confirmed) 5. **Subscrição Finalizada** → `subscription_status_change` (finished) ## Boas Práticas 1. **Responda rapidamente**: Retorne um status HTTP 2xx o mais rápido possível para confirmar o recebimento do webhook. 2. **Processamento assíncrono**: Para operações demoradas, confirme o recebimento imediatamente e processe o evento de forma assíncrona. 3. **Idempotência**: Implemente lógica idempotente, pois webhooks podem ser reenviados em caso de falha de rede. 4. **Validação de assinatura**: Sempre valide a assinatura HMAC antes de processar o webhook. 5. **Logs e monitoramento**: Mantenha logs detalhados de todos os webhooks recebidos para auditoria e debugging. ## Referências - [Configuração de Webhooks](./introducao/autenticacao_webhooks.md)