# QI Tech — Investment-as-a-Service › 记账 Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 130 página(s). Índice: - Aditamento (/zh-Hans/documentation/escrituracao/aditamento/conceito) - Baixar Documento (/zh-Hans/documentation/escrituracao/aditamento/endpoints/baixar-documento) - Cancelar Aditamento (/zh-Hans/documentation/escrituracao/aditamento/endpoints/cancelar-aditamento) - Consultar Aditamento (/zh-Hans/documentation/escrituracao/aditamento/endpoints/consultar-aditamento) - Consultar Signatários (/zh-Hans/documentation/escrituracao/aditamento/endpoints/consultar-signatarios) - Criar Aditamento (/zh-Hans/documentation/escrituracao/aditamento/endpoints/criar-aditamento) - Simular Aditamento (/zh-Hans/documentation/escrituracao/aditamento/endpoints/simular-aditamento) - Validar Aditamento (/zh-Hans/documentation/escrituracao/aditamento/endpoints/validar-aditamento) - Exemplos (/zh-Hans/documentation/escrituracao/aditamento/exemplos) - Regras de Negócio — Aditamento (/zh-Hans/documentation/escrituracao/aditamento/regras-de-negocio) - Tipos de Alteração (/zh-Hans/documentation/escrituracao/aditamento/tipos-de-alteracao) - 非常规摊还 (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/conceito) - 查询非常规摊还 (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao) - 创建非常规摊还 (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao) - 模拟特别摊销现值 (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente) - 示例 — 非常规摊还 (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/exemplos) - 回购式摊还 (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao) - 业务规则 — 非常规摊还 (/zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio) - 错误目录 (/zh-Hans/documentation/escrituracao/catalogo-erros/catalogo-erros) - Webhook 配置 (/zh-Hans/documentation/escrituracao/configuracao-webhooks) - 登记基础资产（Lastro） (/zh-Hans/documentation/escrituracao/emissao-cr/cadastro-lastro) - 登记CR操作 (/zh-Hans/documentation/escrituracao/emissao-cr/cadastro-operacao) - 提交文件 (/zh-Hans/documentation/escrituracao/emissao-cr/envio-documento) - 提交操作的外部文件 (/zh-Hans/documentation/escrituracao/emissao-cr/envio-documento-externo) - 登记基础资产（Lastro） (/zh-Hans/documentation/escrituracao/emissao-cra/cadastro-lastro) - 登记CRA操作 (/zh-Hans/documentation/escrituracao/emissao-cra/cadastro-operacao) - 提交文件 (/zh-Hans/documentation/escrituracao/emissao-cra/envio-documento) - 提交操作的外部文件 (/zh-Hans/documentation/escrituracao/emissao-cra/envio-documento-externo) - 登记基础资产（Lastro） (/zh-Hans/documentation/escrituracao/emissao-cri/cadastro-lastro) - 登记CRI操作 (/zh-Hans/documentation/escrituracao/emissao-cri/cadastro-operacao) - 提交文件 (/zh-Hans/documentation/escrituracao/emissao-cri/envio-documento) - 提交操作的外部文件 (/zh-Hans/documentation/escrituracao/emissao-cri/envio-documento-externo) - 更新操作的拨付账户 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso) - 更新操作的财务数据 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros) - 更新操作的签名方式 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura) - 在操作中添加担保品 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) - 从操作中移除担保品 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia) - 文件上传 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento) - 在操作中登记和删除元数据 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao) - 发送和删除关联方代表的文件 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento) - 发送和删除关联方代表的签名人组 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) - 在特定文件中登记和删除关联方 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento) - 登记和删除关联方 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) - 登记商业票据操作 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) - 操作的第三方拨付 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro) - 扩展字段（Extra Fields） (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields) - 客户接受日志上传 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite) - 取消操作 (/zh-Hans/documentation/escrituracao/emissao-de-notas/cancelar-operacao) - 查询通过 QI SIGN 签署的操作合同链接 (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) - 查询通过 QI SIGN 签署操作的链接 (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) - Consulta dos Documentos da Operação (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao) - 通过键查询操作 (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) - 通过筛选条件查询操作 (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) - 按发行人查询下一个发行编号 (/zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao) - 提交已签署的批准会议纪要 (/zh-Hans/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) - 提交操作的已签署文件 (/zh-Hans/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados) - 将操作提交分析 (/zh-Hans/documentation/escrituracao/emissao-de-notas/envio-para-analise) - 将操作提交签名 (/zh-Hans/documentation/escrituracao/emissao-de-notas/envio-para-assinatura) - 更改加入条款模板 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta) - 更改组成性条款模板 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) - 预览加入条款 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao) - 预览组成性条款 (/zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) - 商业票据发行介绍 (/zh-Hans/documentation/escrituracao/emissao-de-notas/inicio) - 财务条件模拟 (/zh-Hans/documentation/escrituracao/emissao-de-notas/simulacao) - 登记债券操作 (/zh-Hans/documentation/escrituracao/emissao-debentures/cadastro-operacao) - 提交文件 (/zh-Hans/documentation/escrituracao/emissao-debentures/envio-documento) - 提交操作的外部文件 (/zh-Hans/documentation/escrituracao/emissao-debentures/envio-documento-externo) - 提交操作担保 (/zh-Hans/documentation/escrituracao/emissao-debentures/envio-garantia) - 更新发行人登记 (/zh-Hans/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) - Consulta da Auto-assinatura (/zh-Hans/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) - Consulta dos Links de Assinatura do Termo de Adesão (/zh-Hans/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) - Auto-assinatura do Emissor (/zh-Hans/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) - Solicitação da Auto-assinatura (/zh-Hans/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) - 登记发行人签名人组 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) - 删除发行人签名人组 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) - 发行人基本登记 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) - 登记发行人银行账户 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor) - 设置发行人主银行账户 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal) - 删除发行人银行账户 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) - 提交发行人文件 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor) - 删除发行人文件 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) - 提交发行人代表文件 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor) - 删除发行人代表文件 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) - 登记发行人联系信息 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor) - 设置发行人主联系人 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal) - 删除发行人联系信息 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) - 登记发行人代表 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor) - 删除发行人代表 (/zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) - 查询发行人 (/zh-Hans/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) - 按过滤条件查询发行人 (/zh-Hans/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) - 提交发行人分析 (/zh-Hans/documentation/escrituracao/homologacao-emissor/envio-analise/) - 介绍 (/zh-Hans/documentation/escrituracao/homologacao-emissor/inicio) - 申请访问发行人数据 (/zh-Hans/documentation/escrituracao/homologacao-emissor/solicitacao-acesso) - 更新投资人登记 (/zh-Hans/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/) - 登记投资人签名人组 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor) - 删除投资人签名人组 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) - 投资人基本登记 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico) - 登记投资人银行账户 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor) - 删除投资人银行账户 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) - 提交投资人文件 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor) - 删除投资人文件 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) - 上传投资者代表文件 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor) - 删除投资者代表文件 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) - 注册投资者联系信息 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor) - 删除投资者联系信息 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao) - 登记投资人代表 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor) - 删除投资人代表 (/zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) - 查询投资人 (/zh-Hans/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) - 按过滤条件查询投资人 (/zh-Hans/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) - 提交投资人分析 (/zh-Hans/documentation/escrituracao/homologacao-investidor/envio-analise/) - 介绍 (/zh-Hans/documentation/escrituracao/homologacao-investidor/inicio) - **申请访问投资人数据** (/zh-Hans/documentation/escrituracao/homologacao-investidor/solicitacao-acesso) - 查询交易凭证 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao) - 清算账户查询 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao) - 按键查询认缴 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) - 查询认缴交易列表 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao) - 股份认缴介绍 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/inicio) - 登记认购 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao) - 取消认购 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao) - 确认或拒绝认购付款 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento) - 查询认购 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas) - 登记认购付款 (/zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento) - 接收 Webhooks (/zh-Hans/documentation/escrituracao/introducao/autenticacao_webhooks) - 商业票据书写 (/zh-Hans/documentation/escrituracao/introducao/) - 测试端点 (/zh-Hans/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) - 认证测试 (/zh-Hans/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao) - 密钥交换 (/zh-Hans/documentation/escrituracao/introducao/troca_de_chaves) - 查询资产 (/zh-Hans/documentation/escrituracao/operacoes-ativas/consulta-security) - 查询投资人持仓 (/zh-Hans/documentation/escrituracao/operacoes-ativas/posicao-investidor) - 书写 Webhooks (/zh-Hans/documentation/escrituracao/webhooks-escrituracao) --- # Aditamento URL: /zh-Hans/documentation/escrituracao/aditamento/conceito ## Visão geral Aditamento é o processo de alterar as condições de um título já emitido. Depois que a Nota Comercial foi assinada e emitida, qualquer mudança nas condições pactuadas — repactuar o fluxo de pagamento, substituir uma garantia, incluir ou remover um avalista, corrigir o número da emissão — precisa ser formalizada em um termo aditivo assinado pelas partes. A QI Tech recebe esse pedido via API, valida a elegibilidade do título, calcula o novo fluxo, gera o termo aditivo, cobra a taxa do serviço, coleta as assinaturas e só então aplica as alterações no título. O resultado é um evento rastreável, com `status` próprio, histórico de transições e os documentos assinados disponíveis para download. O integrador inicia o fluxo com uma chamada e acompanha o restante por consulta. As etapas intermediárias — geração do termo, emissão do boleto, envio do envelope de assinatura, aplicação das alterações — são orquestradas internamente pela QI Tech. ## O que pode ser aditado Cada aditamento carrega uma ou mais alterações, no campo `changes`. Os cinco tipos ficam em `changes[].type`: - `financial_flow` (fluxo financeiro) — repactuação do cronograma: novas datas de vencimento, novos valores e/ou nova taxa de juros. - `collateral` (garantia) — inclusão ou remoção de uma garantia do título. - `related_party` (parte relacionada) — inclusão, alteração ou remoção de avalista, devedor solidário, fiel depositário e demais papéis. - `issue_number` (número da emissão) — correção do número da emissão. - `term_clause` (cláusula do termo) — regeração do documento com campos livres preenchidos pelo solicitante. Um mesmo aditamento pode combinar vários tipos. As alterações são aplicadas em conjunto: ou todas valem, ou nenhuma vale. ## Conceitos-chave - **`financial_base_date`** — data em que o aditamento passa a valer e a âncora de todo o cálculo. O saldo devedor é apurado nessa data e o novo fluxo parte dela. Aditamento com data base no passado é recusado, salvo operações com origem de tombamento. - **`outstanding_balance`** (saldo devedor) — calculado internamente na `financial_base_date` e devolvido na simulação, na validação e na consulta. O integrador não precisa calcular saldo devedor do seu lado. - **Fechamento (`closing`)** — em uma repactuação de fluxo, a QI Tech confere se o novo cronograma fecha contra o valor presente do título dentro de uma tolerância. Um fluxo que não fecha faz o aditamento nascer recusado, com o `difference` e a `tolerance` na resposta. - **Termo aditivo** — o documento que formaliza a alteração. Pode ser **gerado pela QI Tech** a partir dos dados do aditamento, ou **enviado pronto pelo integrador** no array `documents`. A escolha muda o caminho que o aditamento percorre (veja [Regras de Negócio](./regras-de-negocio.md)). - **Cobrança** — o aditamento tem uma taxa, cobrada por boleto. O pagamento é o que libera o envio do termo para assinatura. O valor segue a configuração comercial do seu contrato e vem na simulação, em `charge_amount`. - **Envelope de assinatura** — o conjunto de signatários do termo. Os signatários vêm dos grupos de assinatura cadastrados na operação; uma parte relacionada incluída pelo próprio aditamento também pode ser eleita signatária. - **Um aditamento por vez** — um título só admite um aditamento em andamento. Enquanto o anterior não chega a um estado terminal, uma nova criação é recusada com `AMD000031`. ## O ciclo de vida Um aditamento atravessa a esteira uma vez, e cada parada espera por uma coisa só: | `status` | O que está acontecendo | | --- | --- | | `created` | Criado e roteado. Estado transitório. | | `validation_failed` | Recusado na validação. Nada foi cobrado nem assinado. Estado terminal. | | `pending_manual_approval` | O termo foi enviado pronto pelo integrador e aguarda conferência da QI Tech. | | `pending_term_generation` | A QI Tech está gerando o termo aditivo. | | `pending_charge_settlement` | Boleto emitido, aguardando o pagamento da taxa. | | `pending_signature` | Montando e enviando o envelope de assinatura. | | `pending_signature_confirmation` | Envelope enviado, aguardando os signatários. | | `pending_application` | Aplicando as alterações no título. | | `applied` | Alterações aplicadas. Estado terminal. | | `application_failed` | Falha ao aplicar. Estado terminal até intervenção. | | `canceled` | Cancelado ou recusado. O motivo fica em `status_reason`. Estado terminal. | :::info Acompanhamento por consulta Não há webhook dedicado às transições de status do aditamento. Acompanhe pelo endpoint de [consulta](./endpoints/consultar-aditamento.md) — o campo `status_history` traz cada transição com data, ator e motivo. ::: ## Próximos passos - [Regras de Negócio](./regras-de-negocio.md) — elegibilidade, fechamento, assinatura e cancelamento. - [Tipos de Alteração](./tipos-de-alteracao.md) — o formato de `new_value` para cada `type`. - [Simular Aditamento](./endpoints/simular-aditamento.md) — o ensaio, sem criar nada. - [Criar Aditamento](./endpoints/criar-aditamento.md) — o disparo do rito. - [Exemplos](./exemplos.md) — casos completos de ponta a ponta. --- # Baixar Documento URL: /zh-Hans/documentation/escrituracao/aditamento/endpoints/baixar-documento Devolve o conteúdo de um documento do aditamento em base64 — o termo aditivo gerado pela QI Tech, o termo que você enviou, ou a versão assinada. --- ## **Request** ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY /document/ DOCUMENT-KEY MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres | | --- | --- | --- | --- | | `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave do documento (UUID v4), obtida em `documents[].document_key` na [consulta](./consultar-aditamento.md). | 36 | ### **Query Params** | Campo | Tipo | Obrigatório | Padrão | Descrição | | --- | --- | --- | --- | --- | | `is_signed` | boolean | Não | `false` | Quando `true`, devolve a **versão assinada** do documento. | --- ## **Response** STATUS 200 ```json { "document_base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2UvTWVkaWFCb3hbMCAwIDU5NSA4NDJd..." } ``` | Campo | Tipo | Descrição | | --- | --- | --- | | `document_base64` | string | Conteúdo do arquivo em base64. | :::caution A versão assinada só existe depois da assinatura `is_signed=true` em um documento que ainda não foi assinado retorna `AMD000038`. Confira o campo `documents[].signed_file_key` na consulta: ele só é preenchido quando a versão assinada está disponível. ::: --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000017` | Aditamento não encontrado. | | 403 | `AMD000018` | O aditamento não pertence ao seu tenant. | | 404 | `AMD000037` | Documento não encontrado neste aditamento. | | 422 | `AMD000038` | O documento ainda não tem versão assinada. | ## Veja também - [Consultar Aditamento](./consultar-aditamento.md) - [Consultar Signatários](./consultar-signatarios.md) --- # Cancelar Aditamento URL: /zh-Hans/documentation/escrituracao/aditamento/endpoints/cancelar-aditamento Desiste de um aditamento em andamento. O aditamento vai para `canceled` com `status_reason: withdrawn_by_tenant`. --- ## **Request** ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY /cancel MÉTODO PATCH ### **Path Params** | Campo | Tipo | Descrição | Caracteres | | --- | --- | --- | --- | | `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 | ### **Request Body** Nenhum. A requisição não leva corpo. --- ## Quando o cancelamento é aceito | `status` | Cancelável | | --- | --- | | `created` | Sim | | `pending_manual_approval` | Sim | | `pending_term_generation` | Sim | | `pending_charge_settlement` | Sim | | `pending_signature` | Sim | | `pending_signature_confirmation` | Sim | | `pending_application` | **Não** | | `applied` · `canceled` · `validation_failed` · `application_failed` | **Não** | :::caution Ponto sem volta A partir de `pending_application` o cancelamento deixa de ser aceito — a recusa é `AMD000012`, com o status atual na mensagem. Se precisar reverter um aditamento já aplicado, fale com o seu contato comercial na QI Tech: é um procedimento próprio, não uma chamada de API. ::: ## Efeitos fora do aditamento O cancelamento não se limita a mudar o `status`. Ele também: - **Baixa o boleto da taxa**, se houver um em aberto. Um boleto já compensado não é baixado — nesse caso, o estorno segue o seu contrato comercial. - **Cancela o envelope de assinatura**, se o termo já tiver sido enviado. Links de assinatura já distribuídos deixam de funcionar. --- ## **Response** STATUS 200 A resposta é o objeto completo do aditamento, já com `status: canceled`. Response Body ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "status": "canceled", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "amendment_number": 2, "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47", "operation_type": "commercial_paper", "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "created_by": "integration", "created_at": "2026-09-14T10:22:41", "applied_at": null, "envelope_key": null, "signature_method": "certifiqi", "changes": ["..."], "documents": ["..."], "charges": [ { "amendment_charge_key": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f", "charge_status": "canceled", "amount": 500.00, "settled_at": null, "charge_status_history": ["..."] } ], "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }, { "status": "pending_charge_settlement", "status_reason": null, "reason": null, "event_actor": "system", "event_datetime": "2026-09-14T10:23:02" }, { "status": "canceled", "status_reason": "withdrawn_by_tenant", "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T14:08:55" } ] } ``` --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000017` | Aditamento não encontrado. | | 403 | `AMD000018` | O aditamento não pertence ao seu tenant. | | 409 | `AMD000012` | O `status` atual não permite o cancelamento. | ## Veja também - [Consultar Aditamento](./consultar-aditamento.md) - [Regras de Negócio](../regras-de-negocio.md#cancelamento) --- # Consultar Aditamento URL: /zh-Hans/documentation/escrituracao/aditamento/endpoints/consultar-aditamento Dois endpoints de consulta: um devolve o aditamento completo pela chave, outro lista os aditamentos do seu tenant de forma paginada. Como não há webhook dedicado às transições de status do aditamento, a consulta é o caminho para acompanhar o andamento. --- ## Consulta por chave ### **Request** ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres | | --- | --- | --- | --- | | `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 | ### **Response** STATUS 200 A resposta é o objeto completo do aditamento — o mesmo formato devolvido pela [criação](./criar-aditamento.md#response-body-params), agora com os campos preenchidos pelas etapas já percorridas. Response Body — aditamento aguardando o pagamento da taxa ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "status": "pending_charge_settlement", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "amendment_number": 2, "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47", "operation_type": "commercial_paper", "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "created_by": "integration", "created_at": "2026-09-14T10:22:41", "applied_at": null, "previous_financial_key": "b4d1e8a2-3c57-4f9b-8a06-5e2d7c1b9f34", "new_financial_key": null, "envelope_key": null, "signature_method": "certifiqi", "changes": [ { "amendment_change_key": "c9e7a1b3-5d24-4f68-9b0c-3a7e6d5f2c18", "type": "financial_flow", "operation": "modification", "target_key": null, "status": "created", "is_term_signer": false, "applied_at": null, "failure_reason": null, "previous_value": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" } }, "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" } }, "term_wording": null, "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" } ], "financial": { "previous_interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" }, "new_interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" }, "closing_present_value": 152340.55, "closing_difference": 0.00, "closing_tolerance": 0.01 } } ], "documents": [ { "document_key": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "document_type": "amendment_term", "description": null, "template_key": "de1862a0-e196-4329-9ca4-ba5068a78929", "signed_file_key": null, "externally_provided_at": null } ], "charges": [ { "amendment_charge_key": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f", "charge_status": "registered", "charge_payer_type": "issuer", "charge_attempt": 1, "amount": 500.00, "due_date": "2026-09-19", "payer_name": "Emissor Exemplo S.A.", "payer_document_number": "12.345.678/0001-90", "external_charge_key": "4c3d2e1f-9a8b-4756-b342-1e0d9c8b7a65", "digitable_line": "34191.79001 01043.510047 91020.150008 1 96690000050000", "settled_at": null, "charge_status_history": [ { "status": "created", "event_actor": "system", "event_datetime": "2026-09-14T10:23:02" }, { "status": "registration_requested", "event_actor": "system", "event_datetime": "2026-09-14T10:23:03" }, { "status": "registered", "event_actor": "system", "event_datetime": "2026-09-14T10:23:18" } ] } ], "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }, { "status": "pending_term_generation", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }, { "status": "pending_charge_settlement", "status_reason": null, "reason": null, "event_actor": "system", "event_datetime": "2026-09-14T10:23:02" } ] } ``` :::tip Onde está a linha digitável Em `charges[].digitable_line`. Enquanto o aditamento estiver em `pending_charge_settlement`, é o pagamento desse boleto que libera o envio do termo para assinatura. ::: --- ## Consulta paginada ### **Request** ENDPOINT /security_amendment/amendment MÉTODO GET ### **Query Params** | Campo | Tipo | Obrigatório | Padrão | Descrição | | --- | --- | --- | --- | --- | | `security_key` | string (UUID) | Não | — | Filtra os aditamentos de um título específico. | | `page` | integer | Não | `1` | Página desejada. | | `page_size` | integer | Não | `30` | Itens por página. | ### **Response** STATUS 200 :::info Resposta resumida A listagem devolve uma **versão reduzida** de cada aditamento: sem `documents`, `charges`, `status_history`, `envelope_key`, `signature_method` nem as chaves de fluxo financeiro. As alterações vêm sem `previous_value`, `new_value`, `term_wording` e histórico. Para o objeto completo, consulte pela chave. ::: Response Body ```json { "amendment_list": [ { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "status": "pending_charge_settlement", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "amendment_number": 2, "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47", "operation_type": "commercial_paper", "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "created_by": "integration", "created_at": "2026-09-14T10:22:41", "applied_at": null, "changes": [ { "amendment_change_key": "c9e7a1b3-5d24-4f68-9b0c-3a7e6d5f2c18", "type": "financial_flow", "operation": "modification", "target_key": null, "status": "created", "is_term_signer": false, "applied_at": null, "failure_reason": null, "financial": { "closing_present_value": 152340.55, "closing_difference": 0.00, "closing_tolerance": 0.01 } } ] } ], "total_count": 1, "page": 1, "page_size": 30 } ``` | Campo | Tipo | Descrição | | --- | --- | --- | | `amendment_list` | array | Aditamentos da página, em formato reduzido. | | `total_count` | integer | Total de aditamentos que atendem ao filtro. | | `page` | integer | Página devolvida. | | `page_size` | integer | Tamanho da página. | --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000017` | Aditamento não encontrado. | | 403 | `AMD000018` | O aditamento não pertence ao seu tenant. | ## Veja também - [Criar Aditamento](./criar-aditamento.md) - [Consultar Signatários](./consultar-signatarios.md) - [Baixar Documento](./baixar-documento.md) --- # Consultar Signatários URL: /zh-Hans/documentation/escrituracao/aditamento/endpoints/consultar-signatarios Devolve o envelope de assinatura do termo aditivo: quem precisa assinar, quem já assinou e o **link de assinatura** de cada signatário. Use este endpoint enquanto o aditamento está em `pending_signature_confirmation` para saber quem falta e reenviar o link a quem precisa. --- ## **Request** ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY /signers MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres | | --- | --- | --- | --- | | `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 | --- ## **Response** STATUS 200 Response Body ```json { "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce", "status": "pending_signature", "documents": [ { "document_type": "amendment_term", "signers": [ { "name": "Emissor Exemplo S.A.", "document_number": "145.736.070-56", "email": "financeiro@emissor-exemplo.com.br", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "status": "on_signature" }, { "name": "Maria Oliveira", "document_number": "969.698.790-03", "email": "maria.oliveira@exemplo.com.br", "signature_url": "https://sign.qitech.com.br/s/k9Xp1Qa", "status": "signed" } ] } ] } ``` | Campo | Tipo | Descrição | | --- | --- | --- | | `envelope_key` | string (UUID) | Chave do envelope de assinatura. | | `status` | string | Estado do envelope. | | `documents` | array | Documentos do envelope e seus signatários. | | `documents[].signers[].name` | string | Nome do signatário. | | `documents[].signers[].document_number` | string | CPF do signatário. | | `documents[].signers[].email` | string | E-mail para onde o convite foi enviado. | | `documents[].signers[].signature_url` | string | **Link de assinatura** individual. | | `documents[].signers[].status` | string | Estado da assinatura daquele signatário. | :::info Só depois do envelope existir O envelope é criado quando a taxa do aditamento é paga e o termo segue para assinatura. Antes disso, este endpoint retorna `AMD000039`. ::: --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000017` | Aditamento não encontrado. | | 403 | `AMD000018` | O aditamento não pertence ao seu tenant. | | 422 | `AMD000039` | O aditamento ainda não tem envelope de assinatura. | | 500 | `AMD000019` | Falha ao consultar o provedor de assinatura. | ## Veja também - [Consultar Aditamento](./consultar-aditamento.md) - [Baixar Documento](./baixar-documento.md) - [Regras de Negócio](../regras-de-negocio.md#assinatura) --- # Criar Aditamento URL: /zh-Hans/documentation/escrituracao/aditamento/endpoints/criar-aditamento Este endpoint cria o aditamento e dispara o rito. A partir daqui a QI Tech orquestra as etapas seguintes — geração do termo, cobrança da taxa, envio para assinatura e aplicação das alterações — e você acompanha pelo endpoint de [consulta](./consultar-aditamento.md). Valide antes de criar: um título só admite **um aditamento em andamento por vez**, e uma criação recusada no fechamento consome essa vaga até ser cancelada. --- ## **Request** ENDPOINT /security_amendment/amendment MÉTODO POST ### **Request Body** ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "signature_method": "certifiqi", "amendment_number": 2, "changes": [ { "type": "financial_flow", "operation": "modification", "term_wording": "As partes repactuam o cronograma de pagamento conforme abaixo.", "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ] } ``` ### **Request Body Params** | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `security_key` | string (UUID) | Sim | Chave do título a ser aditado. | | `financial_base_date` | string (date) | Sim | Data base em `YYYY-MM-DD`. Âncora do saldo devedor, do novo fluxo e do momento da aplicação. Retroativa é recusada com `AMD000005`. | | `changes` | array | Sim | Mínimo 1 item. Formato de cada tipo em [Tipos de Alteração](../tipos-de-alteracao.md). | | `amendment_key` | string (UUID) | Não | **Chave de idempotência** fornecida por você. Reenviar uma chave já usada retorna `AMD000024`. Quando omitido, a QI Tech gera a chave. | | `signature_method` | string | Não | Por onde o termo é assinado. Valores: `qi_sign`, `certifiqi`. Ausente, vale `qi_sign`. | | `amendment_number` | integer (≥ 1) | Não | Ordinal deste aditamento na vida do título, contando os feitos antes da entrada na plataforma. Ausente, a QI Tech usa a própria contagem de aditamentos aplicados + 1. | | `documents` | array | Não | Documentos anexados. É aqui que você envia o termo pronto — veja abaixo. | ### **Enviar o termo pronto** Por padrão a QI Tech gera o termo aditivo. Se você prefere enviar o seu, inclua um documento do tipo `amendment_term` no array `documents`: ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ "..." ], "documents": [ { "document_type": "amendment_term", "document_name": "termo-aditivo-002.pdf", "document_base64": "JVBERi0xLjQKJeLjz9MK...", "description": "Termo aditivo redigido pelo escritório do emissor" } ] } ``` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `document_type` | string | Sim | Valores: `amendment_term`, `deliberation_evidence`. | | `document_name` | string | Sim | Nome do arquivo. Entre 1 e 255 caracteres. | | `document_base64` | string | Sim | Conteúdo do arquivo em base64. | | `description` | string | Não | Descrição livre. | :::caution O termo enviado muda o caminho Enviar um documento do tipo `amendment_term` faz o aditamento nascer em `pending_manual_approval`: a QI Tech confere o documento antes de seguir para a cobrança. Essa conferência é interna e não tem endpoint no seu contrato — acompanhe pelo `status`. Um documento acima do tamanho máximo é recusado com `AMD000016`. ::: --- ## **Response** STATUS 201 Response Body ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "status": "pending_term_generation", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "amendment_number": 2, "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47", "operation_type": "commercial_paper", "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "created_by": "integration", "created_at": "2026-09-14T10:22:41", "applied_at": null, "previous_financial_key": "b4d1e8a2-3c57-4f9b-8a06-5e2d7c1b9f34", "new_financial_key": null, "envelope_key": null, "signature_method": "certifiqi", "changes": [ { "amendment_change_key": "c9e7a1b3-5d24-4f68-9b0c-3a7e6d5f2c18", "type": "financial_flow", "operation": "modification", "target_key": null, "status": "created", "is_term_signer": false, "applied_at": null, "failure_reason": null, "previous_value": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" } }, "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" } }, "term_wording": "As partes repactuam o cronograma de pagamento conforme abaixo.", "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" } ] } ], "documents": [], "charges": [], "status_history": [ { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }, { "status": "pending_term_generation", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" } ] } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | --- | --- | --- | | `amendment_key` | string (UUID) | Chave única do aditamento. Use-a em todas as consultas. | | `status` | string | Estado atual. Veja o ciclo de vida em [Conceito](../conceito.md#o-ciclo-de-vida). | | `security_key` | string (UUID) | Título aditado. | | `amendment_number` | integer | Ordinal deste aditamento na vida do título. | | `operation_key` | string (UUID) | Operação de origem do título. | | `operation_type` | string | Tipo do instrumento. Exemplo: `commercial_paper`. | | `financial_base_date` | string (date) | Data base do aditamento. | | `outstanding_balance` | number | Saldo devedor apurado na data base. | | `created_by` | string | Quem criou o aditamento. | | `created_at` | string (datetime) | Momento da criação. | | `applied_at` | string (datetime) | Momento da aplicação. `null` enquanto não aplicado. | | `previous_financial_key` | string (UUID) | Fluxo financeiro vigente antes do aditamento. | | `new_financial_key` | string (UUID) | Fluxo resultante. Preenchido na aplicação. | | `envelope_key` | string (UUID) | Envelope de assinatura. Preenchido quando o termo é enviado para assinatura. | | `signature_method` | string | `qi_sign` ou `certifiqi`. | | `changes` | array | As alterações do aditamento, cada uma com status próprio. | | `documents` | array | Documentos do aditamento, incluindo o termo. | | `charges` | array | Cobranças do aditamento. Preenchido quando o boleto é emitido. | | `status_history` | array | Cada transição de status, com ator, motivo e data. | **`changes[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `amendment_change_key` | string (UUID) | Chave única da alteração. | | `type` / `operation` / `target_key` | string | Ecoados da requisição. | | `status` | string | Estado da alteração. | | `is_term_signer` | boolean | Se a parte relacionada foi eleita signatária do termo. | | `applied_at` | string (datetime) | Momento em que esta alteração foi aplicada. | | `failure_reason` | string | Motivo da falha, quando a aplicação não completa. | | `previous_value` | object | Estado anterior ao aditamento. | | `new_value` | object | Conteúdo enviado na requisição. | | `term_wording` | string | Redação específica desta alteração no termo. | | `status_history` | array | Transições desta alteração. | | `financial` | object | Presente apenas em alterações de `financial_flow`. Guarda o antes e o depois do fluxo e o resultado do fechamento. | **`changes[].financial`** | Campo | Tipo | Descrição | | --- | --- | --- | | `previous_interest_rate` | object | Taxa vigente antes do aditamento. | | `new_interest_rate` | object | Taxa resultante. | | `previous_installments` | array | Cronograma anterior. | | `new_installments` | array | Cronograma resultante. | | `closing_present_value` | number | Valor presente usado no fechamento. | | `closing_difference` | number | Diferença apurada. | | `closing_tolerance` | number | Tolerância aplicada. | **`charges[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `amendment_charge_key` | string (UUID) | Chave única da cobrança. | | `charge_status` | string | Estado do boleto. | | `charge_payer_type` | string | Quem é cobrado. | | `charge_attempt` | integer | Número da tentativa de cobrança. | | `amount` | number | Valor da taxa. | | `due_date` | string (date) | Vencimento do boleto. | | `payer_name` | string | Nome do pagador. | | `payer_document_number` | string | Documento do pagador. | | `digitable_line` | string | **Linha digitável do boleto.** | | `external_charge_key` | string (UUID) | Chave do boleto no emissor. | | `settled_at` | string (datetime) | Momento da compensação. | | `charge_status_history` | array | Transições da cobrança. | **`documents[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `document_key` | string (UUID) | Chave do documento. Use-a para [baixar](./baixar-documento.md). | | `document_type` | string | `amendment_term` ou `deliberation_evidence`. | | `description` | string | Descrição livre. | | `template_key` | string (UUID) | Template usado na geração, quando gerado pela QI Tech. | | `signed_file_key` | string | Referência do arquivo assinado. Preenchido após a assinatura. | | `externally_provided_at` | string (datetime) | Preenchido quando o documento foi enviado por você. | **`status_history[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `status` | string | Estado alcançado. | | `status_reason` | string | Motivo estruturado. Valores: `manual_approval_rejected`, `expired`, `withdrawn_by_tenant`, `withdrawn_by_issuer`, `signature_rejected`, `reverted`. | | `reason` | string | Descrição livre do motivo. | | `event_actor` | string | Quem provocou a transição. | | `event_datetime` | string (datetime) | Momento da transição. | --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000001` | Título não encontrado para este tenant. | | 422 | `AMD000002` | Título não está ativo. | | 422 | `AMD000003` | Operação de origem não está finalizada. | | 422 | `AMD000004` | Título já liquidado. | | 422 | `AMD000005` | Data base retroativa. | | 422 | `AMD000006` | Combinação de tipo e operação inexistente. | | 422 | `AMD000007` | `target_key` obrigatório e ausente. | | 422 | `AMD000008` | Garantia não suportada para este tipo de operação. | | 422 | `AMD000014` | Parte relacionada de papel imutável (`issuer`, `investor`). | | 422 | `AMD000015` | Garantia exige documentos que não foram enviados. | | 413 | `AMD000016` | Documento acima do tamanho máximo. | | 409 | `AMD000024` | `amendment_key` já utilizado. | | 422 | `AMD000040` | `is_term_signer` em um tipo que não aceita. | | 422 | `AMD000041` | Signatário do termo sem `signer_group_list`. | | 422 | `AMD000042` | Signatário sem e-mail, exigido pelo provedor de assinatura. | | 422 | `AMD000043` | Parte removida não tem grupo de assinatura. | | 409 | `AMD000044` | Número de emissão já utilizado. | | 409 | `AMD000031` | O título já tem um aditamento em andamento. | O catálogo completo está em [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). ## Veja também - [Validar Aditamento](./validar-aditamento.md) - [Consultar Aditamento](./consultar-aditamento.md) - [Cancelar Aditamento](./cancelar-aditamento.md) - [Tipos de Alteração](../tipos-de-alteracao.md) --- # Simular Aditamento URL: /zh-Hans/documentation/escrituracao/aditamento/endpoints/simular-aditamento Este endpoint devolve o efeito de uma repactuação de fluxo **sem criar nada**: o saldo devedor na data base, o cronograma vigente, o cronograma proposto, o resultado do fechamento e o valor da taxa do aditamento. Use a simulação para apresentar o cenário ao emissor antes de qualquer compromisso. :::info Escopo da simulação A simulação aceita **exatamente uma** alteração, e ela precisa ser do tipo `financial_flow`. Qualquer outro tipo é recusado com `AMD000013`. Para conferir um conjunto completo de alterações, use a [validação](./validar-aditamento.md). ::: --- ## **Request** ENDPOINT /security_amendment/amendment/simulation MÉTODO POST ### **Request Body** ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ { "type": "financial_flow", "operation": "modification", "new_value": { "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ] } ``` ### **Request Body Params** | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `security_key` | string (UUID) | Sim | Chave do título a ser aditado. | | `financial_base_date` | string (date) | Sim | Data base em `YYYY-MM-DD`. Âncora do saldo devedor e do novo fluxo. | | `changes` | array | Sim | Exatamente 1 item, do tipo `financial_flow`. Formato em [Tipos de Alteração](../tipos-de-alteracao.md). | --- ## **Response** STATUS 200 Response Body ```json { "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "closing": { "present_value": 152340.55, "difference": 0.00, "tolerance": 0.01, "passed": true }, "preserved_installments": [ { "installment_number": 1, "due_date": "2026-07-20", "principal_amortization_amount": 48000.00, "interest_amount": 2100.00, "installment_status": "paid", "paid_amount": 50100.00, "paid_at": "2026-07-20T13:42:11" } ], "previous_financial": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-09-20", "principal_amortization_amount": 50000.00, "interest_amount": 2680.00, "installment_status": "pending" } ] }, "new_financial": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-10-20", "principal_amortization_amount": 49210.33, "interest_amount": 3470.22, "installment_status": "pending" }, { "installment_number": 4, "due_date": "2026-11-20", "principal_amortization_amount": 49563.87, "interest_amount": 3116.68, "installment_status": "pending" }, { "installment_number": 5, "due_date": "2026-12-20", "principal_amortization_amount": 49920.40, "interest_amount": 2760.15, "installment_status": "pending" } ] }, "charge_amount": 500.00 } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | --- | --- | --- | | `financial_base_date` | string (date) | Data base usada no cálculo, ecoada da requisição. | | `outstanding_balance` | number | Saldo devedor apurado na data base. | | `closing` | object | Resultado do fechamento contra o valor presente. | | `preserved_installments` | array | Parcelas que **não** entram na repactuação e são mantidas como estão. | | `previous_financial` | object | Taxa e cronograma vigentes antes do aditamento. | | `new_financial` | object | Taxa e cronograma resultantes da proposta. | | `charge_amount` | number | Valor da taxa do aditamento, conforme seu contrato. | **`closing`** | Campo | Tipo | Descrição | | --- | --- | --- | | `present_value` | number | Valor presente do título na data base. | | `difference` | number | Diferença entre o fluxo proposto e o valor presente. | | `tolerance` | number | Diferença máxima aceita. | | `passed` | boolean | `true` quando a diferença está dentro da tolerância. Um fluxo com `false` faria o aditamento nascer em `validation_failed`. | **`installments[]`** (em `preserved_installments`, `previous_financial` e `new_financial`) | Campo | Tipo | Descrição | | --- | --- | --- | | `installment_number` | integer | Número da parcela no cronograma. | | `due_date` | string (date) | Vencimento. | | `principal_amortization_amount` | number | Parcela de amortização do principal. | | `interest_amount` | number | Parcela de juros. | | `installment_status` | string | Estado da parcela. | | `paid_amount` | number | Valor pago. Presente apenas em parcelas com pagamento. | | `paid_at` | string (datetime) | Momento do pagamento. Presente apenas em parcelas pagas. | --- ## **Erros** | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000001` | Título não encontrado para este tenant. | | 422 | `AMD000002` | Título não está ativo. | | 422 | `AMD000003` | Operação de origem não está finalizada. | | 422 | `AMD000004` | Título já liquidado. | | 422 | `AMD000005` | Data base retroativa. | | 422 | `AMD000013` | A simulação aceita apenas uma alteração de `financial_flow`. | | 422 | `AMD000020` | Parcela com pagamento já aplicado não pode ser renegociada. | O catálogo completo está em [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). ## Veja também - [Validar Aditamento](./validar-aditamento.md) - [Criar Aditamento](./criar-aditamento.md) - [Regras de Negócio](../regras-de-negocio.md) --- # Validar Aditamento URL: /zh-Hans/documentation/escrituracao/aditamento/endpoints/validar-aditamento Este endpoint recebe **o mesmo corpo da criação** e devolve o que aconteceria, sem criar nada. Use-o como último passo antes de disparar o rito: ele confere a elegibilidade do título, resolve cada alteração contra o estado atual e informa em qual `status` o aditamento nasceria. Diferente da [simulação](./simular-aditamento.md), a validação aceita o **conjunto completo** de alterações, de qualquer tipo. --- ## **Request** ENDPOINT /security_amendment/amendment/validation MÉTODO POST ### **Request Body** Idêntico ao da [criação](./criar-aditamento.md). ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "signature_method": "certifiqi", "changes": [ { "type": "financial_flow", "operation": "modification", "new_value": { "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" } ] } }, { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001" } ] } ``` --- ## **Response** STATUS 200 Response Body ```json { "valid": true, "financial_base_date": "2026-09-20", "outstanding_balance": 152340.55, "closing": { "present_value": 152340.55, "difference": 0.00, "tolerance": 0.01, "passed": true }, "resolved_changes": [ { "type": "financial_flow", "operation": "modification", "target_key": null, "previous_value": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" } }, "preserved_installments": [ { "installment_number": 1, "due_date": "2026-07-20", "principal_amortization_amount": 48000.00, "interest_amount": 2100.00, "installment_status": "paid" } ] }, { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001", "previous_value": { "collateral_type": "fiduciary_alienation_vehicle", "description": "Veículo dado em alienação fiduciária" } } ], "term_generation": "qi_generated", "next_status": "pending_term_generation" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | --- | --- | --- | | `valid` | boolean | `true` quando o aditamento pode ser criado como enviado. | | `financial_base_date` | string (date) | Data base ecoada da requisição. | | `outstanding_balance` | number | Saldo devedor apurado na data base. | | `closing` | object | Resultado do fechamento. Presente quando há alteração de `financial_flow`. | | `resolved_changes` | array | Cada alteração resolvida contra o estado atual do título. | | `term_generation` | string | Origem do termo. `qi_generated` quando a QI Tech gera; `tenant_supplied` quando você enviou o termo pronto. | | `next_status` | string | O `status` em que o aditamento nasceria se fosse criado agora. | **`resolved_changes[]`** | Campo | Tipo | Descrição | | --- | --- | --- | | `type` | string | Tipo da alteração. | | `operation` | string | Operação da alteração. | | `target_key` | string (UUID) | Registro endereçado, quando houver. | | `previous_value` | object | Estado atual do que será alterado. Ausente quando não há valor anterior (por exemplo, em `addition`). | | `preserved_installments` | array | Apenas em `financial_flow`: parcelas mantidas fora da repactuação. | :::tip Antecipe a aprovação manual O campo `next_status` é o principal motivo para validar antes de criar. Quando ele vem `pending_manual_approval`, o aditamento vai aguardar conferência da QI Tech sobre o termo que você enviou — e o prazo total muda. Veja [Regras de Negócio](../regras-de-negocio.md#o-termo-aditivo). ::: --- ## **Erros** A validação recusa pelos mesmos motivos da criação. Os mais comuns: | Status | Código | Descrição | | --- | --- | --- | | 404 | `AMD000001` | Título não encontrado para este tenant. | | 422 | `AMD000002` | Título não está ativo. | | 422 | `AMD000003` | Operação de origem não está finalizada. | | 422 | `AMD000004` | Título já liquidado. | | 422 | `AMD000005` | Data base retroativa. | | 422 | `AMD000006` | Combinação de tipo e operação inexistente. | | 422 | `AMD000007` | `target_key` obrigatório e ausente. | | 422 | `AMD000008` | Garantia não suportada para este tipo de operação. | | 422 | `AMD000014` | Parte relacionada de papel imutável. | | 409 | `AMD000031` | O título já tem um aditamento em andamento. | O catálogo completo está em [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). ## Veja também - [Criar Aditamento](./criar-aditamento.md) - [Simular Aditamento](./simular-aditamento.md) - [Tipos de Alteração](../tipos-de-alteracao.md) --- # Exemplos URL: /zh-Hans/documentation/escrituracao/aditamento/exemplos Casos completos, do primeiro ensaio ao aditamento aplicado. --- ## 1. Repactuar o fluxo de pagamento O cenário mais comum: o emissor pede mais prazo e as partes acordam uma taxa nova. ### Passo 1 — Simular Antes de qualquer compromisso, veja o efeito no fluxo e quanto custa o aditamento. ``` POST /security_amendment/amendment/simulation ``` ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ { "type": "financial_flow", "operation": "modification", "new_value": { "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ] } ``` Confira `closing.passed` na resposta. Se vier `false`, o fluxo proposto não fecha e o aditamento nasceria recusado — ajuste antes de seguir. ### Passo 2 — Validar Mesmo corpo da criação, sem criar. Confirme o `next_status`. ``` POST /security_amendment/amendment/validation ``` ### Passo 3 — Criar ``` POST /security_amendment/amendment ``` ```json { "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33", "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "signature_method": "certifiqi", "changes": [ { "type": "financial_flow", "operation": "modification", "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ] } ``` ### Passo 4 — Pagar a taxa Consulte o aditamento e pegue a linha digitável em `charges[].digitable_line`. O aditamento fica em `pending_charge_settlement` até a compensação. ``` GET /security_amendment/amendment/7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33 ``` ### Passo 5 — Coletar assinaturas Com a taxa paga, o termo vai para assinatura. Pegue os links: ``` GET /security_amendment/amendment/7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33/signers ``` ### Passo 6 — Acompanhar a aplicação Assinado o termo, o aditamento vai para `pending_application` e é aplicado na `financial_base_date`. Quando chega a `applied`, o campo `applied_at` é preenchido e `new_financial_key` aponta para o fluxo novo. --- ## 2. Substituir uma garantia Remover a garantia antiga e incluir a nova **no mesmo aditamento** — assim as duas alterações valem juntas, e o título nunca fica descoberto. ``` POST /security_amendment/amendment ``` ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001", "term_wording": "Fica liberada a garantia constituída sobre o veículo de placa ABC1D23." }, { "type": "collateral", "operation": "addition", "new_value": { "collateral_type": "fiduciary_alienation_vehicle", "description": "Veículo dado em substituição", "value": 92000.00 } } ] } ``` :::tip Tudo ou nada As alterações de um mesmo aditamento são aplicadas em conjunto. Em uma substituição, isso garante que a liberação da garantia antiga e a constituição da nova acontecem no mesmo ato. ::: --- ## 3. Incluir um avalista que assina o termo A parte incluída pelo aditamento também precisa assinar o termo aditivo — então ela traz o próprio grupo de assinatura. ``` POST /security_amendment/amendment ``` ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "signature_method": "certifiqi", "changes": [ { "type": "related_party", "operation": "addition", "is_term_signer": true, "new_value": { "person_type": "natural", "name": "Maria Oliveira", "document_number": "96969879003", "role_type": "surety", "street": "Avenida Brigadeiro Faria Lima", "number": "1234", "neighborhood": "Itaim Bibi", "city": "São Paulo", "state": "SP", "postal_code": "01451-001", "signer_group_list": [ { "minimum_required_signers": 1, "signers": [ { "name": "Maria Oliveira", "document_number": "969.698.790-03", "email": "maria.oliveira@exemplo.com.br", "is_group_mandatory": true } ] } ] } } ] } ``` :::caution E-mail com CertifiQI Com `signature_method: certifiqi`, o `email` de cada signatário é obrigatório. Sem ele, a criação é recusada com `AMD000042`. ::: --- ## 4. Enviar o termo já redigido Quando o escritório do emissor redige o termo, envie-o na criação. O aditamento entra em conferência da QI Tech antes de seguir. ``` POST /security_amendment/amendment ``` ```json { "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5", "financial_base_date": "2026-09-20", "changes": [ { "type": "issue_number", "operation": "modification", "new_value": { "issue_number": 2 } } ], "documents": [ { "document_type": "amendment_term", "document_name": "termo-aditivo-002.pdf", "document_base64": "JVBERi0xLjQKJeLjz9MK..." } ] } ``` O aditamento nasce em `pending_manual_approval`. Acompanhe pelo `status`: aprovado, ele segue para a cobrança; recusado, vai para `canceled` com `status_reason: manual_approval_rejected`. --- ## 5. Desistir de um aditamento ``` PATCH /security_amendment/amendment/7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33/cancel ``` Sem corpo. Aceito até `pending_signature_confirmation`. O boleto em aberto é baixado e o envelope de assinatura é cancelado. ## Veja também - [Conceito](./conceito.md) - [Regras de Negócio](./regras-de-negocio.md) - [Tipos de Alteração](./tipos-de-alteracao.md) --- # Regras de Negócio — Aditamento URL: /zh-Hans/documentation/escrituracao/aditamento/regras-de-negocio Esta página consolida as invariantes que governam a criação, a assinatura e a aplicação de um aditamento. Consulte-a sempre que as páginas de endpoints citarem um código de erro, um campo ou uma condição que precise de contexto adicional. ## Elegibilidade do título Antes de criar qualquer coisa, a QI Tech confere se o título aceita aditamento. Todas as condições abaixo precisam valer: - O título precisa existir e pertencer ao seu tenant — caso contrário, `AMD000001`. - O título precisa estar **ativo**. Título em outro estado é recusado com `AMD000002`, e a mensagem carrega o estado encontrado. - A operação de origem precisa estar **finalizada** (emitida). Operação ainda em cadastro ou análise é recusada com `AMD000003`. - O título **não pode estar liquidado** — não há o que aditar, e a recusa é `AMD000004`. - O título **não pode ter outro aditamento em andamento**. Um por vez: enquanto o anterior não chega a `applied`, `canceled` ou `validation_failed`, a criação é recusada com `AMD000031`, e a mensagem diz qual aditamento está ocupando o título. ## Data base (`financial_base_date`) A `financial_base_date` é **fornecida pelo integrador** e é a única referência temporal do aditamento. Ela define: - a data em que o saldo devedor (`outstanding_balance`) é apurado; - a data a partir da qual o novo fluxo passa a valer; - o momento em que as alterações são efetivamente aplicadas no título. **Data base retroativa é recusada** com `AMD000005`. A única exceção são operações com origem de tombamento, em que o histórico anterior à entrada na plataforma justifica a retroatividade. Quando a data base é **futura**, o aditamento permanece em `pending_application` após a coleta das assinaturas e é aplicado quando a data chega. Quando é **hoje**, a aplicação ocorre assim que a última assinatura é confirmada. ## Fechamento do fluxo (`closing`) Em alterações de `financial_flow`, a QI Tech confere se o cronograma proposto fecha contra o valor presente do título na data base. O resultado vem no objeto `closing`: | Campo | Significado | | --- | --- | | `present_value` | Valor presente do título na data base. | | `difference` | Diferença entre o fluxo proposto e o valor presente. | | `tolerance` | Diferença máxima aceita. | | `passed` | `true` quando a diferença está dentro da tolerância. | Um fluxo com `passed: false` faz o aditamento nascer diretamente em `validation_failed`: nada é cobrado e nada é enviado para assinatura. Use a [validação](./endpoints/validar-aditamento.md) antes de criar para não gastar uma tentativa. ### A variável livre O cálculo do novo fluxo resolve **uma variável livre**. O que você envia determina o que a QI Tech calcula: - **Enviou apenas datas** (`installments[].due_date`) — os valores das parcelas são recalculados, mantida a taxa vigente. - **Enviou nova taxa** (`interest_rate`) — os valores são recalculados com a taxa nova, mantidas as datas informadas. - **Enviou valores** (`installments[].amount`) — a taxa é derivada. Enviar **taxa e valores juntos** é recusado, porque sobredetermina o sistema. Dentro de uma mesma parcela, `amount` e `principal_amortization_percentage` também são excludentes. ### Parcelas preservadas Envie **apenas a cauda renegociada**. Parcelas já pagas não entram no payload — a QI Tech as preserva automaticamente e as devolve em `preserved_installments` na simulação. Uma parcela **parcialmente paga não pode ser renegociada**: a recusa é `AMD000020`, com o número e o estado da parcela na mensagem. ## O termo aditivo O termo pode nascer de dois jeitos, e a escolha muda o caminho do aditamento. **Gerado pela QI Tech** — o comportamento padrão. Você não envia nenhum documento do tipo `amendment_term` na criação; a QI Tech monta o termo a partir dos dados do aditamento e o aditamento segue direto para a cobrança. **Enviado pronto pelo integrador** — você inclui um documento do tipo `amendment_term` no array `documents` da criação. Nesse caso o aditamento entra em `pending_manual_approval`. :::info Conferência da QI Tech Quando o termo é enviado pronto, a QI Tech confere o documento antes de seguir. Essa etapa é executada internamente pela equipe da QI Tech e **não tem endpoint no seu contrato de integração** — acompanhe pelo `status`. Aprovado, o aditamento segue para a cobrança. Recusado, ele vai para `canceled` com `status_reason: manual_approval_rejected`. ::: Cada alteração aceita ainda o campo `term_wording` (até 10.000 caracteres): o texto que o termo deve carregar para aquela alteração específica, no lugar da redação padrão da plataforma. ## Cobrança O aditamento tem uma taxa de serviço, cobrada por boleto emitido no momento em que o termo fica pronto. O valor segue a configuração comercial do seu contrato e é devolvido na simulação, em `charge_amount`. **O pagamento do boleto é o que libera o envio para assinatura.** Enquanto a compensação não ocorre, o aditamento permanece em `pending_charge_settlement`. A linha digitável fica em `charges[].digitable_line` na consulta. Boleto vencido sem pagamento não trava o aditamento em definitivo: a QI Tech substitui o boleto vencido por um novo quando o fluxo é retomado. Um boleto dentro do prazo continua válido, com a mesma linha digitável. ## Assinatura Com a taxa paga, a QI Tech monta o envelope e o envia aos signatários. - Os signatários vêm dos **grupos de assinatura cadastrados na operação**. Uma operação sem grupo de assinatura ativo para o emissor é recusada com `AMD000022`. - Uma **parte relacionada incluída pelo próprio aditamento** pode ser eleita signatária do termo com `is_term_signer: true`. Nesse caso ela precisa trazer `signer_group_list` no `new_value` — sem isso, `AMD000041`. - Em remoções, os grupos vêm do cadastro da operação. Uma parte sem grupo de assinatura não pode assinar: `AMD000043`. - `is_term_signer` só existe em alterações do tipo `related_party` — em qualquer outro tipo, `AMD000040`. - O método de assinatura vai em `signature_method` na criação. Quando omitido, vale `qi_sign`. Com `certifiqi`, **o e-mail do signatário é obrigatório** — sem ele, `AMD000042`. Consulte o andamento pelo endpoint de [signatários](./endpoints/consultar-signatarios.md), que devolve quem já assinou, quem falta e o link de assinatura de cada um. ## Aplicação Coletadas as assinaturas — e chegada a data base — a QI Tech aplica as alterações no título. A aplicação é **conjunta**: as alterações de um mesmo aditamento valem todas ou nenhuma. Cada alteração carrega o próprio `status` e o `applied_at`. Uma alteração que falha registra o motivo em `failure_reason` e leva o aditamento para `application_failed`. :::caution Alterações de `term_clause` Uma alteração do tipo `term_clause` não altera dado estruturado no título — o efeito dela vive na redação do termo assinado. Ela é registrada e aplicada como as demais, mas não produz mudança consultável fora do documento. ::: ## Cancelamento Você pode desistir do aditamento enquanto ele não entrou em aplicação. O cancelamento é aceito nos status `created`, `pending_manual_approval`, `pending_term_generation`, `pending_charge_settlement`, `pending_signature` e `pending_signature_confirmation`. A partir de `pending_application` o cancelamento **não é mais aceito** — a recusa é `AMD000012`. Nos estados terminais (`applied`, `canceled`, `validation_failed`) também não. O cancelamento tem dois efeitos fora do aditamento: **baixa o boleto em aberto**, se houver, e **cancela o envelope de assinatura**, se já tiver sido enviado. Um boleto já pago não é baixado. O motivo registrado é `withdrawn_by_tenant`, visível em `status_history[].status_reason`. ## Veja também - [Conceito](./conceito.md) - [Tipos de Alteração](./tipos-de-alteracao.md) - [Criar Aditamento](./endpoints/criar-aditamento.md) - [Exemplos](./exemplos.md) - [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Tipos de Alteração URL: /zh-Hans/documentation/escrituracao/aditamento/tipos-de-alteracao Cada item do array `changes` descreve uma alteração. Esta página detalha o formato de `new_value` para cada `type`. ## O envelope da alteração Todos os tipos compartilham a mesma estrutura externa: ```json { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001", "new_value": null, "term_wording": "Texto livre para o termo, no lugar da redação padrão.", "is_term_signer": false } ``` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `type` | string | Sim | Dimensão alterada. Valores: `financial_flow`, `collateral`, `related_party`, `issue_number`, `term_clause`. | | `operation` | string | Sim | Valores: `addition`, `modification`, `removal`. Nem toda combinação existe — veja a matriz abaixo. | | `target_key` | string (UUID) | Condicional | Registro existente endereçado pela alteração. Obrigatório em `modification` e `removal` de `collateral` e `related_party`. | | `new_value` | object | Condicional | Conteúdo da alteração. O formato depende do `type`. Ausente em `removal`. | | `term_wording` | string | Não | Até 10.000 caracteres. Redação específica que o termo deve carregar para esta alteração. | | `is_term_signer` | boolean | Não | Apenas em `related_party`: a parte endereçada assina o termo aditivo. | ## Matriz de combinações | `type` | `addition` | `modification` | `removal` | | --- | --- | --- | --- | | `financial_flow` | — | Sim, sem `target_key` | — | | `collateral` | Sim, sem `target_key` | Sim, `target_key` obrigatório | Sim, `target_key` obrigatório | | `related_party` | Sim, sem `target_key` | Sim, `target_key` obrigatório | Sim, `target_key` obrigatório | | `issue_number` | — | Sim, sem `target_key` | — | | `term_clause` | Sim | Sim | Sim — nenhum exige `target_key` | Combinação inexistente é recusada com `AMD000006`, e a mensagem carrega o par tentado. `target_key` faltando onde é exigido retorna `AMD000007`. --- ## `financial_flow` — repactuação do fluxo Reperfilamento do cronograma de pagamento. Aceita apenas `modification`. ```json { "type": "financial_flow", "operation": "modification", "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" }, "installments": [ { "installment_number": 3, "due_date": "2026-10-20" }, { "installment_number": 4, "due_date": "2026-11-20" }, { "installment_number": 5, "due_date": "2026-12-20" } ] } } ``` ### `new_value` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `interest_rate` | object | Condicional | Nova taxa. Ausente, mantém a taxa vigente do título. | | `installments` | array | Condicional | Somente a cauda renegociada. Mínimo 1 item. | Pelo menos um dos dois precisa estar presente. **`interest_rate`** | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `interest_base` | string | Sim | Base de contagem. Valores: `calendar_days`, `calendar_days_365`, `workdays`. | | `annual_rate` | number | Condicional | Taxa anual. | | `monthly_rate` | number | Condicional | Taxa mensal. | | `daily_rate` | number | Condicional | Taxa diária. | Informe **exatamente uma** entre `annual_rate`, `monthly_rate` e `daily_rate`. **`installments[]`** | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `installment_number` | integer (≥ 1) | Sim | Número da parcela no cronograma do título. | | `due_date` | string (date) | Sim | Novo vencimento, em `YYYY-MM-DD`. | | `amount` | number (> 0) | Não | Novo valor da parcela. | | `principal_amortization_percentage` | number | Não | Percentual de amortização do principal. | :::caution Uma variável livre por vez `amount` e `principal_amortization_percentage` são **excludentes** dentro da mesma parcela. E enviar `interest_rate` junto com `amount` nas parcelas sobredetermina o cálculo e é recusado — escolha o que a QI Tech deve calcular. ::: Parcelas já pagas não entram no array; a QI Tech as preserva. Uma parcela parcialmente paga não pode ser renegociada (`AMD000020`). --- ## `collateral` — garantias Inclusão ou remoção de garantia. Disponível apenas para operações do tipo `commercial_paper` e `debenture` — em qualquer outro tipo, `AMD000008`. **Inclusão** — o `new_value` carrega a garantia completa, no mesmo formato aceito no cadastro da operação. O campo `collateral_type` discrimina o formato: ```json { "type": "collateral", "operation": "addition", "new_value": { "collateral_type": "fiduciary_alienation_vehicle", "description": "Veículo dado em alienação fiduciária", "value": 85000.00 } } ``` **Remoção** — endereça a garantia existente e não leva `new_value`: ```json { "type": "collateral", "operation": "removal", "target_key": "a1b2c3d4-0000-4000-8000-000000000001" } ``` ### Tipos de garantia aceitos `bank_surety` · `contract` · `fiduciary_alienation_aircraft` · `fiduciary_alienation_artwork` · `fiduciary_alienation_equipment` · `fiduciary_alienation_property` · `fiduciary_alienation_securities` · `fiduciary_alienation_vehicle` · `fiduciary_assignment_shares` · `guarantor` · `insurance` · `monitoring_guarantee` · `mortgage_property` · `mortgage_ship` · `surety` · `vehicle_stock` O formato de cada tipo é o mesmo do [cadastro de garantia](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) na emissão. Garantias que exigem documentos precisam trazê-los — a falta é recusada com `AMD000015`. --- ## `related_party` — partes relacionadas Inclusão, alteração ou remoção de avalista, devedor solidário, fiel depositário e demais papéis. ```json { "type": "related_party", "operation": "addition", "is_term_signer": true, "new_value": { "person_type": "natural", "name": "Maria Oliveira", "document_number": "96969879003", "role_type": "surety", "street": "Avenida Brigadeiro Faria Lima", "number": "1234", "neighborhood": "Itaim Bibi", "city": "São Paulo", "state": "SP", "postal_code": "01451-001", "signer_group_list": [ { "minimum_required_signers": 1, "signers": [ { "name": "Maria Oliveira", "document_number": "969.698.790-03", "email": "maria.oliveira@exemplo.com.br", "is_group_mandatory": true } ] } ] } } ``` ### Papéis (`role_type`) `cosigner` · `fiduciary_debtor` · `solidary_debtor` · `surety` :::caution Papéis imutáveis `issuer` e `investor` **não podem ser aditados** — a recusa é `AMD000014`. Emissor e investidor são determinados na emissão do título. ::: ### Eleger a parte como signatária Com `is_term_signer: true`, a parte assina o termo aditivo: - Em `addition` e `modification`, o `new_value` precisa trazer `signer_group_list` — sem ele, `AMD000041`. - Em `removal`, os grupos vêm do cadastro da operação. Parte sem grupo de assinatura não pode assinar: `AMD000043`. - Com `signature_method: certifiqi`, o `email` de cada signatário é **obrigatório** — sem ele, `AMD000042`. - `is_term_signer` em qualquer outro `type` é recusado com `AMD000040`. --- ## `issue_number` — número da emissão Correção do número da emissão. Aceita apenas `modification`. ```json { "type": "issue_number", "operation": "modification", "new_value": { "issue_number": 2 } } ``` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `issue_number` | integer (≥ 1) | Sim | Novo número da emissão. | Um número já usado por outra operação ativa do mesmo emissor é recusado com `AMD000044`. --- ## `term_clause` — cláusulas do termo Regeração do documento com campos livres. Não existe cláusula endereçável: o que muda é o template e o mapa de campos que ele consome. ```json { "type": "term_clause", "operation": "modification", "new_value": { "document_type": "commercial_paper", "extra_fields": { "clausula_decima": "As partes acordam que...", "foro_eleito": "Comarca de São Paulo - SP" } } } ``` | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `document_type` | string | Sim | Valores: `commercial_paper`, `adhesion_term`. | | `extra_fields` | object | Sim | Mapa plano de texto para texto, consumido pelo template. Mínimo 1 chave. | | `template_key` | string (UUID) | Não | Template específico a ser usado. | :::info Efeito documental Uma alteração de `term_clause` não muda dado estruturado no título — o efeito dela vive na redação do termo assinado. ::: ## Veja também - [Regras de Negócio](./regras-de-negocio.md) - [Criar Aditamento](./endpoints/criar-aditamento.md) - [Exemplos](./exemplos.md) --- # 非常规摊还 URL: /zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/conceito ## 概述 非常规摊还是指在常规还款计划之外减少某笔发行未偿余额的过程 — 例如发行人提前还款、在到期日之前结清分期，或对部分债务进行再融资。QI Tech 通过 API 接收该请求，校验金额并登记该事件以供后续清算，同时不影响在每个 `due_date`（到期日）生成的常规摊还。 典型场景包括发行人提前结清、提前支付一期或多期分期，以及部分再融资操作。在所有这些情形中，集成方按需发起流程，说明正在摊还哪一期（或哪几期）分期以及金额是多少。 每当你需要在常规还款计划之外变更未偿余额时，就会使用本 API。其结果始终是一个可追溯的事件，具备自身的 `status` 和财务记录。创建是 fire-and-forget 的：QI Tech 在内部编排清算、终结与取消，集成方无需调用额外的端点。 ## 常规摊还与非常规摊还 常规摊还由 QI Tech 自动生成：在每个 `due_date`（到期日），分期清算流程会在内部创建，无需集成方任何操作。而非常规摊还始终是按需发起的，需通过显式的 API 调用。两者并存 — 登记一笔非常规摊还既不会取消也不会替代尚未到期的常规摊还；它只是在该资产上新增一个清算事件。 ## 摊还类型 `amortization_type` 字段支持以下七种类型。所有类型都通过 `installment_list` 指定目标分期；类型只决定 `amount` 在这些分期之间的分配方式： - `equal_amount`（按比例分摊）— 在所选分期之间按比例分配所提供的金额，先逾期分期，再未来分期。 - `first_installments`（前若干期）— 将金额依次应用于所选分期中（按到期日排序）的前 N 期，直至金额用尽。 - `present_amount`（现值）— 由集成方选择分期，并可提供 `total_discount`；分配顺序为利息 → 罚金 → 本金。 - `matured_installments`（已到期分期）— 将金额仅应用于已经到期的分期。 - `early_amortization`（提前摊还）— 提前支付某笔未来分期。 - `nominal_amount`（名义价值）— 按名义价值（到期日的本金 + 利息）结清未来分期，不折现到现值；不接受已逾期的分期。 - `full_amortization`（全额结清）— 将 `amount` 按现值比例分配到**所有**所选分期，不做级联，并在清算时全额结清每一期，即使所得份额低于其现值；差额记录为每期的 `discount_amount`。 只有 `early_amortization` 和 `nominal_amount` 允许部分支付 — 其余五种都要求在容差范围内全额覆盖所声明的金额。 ## 关键概念 - **`event_conciliation`** — 对应某一期具体分期的对账事件。负责证券分期的付款和/或非常规摊还的对账行为。 - **`reference_date`** — 每次创建时由调用方提供的参考日期（必须与结清日期一致）。QI Tech 从不使用 `date.today()`：所有与日期相关的逻辑（到期分类、现值预测、区分已逾期与未到期分期）均以该字段为起点。 - **现值** — 在内部计算，并在事件创建过程中被消费。集成方无需在自己这一侧计算现值。 - **容差（`tolerance_amount`）** — 清算金额与预期分期金额之间可接受的最大差额。默认为 R$ 0.01。超出容差的差额会导致清算被拒绝。 - **派生的部分支付状态** — 当 `paid_amount > 0` 且 `paid_amount < expected_amount` 时，该分期被视为部分已付。这里没有新增状态：该状态是从 `paid_amount` 和 `expected_amount` 两列**派生**出来的。`pending_conciliation` 状态同时涵盖"尚未支付"和"部分支付"两种情况；只有当累计金额在容差范围内覆盖了预期金额时，才会出现 `paid`。 ## 后续步骤 请继续阅读[集成路线图](../roteiro-integracao/roteiro-integracao-padrao.md)，了解逐步流程。若需了解由新操作回购未结非常规摊还的场景，请参阅[回购式摊还](./recompra-de-operacao.md)。 --- # 查询非常规摊还 URL: /zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao 本端点通过键值（`extraordinary_event_conciliation_key`）返回某笔特定的非常规摊还。可用它跟踪事件的对账状态 — 从 `pending_conciliation`（尚未支付或部分支付）一直到由 QI Tech 内部编排确定的终态（`paid` 或 `canceled`）。 该查询与日期无关，且不会触发任何状态转换：它只反映事件及其每一期关联分期的当前状态。 --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event/ EXTRAORDINARY-EVENT-CONCILIATION-KEY 方法 GET ### **Path Params** | 字段 | 类型 | 是否必填 | 描述 | |----------------------------------------|----------------|---------|------------------------------------------| | `extraordinary_event_conciliation_key` | string (UUID) | 是 | 待查询的非常规摊还事件的唯一键值。 | 调用示例： ``` 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** | 字段 | 类型 | 描述 | |----------------------------------------|-----------------|------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key` | string (UUID) | 所查询的非常规摊还事件的键值。 | | `security_key` | string (UUID) | 该事件所属资产（`security`）的键值。 | | `investment_key` | string (UUID) | 该事件目标投资的键值。 | | `amortization_type` | string | 该事件的摊还类型 — 回显创建时使用的值。 | | `total_expected_amount` | number | 该事件的预期总金额（在各分期之间分配的总额），以 BRL 计。 | | `total_discount_amount` | number | 已应用的折扣总额。仅在 `present_amount` 时不为零。 | | `total_paid_amount` | number | 该事件已完成对账的金额（以 BRL 计）。尚无付款确认时为 `0`；部分支付时 `> 0`。 | | `status` | string | 事件的当前状态：`pending_conciliation`、`paid` 或 `canceled`。 | | `reference_date` | string (date) | 创建时提供的参考日期。 | | `due_date` | string (date) | 创建时提供的目标清算日期。 | | `paid_at` | string (date) | 该事件完成清算的日期。在状态变为 `paid` 之前为 `null`。 | | `event_conciliation_list` | array | 该事件的 `event_conciliation`（每期分期的对账事件）列表。**[event_conciliation_list 对象](#event_conciliation_list-对象)**。 | ### **event_conciliation_list 对象** | 字段 | 类型 | 描述 | |-----------------------------|-----------------|---------------------------------------------------------------| | `event_conciliation_key` | string (UUID) | 分期对账事件（`event_conciliation`）的键值。 | | `installment_key` | string (UUID) | 受该对账事件影响的分期的键值。 | | `event_conciliation_status` | string | 分期对账事件的当前状态（`pending_conciliation`、`paid`、`canceled`）。 | | `event_conciliation_type` | string | `event_conciliation` 的类型。由本流程创建的事件恒为 `extraordinary_event`。 | :::info `status`（以及每期分期的 `event_conciliation_status`）反映的是查询时刻的当前状态。转为 `paid` 或 `canceled` 由 QI Tech 的内部编排完成 — 集成方无需为此调用任何端点。 ::: --- ## **错误** | 错误码 | HTTP | 含义 | |------------|------|-------------------------------------------------------------------------| | EVC100011 | 404 | 未找到与所提供的 `extraordinary_event_conciliation_key` 对应的非常规摊还。 | 完整的处理方案请参阅[错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros)。 --- ## **另请参阅** - [创建非常规摊还](./criar-amortizacao.md) - [模拟非常规摊还的现值](./simular-valor-presente.md) - [概念](../conceito.md) - [集成路线图](../../roteiro-integracao/roteiro-integracao-padrao.md) - [业务规则](../regras-de-negocio.md) - [示例](../exemplos.md) --- # 创建非常规摊还 URL: /zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao 本端点针对某笔发行的一期或多期 `installment` 创建非常规摊还。event-conciliation-service 会将这些分期归入单个非常规摊还事件，按所提供的 `amortization_type` 分配所声明的 `amount`，并通过 security-service 获取现值 — 集成方无需在自己这一侧计算现值。`reference_date` 由调用方在非常规摊还请求中提供，是本服务在划分逾期分期和进行按比例折现时使用的唯一时间基准。 --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event 方法 POST ### **Request Body** `installment_list`（`installment_number` 数组，整数 ≥ 1）对所有类型均为必填：它指定目标分期，`amortization_type` 则决定 `amount` 在这些分期之间的分配方式。`installment_list` 中提交的数字会由服务与对应 `security` 的 `installment_number` 进行解析匹配。 示例 — `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] } ``` 示例 — `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", "installment_list": [1, 2, 3, 4] } ``` 示例 — `nominal_amount`（未来分期按名义价值结清）： ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "nominal_amount", "amount": 18670.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [3, 4] } ``` ### **Request Body Params** | 字段 | 类型 | 是否必填 | 描述 | |---------------------------|------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | 是 | 将被摊还的资产（`security`）的唯一键值。 | | `investment_key` | string (UUID) | 是 | 目标投资的键值。security-service 在计算现值时以此作为按比例分配的基准。 | | `amortization_type` | string | 是 | 分配策略。取值：`equal_amount`、`first_installments`、`present_amount`、`matured_installments`、`early_amortization`、`nominal_amount`、`full_amortization`。 | | `amount` | number | 是 | 待摊还的总金额（以 BRL 计）。按 `amortization_type` 在所选分期之间进行分配。 | | `reference_date` | string (date) | 是 | 参考日期，格式为 `YYYY-MM-DD`。**由调用方提供** — 服务将其作为"今天"，用于划分逾期分期并对现值进行按比例折现。 | | `due_date` | string (date) | 是 | 目标清算日期（通常与 `reference_date` 相同）。 | | `installment_list` | 整数数组（≥ 1） | 是 | 目标分期的 `installment_number` 列表（不是 UUID），`minItems: 1`。对所有类型均为必填 — 省略时返回 `EVC100002`。服务会将每个数字与该 `security` 的 `installment_number` 进行匹配；不存在的数字会返回 `EVC000007`。旧版 `installment_key_list` 已移除 — 仍提交该字段的客户端会收到 `QIT000001`（400）。 | | `total_discount` | number | 否 | 仅与 `present_amount` 搭配使用 — 按利息 → 罚金 → 本金的顺序分配折扣。 | | `number_of_installments` | integer | 条件必填 | 使用 `first_installments` 时必填：所选分期中（按到期日）有多少期获得金额。 | --- ## **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** | 字段 | 类型 | 描述 | |---------------------------------------|-----------------|----------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key`| string (UUID) | 所创建的非常规摊还总事件的键值。 | | `security_key` | string (UUID) | 资产键值 — 回显提交的值。 | | `amortization_type` | string | 所选的摊还类型 — 回显提交的值。 | | `total_expected_amount` | number | 由所选类型的引擎在各 `event_conciliation`（分期对账事件）之间分配的总额。 | | `total_discount_amount` | number | 已应用的折扣总额。仅在 `present_amount` 时不为零。 | | `status` | string | 非常规事件的初始状态。创建时恒为 `pending_conciliation`。 | | `reference_date` | string (date) | 请求中提交的参考日期（必须与结清日期一致）。 | | `due_date` | string (date) | 请求中提交的目标清算日期。 | | `event_conciliation_list` | array | 所生成的 `event_conciliation`（分期对账事件）列表。**[event_conciliation_list 对象](#event_conciliation_list-对象)**。 | ### **event_conciliation_list 对象** | 字段 | 类型 | 描述 | |--------------------------|-----------------|-------------------------------------------------------------| | `event_conciliation_key` | string (UUID) | 分期对账事件（`event_conciliation`）的键值。 | | `installment_key` | string (UUID) | 受该对账事件影响的分期的键值。 | | `expected_amount` | number | 分配引擎分配给该分期对账事件的金额。 | | `discount_amount` | number | 分配给该分期对账事件的 `total_discount` 份额（`present_amount`），或该分期现值与所得份额之差（`full_amortization`）。 | | `due_date` | string (date) | 关联分期的到期日。 | | `status` | string | 分期对账事件的初始状态。创建时恒为 `pending_conciliation`。 | | `event_conciliation_type`| string | `event_conciliation` 的类型。由本流程创建的分期对账事件恒为 `extraordinary`。 | --- ## **错误** | 错误码 | HTTP | 含义 | |------------|------|---------------------------------------------------------------------------------------------------------| | EVC100001 | 400 | `amortization_type` 无效。请使用七个受支持取值之一。 | | EVC100002 | 400 | 对所有摊还类型而言，`installment_list` 为必填且不得为空。 | | EVC100003 | 400 | 使用 `first_installments` 时，`number_of_installments` 为必填。 | | EVC100004 | 400 | 所提供的某期分期不属于目标 `security`。 | | EVC000007 | 404 | `installment_list` 中的某个整数与该 `security` 的任何 `installment_number` 都不匹配（`InstallmentNumberNotFound`）。 | | QIT000001 | 400 | Schema 校验失败 — 例如提交了已移除的旧版 `installment_key_list`，或 `installment_list` 中某项不是 ≥ 1 的整数。 | | EVC100005 | 400 | `amount` 不足以覆盖所有选中的分期（不适用于 `early_amortization`）。 | | EVC100006 | 400 | `total_discount` 超过所选分期现值之和。 | | EVC100007 | 400 | 对 `matured_installments` 而言，所选分期必须全部已逾期。 | | EVC100008 | 400 | 该分期已存在一笔待处理的非常规摊还 — 请先取消后再创建新的。 | | EVC100013 | 424 | Security API 不可用（Failed Dependency）。属临时性问题 — 恢复后重试。 | | EVC100015 | 400 | `early_amortization` 要求 `installment_list` 中恰好有 1 期分期。 | | EVC100016 | 400 | `early_amortization` 的目标分期不得已逾期。 | | EVC100017 | 400 | 在 `early_amortization` 中，`amount` 必须小于等于该分期的现值。 | | EVC100030 | 400 | 在 `nominal_amount` 中，所选分期必须全部为未来分期（在 `reference_date` 未逾期）。 | | EVC100031 | 400 | 在 `nominal_amount` 中，`amount` 必须小于等于所选分期的名义价值之和。 | | EVC100032 | 400 | 没有任何所选分期会获得正的 `expected_amount` — 不会创建该事件。 | | EVC100033 | 400 | 已分配的 `expected_amount` 之和与所声明的 `amount` 相差超过 R$ 0.01。 | | EVC100034 | 400 | 某一所选分期的 `expected_amount` 将为零 — 请只选择 `amount` 能覆盖的分期。 | | EVC100035 | 400 | `amount` 超过所选分期现值之和（按现值定价的类型）。 | 完整的处理方案请参阅[错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros)。 --- ## **另请参阅** - [模拟非常规摊还的现值](./simular-valor-presente.md) - [查询非常规摊还](./consultar-amortizacao.md) - [概念](../conceito.md) - [集成路线图](../../roteiro-integracao/roteiro-integracao-padrao.md) - [业务规则](../regras-de-negocio.md) - [示例](../exemplos.md) --- # 模拟特别摊销现值 URL: /zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente 本端点用于模拟 `present_amount` 类型的特别摊销，但不会创建任何事件——它是纯计算，没有任何副作用。服务会根据 `installment_list` 中指定的分期，计算并返回将要创建的特别事件的总 `amount`（现值），以及每个分期对应的 `event_conciliation`（`extraordinary` 类型）的现值——集成方无需在自己一侧计算现值。 请求中不发送 `amortization_type`：由于这是现值模拟，类型始终为 `present_amount`。`amount` 也不发送——它是计算的结果。`reference_date` 由调用方提供，是服务用于判定逾期分期并按比例（pro-rata）折算现值的唯一时间参考；在模拟中，`due_date` 被视为等于 `reference_date`。 响应即为可直接使用的创建请求体：只需移除仅作展示用途的 `event_conciliation_list` 字段，再将其作为[创建特别摊销](./criar-amortizacao)的请求体发送，即可执行所模拟的摊销。 --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event/present_value_simulation METHOD POST ### **Request Body** ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "reference_date": "2026-04-24", "installment_list": [1, 2] } ``` ### **Request Body Params** | 字段 | 类型 | 必填 | 说明 | |--------------------|--------------------------|------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | 是 | 将被模拟摊销的资产（`security`）的唯一键。 | | `investment_key` | string (UUID) | 是 | 目标投资的键。用作现值计算的比例基础。 | | `reference_date` | string (date) | 是 | `YYYY-MM-DD` 格式的参考日期。**由调用方提供**——服务将其作为"今天"来判定逾期分期并应用现值的按比例折算。在模拟中也用作 `due_date`。 | | `installment_list` | array of integers (≥ 1) | 是 | 目标分期的 `installment_number` 列表（不是 UUID），`minItems: 1`。服务会将每个编号与 `security` 的 `installment_number` 进行匹配；不存在的编号返回 `EVC000007`。 | 与创建不同，`amortization_type`、`amount` 和 `due_date` **不需要发送**：类型始终为 `present_amount`，`amount` 由服务计算，`due_date` 被视为等于 `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** | 字段 | 类型 | 说明 | |---------------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | 资产键——回显所发送的值。 | | `investment_key` | string (UUID) | 目标投资键——回显所发送的值。 | | `amortization_type` | string | 始终为 `present_amount`——由服务填充，用于组成创建请求体。 | | `amount` | number | 为特别事件计算出的总现值（等于 `event_conciliation_list` 中各 `amount` 之和）。 | | `reference_date` | string (date) | 参考日期——回显所发送的值。 | | `due_date` | string (date) | 目标结算日期——等于所发送的 `reference_date`。 | | `installment_list` | array of integers | 目标分期——回显所发送的值。 | | `event_conciliation_list` | array | 将要生成的各分期 `event_conciliation`（`extraordinary` 类型）的现值。**仅供展示——不属于创建请求体。** **[Object event_conciliation_list](#object-event_conciliation_list)**。 | :::info `event_conciliation_list` 字段**仅用于展示**每个分期的现值模拟结果——**不得**包含在特别事件的创建请求体中。要执行所模拟的摊销，请移除 `event_conciliation_list` 后，将响应作为[创建特别摊销](./criar-amortizacao)的请求体发送。 ::: ### **Object event_conciliation_list** | 字段 | 类型 | 说明 | |----------------------|---------|------------------------------------------------------------------------------------------------| | `installment_number` | integer | 此对账事件所对应分期的编号（`installment_number`）。 | | `amount` | number | 为该分期的 `event_conciliation`（`extraordinary` 类型）计算出的现值。 | --- ## **Errors** | 代码 | HTTP | 含义 | |------------|------|---------------------------------------------------------------------------------------------------------------------------| | EVC100002 | 400 | `installment_list` 为必填且不能为空。 | | EVC100004 | 400 | 某个所提供的分期不属于目标 `security`。 | | EVC000007 | 404 | `installment_list` 中的某个整数与 `security` 的任何 `installment_number` 都不匹配（`InstallmentNumberNotFound`）。 | | QIT000001 | 400 | Schema 校验失败——例如 `installment_list` 的某项不是 ≥ 1 的整数。 | | EVC100008 | 400 | 该分期已存在待处理的特别摊销——请先取消，再进行模拟/创建。 | | EVC100013 | 424 | 依赖服务暂时不可用（Failed Dependency）。为暂时性问题——恢复后请重试。 | `EVC100005`（`amount` 不足）不适用于模拟——`amount` 由服务计算，无需发送。 完整的错误处理请参阅[错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros)。 --- ## **See also** - [创建特别摊销](./criar-amortizacao) - [查询特别摊销](./consultar-amortizacao) - [概念](../conceito) - [集成指南](../../roteiro-integracao/roteiro-integracao-padrao) - [业务规则](../regras-de-negocio) - [示例](../exemplos) --- # 示例 — 非常规摊还 URL: /zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/exemplos 本页给出两个创建场景。集成方的交互是 **fire-and-forget** 的：只需发起创建调用，QI Tech 会在内部编排清算、终结与取消。不存在面向租户、专门对应非常规 `event_conciliation` 状态转换的 webhook；操作生效的确认通过底层操作已有的报表与 webhook 观察（例如 `commercial_paper.operation_status_change`）。 ## 场景 1：某期分期的部分提前结清（early_amortization） 覆盖单笔未来分期，允许部分支付。 `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] } ``` 响应：`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" } ] } ``` 收到该 201 之后，集成方这一侧的集成工作即告完成。当 R$ 1.500,00 的付款到达对应的清算账户时，QI Tech（account-liquidation-api）会在内部清算该分期对账事件并更新 `paid_amount`；当累计金额覆盖 `total_expected_amount - tolerance_amount` 时，父事件转为 `paid`。若付款未到账，该事件会由 security-service 的每日 settlement 例行任务取消或终结。 ## 场景 2：带折扣的全额结清（present_amount，2 期分期） 创建一笔带合并折扣、覆盖两期分期的摊还。 `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 } ``` 响应 `201 Created` — 会生成两个分期对账事件，其金额按 `present_amount` 引擎的规则分配（利息 → 罚金 → 本金）。完整的响应结构请参阅[创建非常规摊还](./endpoints/criar-amortizacao.md)。 收到 201 之后，集成方的交互与场景 1 相同：QI Tech 会在相应付款到账时清算每个分期对账事件，若金额未在 settlement 窗口内到达，则在内部终结或取消该事件。 ## 场景 3：未来分期按名义价值结清（nominal_amount） 发行人希望在到期前结清第 3 期和第 4 期分期，按每期的名义价值（到期日的本金 + 利息）支付，不做现值折现。`reference_date` 早于两期的到期日。 ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "nominal_amount", "amount": 18670.00, "reference_date": "2026-02-08", "due_date": "2026-06-06", "installment_list": [3, 4] } ``` 响应 `201 Created` — 每期分期生成一个分期对账事件，`expected_amount` 等于各期的名义价值（本例中为 `9360.00` 和 `9310.00`）。若 `amount` 小于两期之和，则先覆盖第 3 期，第 4 期收到剩余金额。已逾期的分期返回 `EVC100030`；`amount` 超过名义价值之和返回 `EVC100031`。清算时允许部分支付，与 `early_amortization` 相同。 ## 场景 4：按协商金额全额结清（full_amortization） 发行人与投资者约定以 R$ 10,000.00 结清第 1 期和第 2 期分期，尽管二者在 `reference_date` 的现值分别为 R$ 9,460.00 和 R$ 9,410.00。`amount` 按现值比例分配，每期在清算时全额结清。 ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "full_amortization", "amount": 10000.00, "reference_date": "2026-02-08", "due_date": "2026-02-08", "installment_list": [1, 2] } ``` 响应 `201 Created` — 两个分期对账事件，`expected_amount` 分别为 `5013.25` 和 `4986.75`（之和等于 `amount`），`discount_amount` 分别为 `4446.75` 和 `4423.25`。`amount` 超过现值之和返回 `EVC100035`；`amount` 过小以致无法给每期正份额则返回 `EVC100034`。 ## 故障排查 调用创建接口时最常见的错误码。完整列表请参阅[错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros)。 - **`EVC100015`**（400，EarlyAmortizationRequiresSingleInstallment）— `early_amortization` 在 `installment_list` 中只接受恰好一期分期。请减少为 1 期。 - **`EVC000007`**（404，InstallmentNumberNotFound）— `installment_list` 中提交的某个 `installment_number` 在目标 `security` 中不存在。调用前请先核对 `GET /security/security/{security_key}` 返回的编号。 - **`QIT000001`**（400）— schema 被拒绝。典型原因：提交了已移除的旧版 `installment_key_list` 字段，或 `installment_list` 中含有非整数项。 - **`EVC100016`**（400，EarlyAmortizationInstallmentOverdue）— `early_amortization` 的目标分期已逾期，不符合条件。请选择一期未来的分期。 - **`EVC100017`**（400，EarlyAmortizationAmountExceedsPresentValue）— 在 `early_amortization` 中，`amount` 超过了该分期的现值。调用前请先确认 PV。 - **`EVC100030`**（400，InstallmentNotEligibleForNominalAmortization）— 在 `nominal_amount` 中，`installment_list` 里的某期分期在 `reference_date` 已逾期。请只选择未来的分期。 - **`EVC100031`**（400，NominalAmountExceedsInstallmentsNominalValue）— 在 `nominal_amount` 中，`amount` 超过了所选分期的名义价值（本金 + 利息）之和。请调低 `amount`。 - **`EVC100033`**（400，DistributionDoesNotMatchAmount）— 已分配的 `expected_amount` 之和与所声明的 `amount` 相差超过 R$ 0.01。对于 `present_amount`，请发送等于现值之和减去 `total_discount` 的 `amount`。 - **`EVC100034`**（400，DistributionWithZeroInstallment）— 某一所选分期的 `expected_amount` 将为零（例如 `total_discount` 等于现值，或 `amount` 在最后一期之前已耗尽）。请只选择 `amount` 能覆盖的分期。 - **`EVC100035`**（400，AmountExceedsInstallmentsPresentValue）— `amount` 超过所选分期现值之和。请降低 `amount`。 - **`EVC100013`**（424，SecurityApiUnavailable）— 获取现值时 Security API 暂时不可用；属临时性问题。请稍候重试。 - **`SEC000031`**（400，PostFixedSecurityNotSupported）— V1 不支持后固定利率资产（CDI、IPCA、IGPM）。请使用 `pre_price` 或 `pre_sac` 类资产。 ## 另请参阅 - [概念](./conceito.md) - [集成路线图](../roteiro-integracao/roteiro-integracao-padrao.md) - [业务规则](./regras-de-negocio.md) - [创建非常规摊还](./endpoints/criar-amortizacao.md) - [查询非常规摊还](./endpoints/consultar-amortizacao.md) - [操作回购](./recompra-de-operacao.md) - [错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # 回购式摊还 URL: /zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao ## 概述 **回购**是指发行一笔**新的**商业票据操作，用以"回购"某笔既有操作中一项或多项未结的非常规摊还。典型场景是：债务人有一笔未结操作，并与投资人共同决定将其回购 — 出于再融资或任何其他协商确定的原因。他们不用自有资金清偿债务，而是构建一笔新操作，其放款会自动清算所选定的非常规摊还。 新操作由被回购事件的**同一债务人**（`issuer`）发行。回购可以涵盖： - **单笔非常规摊还** — 最常见的情形，回购一笔操作。 - **多项资产** — 通过传入多个 `extraordinary_event_conciliation_key`（甚至可来自不同的 `security`），适用于债务人希望在同一笔新操作中回购多项资产的情形。 回购不是一个独立的 API 调用：它在**创建新操作的时刻**声明，通过提供待回购非常规事件的键值列表来完成。 ## 前提条件 每一笔待回购的非常规摊还都必须**已经存在** — 事先通过[非常规摊还](./endpoints/criar-amortizacao.md)流程创建 — 并且在新操作创建时处于 `pending_conciliation` 状态。你在回购中引用的正是这些键值（`extraordinary_event_conciliation_key`）。 :::warning 日期必须与放款日一致 **创建非常规事件时**所提供的 `reference_date` 和 `due_date` 必须与新回购操作的**放款日期**相对应。如果这些日期与放款日不一致，相关事件**不会被正确放款，并会被自动取消** — 回购不会生效。请在规划非常规事件的 `reference_date`/`due_date` 时，就把新操作的放款时点考虑进去。 ::: ## 如何触发 回购在[商业票据操作登记](../emissao-de-notas/cadastro-operacao/criar-operacao.md)（`POST /commercial_paper/operation`）中声明：只需在操作创建的常规字段之外，一并提交 `extraordinary_event_conciliation_key_list` 字段，其中包含你希望回购的非常规事件的键值。 ```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" ] } ``` 相较于普通的操作登记，`extraordinary_event_conciliation_key_list` 是**唯一**新增的内容 — 其余所有字段均遵循[操作创建契约](../emissao-de-notas/cadastro-operacao/criar-operacao.md)。各字段（`issuer_key`、`issuer_bank_account`、`investors`、`issue_date`、`financial`）的完整说明请参阅该页面。 ### 字段 | 字段 | 类型 | 是否必填 | 描述 | |--------------------------------------------|--------------------------|---------|------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key_list`| string (UUID) 数组 | 否 | 待回购非常规摊还的键值列表。各项唯一；每回购一项资产对应一个键值。可跨多个 `security`。在不涉及回购的操作中请省略该字段。 | ## 金额规则 新操作的金额必须足以覆盖被回购的内容。在**创建操作**时应用的规则是： > `extraordinary_event_conciliation_key_list` 中所引用的全部事件的 `expected_amount` 之和，必须**小于等于**新操作的 `released_amount`。否则创建会被拒绝，返回 **`COM000050`**（400）。 :::info `released_amount` 与手续费 `released_amount` 是**扣除已融资手续费后的发行净额**。因此在实践中，新操作的发行金额至少要覆盖被回购事件的金额**加上手续费** — 只有这样，最终的 `released_amount` 才能达到各 `expected_amount` 之和。 ::: ## 放款 > **内部编排。** 回购本身发生在新操作放款时，由 QI Tech 在内部执行 — 集成方在此环节**无需调用**任何额外端点。 新操作放款时： 1. 被引用的非常规摊还会**自动清算**，从 `pending_conciliation` 转为 `paid`。 2. **剩余部分** — 即 `released_amount − Σ expected_amount`（为正值时）— 会**划付给债务人**。 也就是说，放款的一部分用于清偿被回购的事件，余下的部分归债务人，整个过程在一笔操作中完成。 ## 另请参阅 - [概念](./conceito.md) - [创建非常规摊还](./endpoints/criar-amortizacao.md) - [查询非常规摊还](./endpoints/consultar-amortizacao.md) - [业务规则](./regras-de-negocio.md) - [示例](./exemplos.md) - [集成路线图](../roteiro-integracao/roteiro-integracao-padrao.md) - [错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # 业务规则 — 非常规摊还 URL: /zh-Hans/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio 本页汇总了管辖非常规摊还的创建、清算与取消的各项不变量。当端点页面引用某个错误码、字段或需要额外上下文的条件时，请查阅本页。 ## 参考日期（`reference_date`） `reference_date` 由**调用方**在创建请求中提供，是本服务使用的唯一时间基准 — 系统**从不使用** `date.today()`。所有依赖日期的逻辑（逾期分期的分类、现值的按比例折现、`early_amortization` 和 `nominal_amount` 可选分期的筛选）均以该字段为起点。向 security-service 查询现值时也会传入同一个 `reference_date`。 ## 摊还类型 支持的 7 种类型，以及每种类型如何在 `installment_list` 的分期之间分配 `amount`： | 类型 | 在所选分期之间的分配规则 | 是否允许部分支付 | |------------------------|----------------------------------------------------------------------|----------------| | `equal_amount` | 按现值比例分配，先逾期后未来 | 否 | | `first_installments` | 依次应用于所选分期中（按到期日）的前 N 期，N = `number_of_installments` | 否 | | `present_amount` | 按分期显式指定；折扣顺序为利息 → 罚金 → 本金 | 否 | | `matured_installments` | 仅限已到期的分期，按到期日顺序 | 否 | | `early_amortization` | 单笔未来分期，金额不超过其现值 | **是** | | `nominal_amount` | 未来分期按名义价值（本金 + 利息）结清，按到期日顺序，不折现到现值 | **是** | | `full_amortization` | 按现值比例分配到所有所选分期，不做级联；每期全额结清 | 否 | `installment_list`（整数 `installment_number` 数组）对**所有类型均为必填** — 省略时返回 `EVC100002`。服务会将每个 `installment_number` 解析为 `security` 中对应的分期，并逐期查询所选分期的现值；`amortization_type` 只决定 `amount` 在这些分期之间的分配方式。 ## 提前摊还（`early_amortization`） `early_amortization` 允许部分支付（`nominal_amount` 同样允许）。以下所有条件均适用： - `installment_list` 中恰好 **1** 期分期 — 否则返回 `EVC100015`。 - 目标分期**不得已逾期** — 否则返回 `EVC100016`。 - `amount` 必须**小于等于**该分期的**现值** — 否则返回 `EVC100017`。 - **允许部分支付。** `paid_amount > 0 AND paid_amount = total_expected_amount - tolerance_amount` 时才会转为 `paid`。 ## 按名义价值摊还（`nominal_amount`） `nominal_amount` 按名义价值 — 到期日的本金加利息 — 结清未来分期，不将其折现到 `reference_date` 的现值。以下所有条件均适用： - `installment_list` 中所有分期的 `due_date` 必须不早于 `reference_date` — 已逾期的分期返回 `EVC100030`。 - `amount` 按到期日顺序分配，依次按名义价值覆盖每期分期直至用尽；最后一期被覆盖的分期可能只收到部分金额。 - `amount` 必须**小于等于所选分期的名义价值之和** — 否则返回 `EVC100031`。 - 清算时**允许部分支付**，派生状态与 `early_amortization` 所述相同。 ## 全额结清（`full_amortization`） `full_amortization` 使用所声明的 `amount` 结清 `installment_list` 中的**所有**分期，与每期的现值无关： - `amount` 按各期在 `reference_date` 的现值比例分配，不做级联 — 没有任何分期会没有份额。 - 每个 `event_conciliation` 创建时的 `expected_amount` 等于其份额，`discount_amount` 等于现值与份额之差。 - `amount` 不能超过所选分期现值之和 — 否则返回 `EVC100035`。 - 清算时，支付该份额会在 security-service 中**全额**结清该分期：已付金额记为已付，差额记为该分期的折扣。`present_amount` 同样适用。 ## `amount` 与分配结果的一致性 分配 `amount` 之后，服务会对**所有**类型按以下顺序校验结果： 1. `amount` 大于已分配分期的现值之和 → `EVC100035`（按现值定价的类型；`early_amortization` 和 `nominal_amount` 仍分别返回 `EVC100017` 和 `EVC100031`）。 2. 任一所选分期的 `expected_amount` 将为零 → `EVC100034`。不会创建带有零金额子事件的事件；请只选择 `amount` 能覆盖的分期。 3. 已分配的 `expected_amount` 之和与 `amount` 相差超过 R$ 0.01 → `EVC100033`。对于 `present_amount`，`amount` 必须等于现值之和减去 `total_discount`。 `expected_amount` 以分为单位存储，四舍五入的余数计入最后一期，因此事件的 `total_expected_amount` 始终等于其子事件之和。 ## 清算流程 > **内部编排。** 非常规事件的清算在检测到付款时由 QI Tech（account-liquidation-api）执行 — 集成方在此环节**无需调用**任何端点，也不会收到专门针对状态转换的 webhook。以下规则描述的是内部行为，便于你理解创建之后发生了什么。 **常规清算发出完整总额（规则 4）。** 在 `due_date` 进行的常规清算仍会通过 SQS 发出该分期完整的 `total_amount`；不会扣减 `paid_amount`。该事件会在其自身的 `early_amortization` 引擎中对账部分已付状态。 ## 取消与终结 > **内部编排。** 取消与终结由每日例行任务触发 — 集成方**无需调用**任何端点来取消或终结一笔非常规摊还，也不存在面向租户的专用 webhook。以下描述仅供参考。 ## 另请参阅 - [概念](./conceito.md) - [集成路线图](../roteiro-integracao/roteiro-integracao-padrao.md) - [创建非常规摊还](./endpoints/criar-amortizacao.md) - [查询非常规摊还](./endpoints/consultar-amortizacao.md) - [操作回购](./recompra-de-operacao.md) - [示例](./exemplos.md) - [错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # 错误目录 URL: /zh-Hans/documentation/escrituracao/catalogo-erros/catalogo-erros ## 错误格式 所有书写集成 API 返回的错误均按以下说明进行格式化： 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" } ``` --- ## 发行人资质审核流程中可能出现的错误表 | HTTP 代码 | 错误代码 | 标题 | 描述 (eng) | 翻译 (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. | ## 投资人资质审核流程中可能出现的错误表 | HTTP 代码 | 错误代码 | 标题 | 描述 (eng) | 翻译 (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. | ## 商业票据发行流程中可能出现的错误表 | HTTP 代码 | 错误代码 | 标题 | 描述 (eng) | 翻译 (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | COM000001 | Bad Request | Document is not valid. | Documento fornecido não é válido. | | 400 | COM000002 | Bad Request | Tenant must be configured before use this endpoint. | Tenant precisa ser configurado antes de utilizar este endpoint. | | 409 | COM000003 | Conflict | Tenant configuration already exists. | Configuração para este tenant já existe. | | 400 | COM000004 | Bad Request | Investor with key (investor_key) is not allowed. Please check. | Investidor com a chave (investor_key) não permitido. Cheque o cadastro. | | 400 | COM000005 | Bad Request | Issuer with key (issuer_key) is not allowed. Please check. | Emissor com a chave (issuer_key) não permitido. Cheque o cadastro. | | 400 | COM000006 | Bad Request | Operation with more than one investor functionality not available yet. | Operação com mais de um investidor não disponível ainda. | | 404 | COM000007 | Not Found | Operation (operation_key) not found. | Operação (operation_key) não encontrada. | | 403 | COM000008 | Forbidden | Operation (operation_key) does not belong to tenant. | Operação (operation_key) não pertence ao tenant. | | 400 | COM000010 | Bad Request | Operations cannot be updated outside of in_filling status. | Operação não pode ser atualizada fora do status in_filling. | | 404 | COM000011 | Not Found | Related party not found. | Parte relacionada não encontrada. | | 400 | COM000012 | Bad Request | Related party (related_party_key) is not associated with operation (operation_key). | A parte relacionada (related_party_key) não está associada com a operação (operation_key). | | 404 | COM000013 | Not Found | Signer Group not found. | Grupo de assinantes não encontrado. | | 400 | COM000014 | Bad Request | Signer group (signer_group_key) is not associated with related party (related_party_key). | O grupo de assinantes (signer_group_key) não está associado com a parte relacionada (related_party_key). | | 400 | COM000015 | Bad Request | Signer list does not match minimum required signers field. | Lista de assinantes não é compatível com o mínimo de assinantes enviado. | | 404 | COM000016 | Not Found | Document not found. | Documento não encontrado. | | 400 | COM000017 | Bad Request | Document (document_key) is not associated with related party (related_party_key). | O documento (document_key) não está associado com a parte relacionada (related_party_key). | | 400 | COM000018 | Bad Request | Document sent is invalid or quality is low. | Documento enviado é inválido ou de baixa qualidade. | | 400 | COM000019 | Bad Request | Delete issuer or investor is not allowed. | Não é possível deletar o emissor ou investidor. | | 400 | COM000020 | Bad Request | Operation is in a final status and cannot be modified. | Operação já está em um estado final e não pode ser atualizada. | | 400 | COM000021 | Bad Request | Operation is not in analysis. | Operação não está em análise. | | 400 | COM000022 | Bad Request | Document not signed yet. | Documento ainda não foi assinado. | | 400 | COM000023 | Bad Request | Document not available yet. | Documento ainda não foi gerado. | | 400 | COM000024 | Bad Request | Failed to send document to signature, please retry. | Falha ao enviar documento para assinatura, tente novamente. | | 404 | COM000025 | Not Found | Collateral not found. | Garantia não encontrada. | | 400 | COM000026 | Bad Request | Collateral (collateral_key) is not associated with operation (operation_key). | A garantia (collateral_key) não está associada com a operação (operation_key). | | 400 | COM000027 | Bad Request | Metadata not found. | Metadado não encontrado. | | 400 | COM000028 | Bad Request | Operation is canceled and cannot be modified. | Operação está cancelada e não pode ser atualizada. | | 400 | COM000061 | Bad Request | Third-party disbursement slip amount does not match the operation's `released_amount`. | Valor do boleto do desembolso a terceiro diferente do `released_amount` da operação. | | 400 | COM000062 | Bad Request | Third-party disbursement is not enabled. | Tenant não habilitado para desembolso a terceiro. | | 400 | COM000063 | Bad Request | Third-party disbursement beneficiary document is invalid. | Documento do beneficiário do desembolso a terceiro inválido. | | 400 | COM000071 | Bad Request | Third-party disbursement `pix_key` of type `cpf`/`cnpj` has invalid check digits. | A `pix_key` de tipo `cpf`/`cnpj` do desembolso a terceiro tem dígito verificador inválido. | | 400 | COM000072 | Bad Request | The operation uses external signature and `p7s_base64` was not sent. | A operação usa assinatura externa e o `p7s_base64` não foi enviado. | | 400 | COM000073 | Bad Request | The signature file could not be read as a CMS structure, or exceeds the accepted size. | O arquivo de assinatura não pôde ser lido como estrutura CMS, ou excede o tamanho aceito. | | 422 | COM000074 | Unprocessable Entity | The signature does not match the document issued by QI Tech. | A assinatura não corresponde ao documento emitido pela QI Tech. | | 409 | COM000075 | Conflict | The document already had a signature accepted. | O documento já teve uma assinatura aceita. | | 400 | COM000077 | Bad Request | Operation issuer is not enabled for auto signature. | Emissor da operação não está habilitado para auto-assinatura. | ## 份额整合流程中可能出现的错误表 | HTTP 代码 | 错误代码 | 标题 | 描述 (eng) | 翻译 (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | INT000001 | Bad Request | Document is not valid. | Documento fornecido não é válido. | | 404 | INT000002 | Not Found | Integralization process (integralizaion_key) not found. | Processo de integralização (integralizaion_key) não encontrado. | | 403 | INT000003 | Forbidden | Integralization process (integralizaion_key) does not belong to tenant. | Processo de integralização (integralizaion_key) não pertence ao tenant. | | 404 | INT000004 | Not Found | Subscription (subscription_key) not found. | Subscrição (subscription_key) não encontrada. | | 400 | INT000005 | Bad Request | Subscription (subscription_key) is not associated with integralization process (integralizaion_key). | A subscrição (subscription_key) não está associada com o processo de integralização (integralizaion_key). | | 404 | INT000006 | Not Found | Subscription payment not found. | Pagamento de subscrição não encontrado. | | 400 | INT000007 | Bad Request | Subscription payment (subscription_payment_key) is not associated with subscription (subscription_key). | O pagamento de subscrição (subscription_payment_key) não está associado com a subscrição (subscription_key). | | 400 | INT000008 | Bad Request | Subscription payment already analyzed. | Pagamento de subscrição já foi analisado. | | 409 | INT000009 | Conflict | Integralization process for (operation_key) already exists. | Já existe um processo de integralização para a operação (operation_key). | | 400 | INT000010 | Bad Request | Subscripted quantity (subscripted_quantity) is bigger than the available quantity (available_quantity). | A quantidade de cotas subscritas (subscripted_quantity) é maior do que a quantidade disponível (available_quantity). | | 400 | INT000011 | Bad Request | Subscription is not waiting payment yet. | Subscrição ainda não está aguardando pagamento. | | 400 | INT000012 | Bad Request | Subscription is in a final state and cannot be canceled. | Subscrição já está em um status final e não pode ser cancelada. | | 400 | INT000013 | Bad Request | Subscription is not waiting payment yet. | Subscrição não está aguardando pagamento ainda. | | 400 | INT000014 | Bad Request | Document not signed yet. | Documento ainda não foi assinado. | | 400 | INT000015 | Bad Request | Integralization canceled. | Integralização cancelada. | | 400 | INT000016 | Bad Request | Integralization cancellation denied. There are integralized quantities. | Cancelamento de integralização negado. Existem cotas integralizadas. | | 400 | INT000017 | Bad Request | Creation of subscriptions for an ongoing operation is not available yet. | Ainda não é possível criar subscrições para operações em andamento. | | 400 | INT000018 | Bad Request | To create a signature with data different from the original, you must define a recalculation method using the recalculation_method field. | Para criar uma subscrição com data diferente da original é preciso definir um método de recálculo através do campo recalculation_method. | --- # Webhook 配置 URL: /zh-Hans/documentation/escrituracao/configuracao-webhooks Webhook 配置 API 允许管理 webhook 端点，以实时接收书写事件通知。每个 tenant 可以拥有多个 webhook 配置，从而将事件发送到不同的目的地。 --- ## 数据模型 ### 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" } ``` --- ## 创建 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 | 字段 | 类型 | 描述 | | ---------------------- | ------ | --------------------------------------------------------- | | `tenant_key`* | string | tenant 的 UUID（UUID v4）。 | | `url`* | string | 接收 webhook 的目标 URL。 | | `hmac_signature_key`* | string | 用于 webhook HMAC 签名的密钥。 | | `headers` | object | 请求中要包含的自定义 headers。 | --- ### 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 | 字段 | 类型 | 描述 | | ---------------------- | ------ | --------------------------------------------------------- | | `configuration_key` | string | webhook 配置的唯一键（UUID v4）。 | | `tenant_key` | string | tenant 的 UUID。 | | `url` | string | 已配置的目标 URL。 | | `headers` | object | 已配置的自定义 headers。 | | `hmac_signature_key` | string | HMAC 签名的密钥。 | --- ## 列出 Webhook 配置 (GET) ### Request ENDPOINT /outgoing_webhook/webhook_configuration MÉTODO GET ### Query Params | 字段 | 类型 | 描述 | | ------------ | ------- | ---------------------------------------------- | | `tenant_key`* | string | 用于筛选配置的 tenant UUID。 | | `page` | integer | 页码（默认：1）。 | | `page_size` | integer | 每页条目数（默认：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 | 字段 | 类型 | 描述 | | ---------------------- | ------- | --------------------------------------------------------- | | `data` | array | webhook 配置列表。 | | `pagination` | object | **[pagination 对象](#objeto-pagination)**。 | --- ## 通过键获取 Webhook 配置 (GET) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | 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 | 字段 | 类型 | 描述 | | ---------------------- | ------- | --------------------------------------------------------- | | `configuration_key` | string | webhook 配置的唯一键（UUID v4）。 | | `tenant_key` | string | tenant 的 UUID。 | | `url` | string | 已配置的目标 URL。 | | `headers` | object | 已配置的自定义 headers。 | | `hmac_signature_key` | string | HMAC 签名的密钥。 | --- ## 更新 Webhook 配置 (PUT) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY MÉTODO PUT ### Path Params | 字段 | 类型 | 描述 | 字符数 | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | 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 | 字段 | 类型 | 描述 | | --------------------- | ------ | --------------------------------------------------------- | | `url` | string | 接收 webhook 的新目标 URL。 | | `headers` | object | 请求中要包含的新自定义 headers。 | | `hmac_signature_key` | string | webhook HMAC 签名的新密钥。 | --- ### 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 | 字段 | 类型 | 描述 | | ---------------------- | ------- | --------------------------------------------------------- | | `configuration_key` | string | webhook 配置的唯一键（UUID v4）。 | | `tenant_key` | string | tenant 的 UUID。 | | `url` | string | 已配置的目标 URL。 | | `headers` | object | 已配置的自定义 headers。 | | `hmac_signature_key` | string | HMAC 签名的密钥。 | --- ## 删除 Webhook 配置 (DELETE) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | webhook 配置的唯一键（UUID v4）。 | 36 | --- ### Response STATUS 200 Response Body ```json {} ``` --- # 登记基础资产（Lastro） URL: /zh-Hans/documentation/escrituracao/emissao-cr/cadastro-lastro 此端点用于登记CR操作的 **基础资产**（lastro）。基础资产代表为证券化提供支撑的债权。资产文件以 base64 提交，其结构化数据随请求一并发送。 :::info 基础资产在 **操作创建后** 通过单独的请求提交。同一操作可登记多个基础资产。 ::: --- ## **Request** ENDPOINT /cr/operation/ OPERATION-KEY /underlying_asset MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------|--------|-------------------------------|--------| | `OPERATION-KEY` * | string | 操作的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | |---------------------------|--------|----------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | 基础资产类型。 | **[underlying_asset_type 枚举](#underlying_asset_type-枚举)** | | `underlying_asset_base64` * | string | base64 格式的基础资产文件。 | - | | `underlying_asset_data` * | object | 基础资产数据（自由结构）。 | - | ### underlying_asset_type 枚举 | 枚举值 | 描述 | |------------|--------| | `contract` | 合同。 | ## **Response** STATUS 201 Response Body ```json { "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23", "underlying_asset_type": "contract", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Response Body Params | 字段 | 类型 | 描述 | |---------------------------|--------|--------------------| | `underlying_asset_key` * | string | 所登记基础资产的唯一键。 | | `underlying_asset_type` * | string | 基础资产类型。 | | `underlying_asset_data` * | object | 基础资产数据。 | --- --- # 登记CR操作 URL: /zh-Hans/documentation/escrituracao/emissao-cr/cadastro-operacao 此端点通过单个请求创建完整的CR操作。 :::info `financial` 对象为 **必填**，且必须以已计算好的形式提交，因为此端点不执行财务模拟。发行人及其银行账户必须事先登记。 ::: --- ## **Request** ENDPOINT /cr/create_operation MÉTODO POST 请求体既可以是仅含 **必填字段的负载**（包含财务对象），也可以是同时包含关联方的 **完整负载**。两种变体见下文。 必填字段负载 ```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 } ] } } ``` 完整负载（含关联方） ```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** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | ------------------------------------------ | -------------------------- | | `tenant_key` * | string | tenant 的唯一键。 | - | | `issuer_key` * | string | 发行人的唯一键（须事先登记）。 | - | | `issue_number` * | integer | 发行编号。 | - | | `issue_series` * | integer | 发行系列。 | - | | `issue_date` * | string | 操作发行日期（格式："YYYY-MM-DD"）。 | - | | `signature_method` | string | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举](#signature_method-枚举)** | | `investors` * | array | 相关投资人列表。 | **investors 对象** | | `financial` * | object | 操作的已计算财务数据。 | **financial 对象** | | `contract_number` | string | 合同编号。 | - | | `related_party_list` | array | 操作的关联方（担保人、债务人等）。 | **related_party 对象** | ### investors 对象 | 字段 | 类型 | 描述 | | --------------------------- | ------ | ------------------------------------------ | | `investor_key` * | string | 投资人的唯一键（须事先登记）。 | | `bank_account` * | object | 投资人的银行账户（**bank_account 对象**）。 | | `subscription_percentage` | number | 认购比例。 | | `subscription_quantity` | number | 认购数量。 | ### bank_account 对象 | 字段 | 类型 | 描述 | | ------------------------------------- | ------ | ----------------------------------------------- | | `account_number` * | string | 银行账户号码。 | | `account_digit` * | string | 银行账户校验位。 | | `account_branch` * | string | 银行账户支行。 | | `financial_institution_code_number` | string | 金融机构代码。 | | `financial_institution_ispb` * | string | 金融机构 ISPB 代码。 | | `account_type` * | string | 账户类型（`checking`、`savings`、`salary`、`payment`）。 | ### financial 对象 | 字段 | 类型 | 描述 | | --------------------------- | ------- | ------------------------------------------ | | `financial_base_date` * | string | 财务基准日期（格式："YYYY-MM-DD"）。 | | `interest_type` * | string | 利率类型。 | | `issue_amount` | number | 发行总金额。 | | `issue_quantity` | integer | 发行单位数量。 | | `unit_price` | number | 每单位发行价格。 | | `released_amount` | number | 释放的净金额。 | | `cet` / `annual_cet` | number | 有效总成本（月度与年度），百分比。 | | `number_of_installments` * | integer | 期数。 | | `prefixed_interest_rate` * | object | 固定利率。 | | `fine_delay_rate` | object | 滞纳金利率。 | | `contract_fine_rate` | number | 合同罚款百分比。 | | `fees` | array | 费用列表。 | | `installments` | array | 已计算的期次列表。 | ### related_party 对象 `related_party_list` 中的每一项代表参与该操作的一方。 | 字段 | 类型 | 描述 | | ----------------- | ------- | ----------------------------------------------- | | `person_type` * | string | 人员类型（`natural` 自然人，`legal` 法人）。 | | `name` * | string | 关联方名称。 | | `document_number` * | string | CPF（自然人）或 CNPJ（法人）。 | | `role_type` * | string | 关联方在操作中的角色。**[role_type 枚举](#role_type-枚举)** | | `street` * | string | 街道。 | | `number` * | string | 门牌号。 | | `neighborhood` | string | 街区。 | | `postal_code` * | string | 邮政编码（格式："00000-000"）。 | | `city` * | string | 城市。 | | `state` * | string | 州/省（2 个字母）。 | | `complement` | string | 地址补充信息。 | | `is_pep` | boolean | （自然人）是否为政治公众人物。 | | `marital_status` | string | （自然人）婚姻状况。 | | `property_system` | string | （自然人）财产制度。 | | `birthdate` | string | （自然人）出生日期。 | | `mother_name` | string | （自然人）母亲姓名。 | | `occupation` | string | （自然人）职业。 | | `trading_name` | string | （法人）商号。 | | `cnae_code` | string | （法人）CNAE 代码（格式："00.00-0-00"）。 | | `company_type` | string | （法人）公司类型。 | | `foundation_date` | string | （法人）成立日期。 | :::warning 注意 必填字段因 `person_type` 而异： - **自然人（`natural`）**：除通用字段外，`is_pep` 为必填。 - **法人（`legal`）**：除通用字段外，`trading_name`、`cnae_code`、`company_type` 和 `foundation_date` 为必填。 ::: ### role_type 枚举 | 枚举值 | 描述 | |--------|------| | `issuer` | 发行人。 | | `investor` | 投资人。 | | `cosigner` | 共同债务人。 | | `fiduciary_debtor` | 信托债务人。 | | `solidary_debtor` | 连带债务人。 | | `guarantor` | 担保人。 | | `bonafide_depositary` | 善意保管人。 | | `intervening_guarantor` | 介入担保人。 | | `intervening_consentor` | 介入同意人。 | | `intervening_discharger` | 介入清偿人。 | | `assignor` | 转让人。 | | `endorser` | 背书人。 | | `consulting` | 咨询方。 | | `fund_administrator` | 基金管理人。 | | `fund_representative` | 基金代表。 | | `company_representative` | 公司代表。 | | `attestant` | 见证人。 | | `debtor` | 债务人。 | | `bestowal` | 授予人。 | | `manager` | 管理人。 | :::tip 担保和基础资产在操作创建后通过 **单独的端点** 提交。请参阅本节的 **登记基础资产** 页面。 ::: ### signature_method 枚举 | 枚举值 | 描述 | |--------|------| | `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。 | | `qi_sign` | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 | ## **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": { ... } } ``` 响应返回所创建操作的完整 JSON，包括 `operation_key`、投资人与关联方列表，以及已计算的财务对象。 --- # 提交文件 URL: /zh-Hans/documentation/escrituracao/emissao-cr/envio-documento 此端点用于 **上传文件** 并返回标识该文件的 `document_key`。当其他操作端点需要先前已上传文件的键时，该 `document_key` 用于引用这些文件。 --- ## **Request** ENDPOINT /cr/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 必需 | |-------------------|--------|----------------------------|------| | `document_base64` * | string | base64 编码的文件内容。 | 是 | | `document_name` | string | 文件名称。 | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |----------------|--------|-------------------------------|------------| | `document_key` * | string | 所上传文件的唯一键（UUID v4）。 | 36 | --- --- # 提交操作的外部文件 URL: /zh-Hans/documentation/escrituracao/emissao-cr/envio-documento-externo 此端点允许将在外部签署的文件提交至书写系统，提交的 base64 将由书写方进行分析和批准。 :::warning 警告 此端点仅应用于使用 **client_side** 签名类型的操作，或用于提交 SA 或合作社类型公司的批准会议纪要。对于通过 QI Sign 或 Certifiqi 的流程，合同以正常方式生成。 ::: --- ## 提交已签署文件 (POST) ### Request ENDPOINT /cr/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------|--------|-------------------------------|--------| | `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。 | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|--------|--------------------|------------------------------------------------------------| | `contract_type` * | string | 已签署文件的类型。 | **[contract_type 枚举](#contract_type-枚举)** | | `contract_base64` * | string | base64 格式的已签署文件。 | - | ### contract_type 枚举 | 枚举值 | 描述 | |---------------------|--------------------------------------------| | `securitization_term` | CR 证券化条款。 | | `adhesion_term` | CR 加入条款。 | | `sa_minute` | **SA** 公司CR发行批准会议纪要。 | | `ltda_minute` | **LTDA** 公司CR发行批准会议纪要。 | | `cop_minute` | **合作社** CR发行批准会议纪要。 | ### Response 响应体为更新后的完整操作 JSON。 --- --- # 登记基础资产（Lastro） URL: /zh-Hans/documentation/escrituracao/emissao-cra/cadastro-lastro 此端点用于登记CRA操作的 **基础资产**（lastro）。基础资产代表为证券化提供支撑的债权。资产文件以 base64 提交，其结构化数据随请求一并发送。 :::info 基础资产在 **操作创建后** 通过单独的请求提交。同一操作可登记多个基础资产。 ::: --- ## **Request** ENDPOINT /cra/operation/ OPERATION-KEY /underlying_asset MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------|--------|-------------------------------|--------| | `OPERATION-KEY` * | string | 操作的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | |---------------------------|--------|----------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | 基础资产类型。 | **[underlying_asset_type 枚举](#underlying_asset_type-枚举)** | | `underlying_asset_base64` * | string | base64 格式的基础资产文件。 | - | | `underlying_asset_data` * | object | 基础资产数据（自由结构）。 | - | ### underlying_asset_type 枚举 | 枚举值 | 描述 | |------------|--------| | `contract` | 合同。 | ## **Response** STATUS 201 Response Body ```json { "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23", "underlying_asset_type": "contract", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Response Body Params | 字段 | 类型 | 描述 | |---------------------------|--------|--------------------| | `underlying_asset_key` * | string | 所登记基础资产的唯一键。 | | `underlying_asset_type` * | string | 基础资产类型。 | | `underlying_asset_data` * | object | 基础资产数据。 | --- --- # 登记CRA操作 URL: /zh-Hans/documentation/escrituracao/emissao-cra/cadastro-operacao 此端点通过单个请求创建完整的CRA操作。 :::info `financial` 对象为 **必填**，且必须以已计算好的形式提交，因为此端点不执行财务模拟。发行人及其银行账户必须事先登记。 ::: --- ## **Request** ENDPOINT /cra/create_operation MÉTODO POST 请求体既可以是仅含 **必填字段的负载**（包含财务对象），也可以是同时包含关联方的 **完整负载**。两种变体见下文。 必填字段负载 ```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 } ] } } ``` 完整负载（含关联方） ```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** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | ------------------------------------------ | -------------------------- | | `tenant_key` * | string | tenant 的唯一键。 | - | | `issuer_key` * | string | 发行人的唯一键（须事先登记）。 | - | | `issue_number` * | integer | 发行编号。 | - | | `issue_series` * | integer | 发行系列。 | - | | `issue_date` * | string | 操作发行日期（格式："YYYY-MM-DD"）。 | - | | `signature_method` | string | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举](#signature_method-枚举)** | | `investors` * | array | 相关投资人列表。 | **investors 对象** | | `financial` * | object | 操作的已计算财务数据。 | **financial 对象** | | `contract_number` | string | 合同编号。 | - | | `related_party_list` | array | 操作的关联方（担保人、债务人等）。 | **related_party 对象** | ### investors 对象 | 字段 | 类型 | 描述 | | --------------------------- | ------ | ------------------------------------------ | | `investor_key` * | string | 投资人的唯一键（须事先登记）。 | | `bank_account` * | object | 投资人的银行账户（**bank_account 对象**）。 | | `subscription_percentage` | number | 认购比例。 | | `subscription_quantity` | number | 认购数量。 | ### bank_account 对象 | 字段 | 类型 | 描述 | | ------------------------------------- | ------ | ----------------------------------------------- | | `account_number` * | string | 银行账户号码。 | | `account_digit` * | string | 银行账户校验位。 | | `account_branch` * | string | 银行账户支行。 | | `financial_institution_code_number` | string | 金融机构代码。 | | `financial_institution_ispb` * | string | 金融机构 ISPB 代码。 | | `account_type` * | string | 账户类型（`checking`、`savings`、`salary`、`payment`）。 | ### financial 对象 | 字段 | 类型 | 描述 | | --------------------------- | ------- | ------------------------------------------ | | `financial_base_date` * | string | 财务基准日期（格式："YYYY-MM-DD"）。 | | `interest_type` * | string | 利率类型。 | | `issue_amount` | number | 发行总金额。 | | `issue_quantity` | integer | 发行单位数量。 | | `unit_price` | number | 每单位发行价格。 | | `released_amount` | number | 释放的净金额。 | | `cet` / `annual_cet` | number | 有效总成本（月度与年度），百分比。 | | `number_of_installments` * | integer | 期数。 | | `prefixed_interest_rate` * | object | 固定利率。 | | `fine_delay_rate` | object | 滞纳金利率。 | | `contract_fine_rate` | number | 合同罚款百分比。 | | `fees` | array | 费用列表。 | | `installments` | array | 已计算的期次列表。 | ### related_party 对象 `related_party_list` 中的每一项代表参与该操作的一方。 | 字段 | 类型 | 描述 | | ----------------- | ------- | ----------------------------------------------- | | `person_type` * | string | 人员类型（`natural` 自然人，`legal` 法人）。 | | `name` * | string | 关联方名称。 | | `document_number` * | string | CPF（自然人）或 CNPJ（法人）。 | | `role_type` * | string | 关联方在操作中的角色。**[role_type 枚举](#role_type-枚举)** | | `street` * | string | 街道。 | | `number` * | string | 门牌号。 | | `neighborhood` | string | 街区。 | | `postal_code` * | string | 邮政编码（格式："00000-000"）。 | | `city` * | string | 城市。 | | `state` * | string | 州/省（2 个字母）。 | | `complement` | string | 地址补充信息。 | | `is_pep` | boolean | （自然人）是否为政治公众人物。 | | `marital_status` | string | （自然人）婚姻状况。 | | `property_system` | string | （自然人）财产制度。 | | `birthdate` | string | （自然人）出生日期。 | | `mother_name` | string | （自然人）母亲姓名。 | | `occupation` | string | （自然人）职业。 | | `trading_name` | string | （法人）商号。 | | `cnae_code` | string | （法人）CNAE 代码（格式："00.00-0-00"）。 | | `company_type` | string | （法人）公司类型。 | | `foundation_date` | string | （法人）成立日期。 | :::warning 注意 必填字段因 `person_type` 而异： - **自然人（`natural`）**：除通用字段外，`is_pep` 为必填。 - **法人（`legal`）**：除通用字段外，`trading_name`、`cnae_code`、`company_type` 和 `foundation_date` 为必填。 ::: ### role_type 枚举 | 枚举值 | 描述 | |--------|------| | `issuer` | 发行人。 | | `investor` | 投资人。 | | `cosigner` | 共同债务人。 | | `fiduciary_debtor` | 信托债务人。 | | `solidary_debtor` | 连带债务人。 | | `guarantor` | 担保人。 | | `bonafide_depositary` | 善意保管人。 | | `intervening_guarantor` | 介入担保人。 | | `intervening_consentor` | 介入同意人。 | | `intervening_discharger` | 介入清偿人。 | | `assignor` | 转让人。 | | `endorser` | 背书人。 | | `consulting` | 咨询方。 | | `fund_administrator` | 基金管理人。 | | `fund_representative` | 基金代表。 | | `company_representative` | 公司代表。 | | `attestant` | 见证人。 | | `debtor` | 债务人。 | | `bestowal` | 授予人。 | | `manager` | 管理人。 | :::tip 担保和基础资产在操作创建后通过 **单独的端点** 提交。请参阅本节的 **登记基础资产** 页面。 ::: ### signature_method 枚举 | 枚举值 | 描述 | |--------|------| | `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。 | | `qi_sign` | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 | ## **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": { ... } } ``` 响应返回所创建操作的完整 JSON，包括 `operation_key`、投资人与关联方列表，以及已计算的财务对象。 --- # 提交文件 URL: /zh-Hans/documentation/escrituracao/emissao-cra/envio-documento 此端点用于 **上传文件** 并返回标识该文件的 `document_key`。当其他操作端点需要先前已上传文件的键时，该 `document_key` 用于引用这些文件。 --- ## **Request** ENDPOINT /cra/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 必需 | |-------------------|--------|----------------------------|------| | `document_base64` * | string | base64 编码的文件内容。 | 是 | | `document_name` | string | 文件名称。 | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |----------------|--------|-------------------------------|------------| | `document_key` * | string | 所上传文件的唯一键（UUID v4）。 | 36 | --- --- # 提交操作的外部文件 URL: /zh-Hans/documentation/escrituracao/emissao-cra/envio-documento-externo 此端点允许将在外部签署的文件提交至书写系统，提交的 base64 将由书写方进行分析和批准。 :::warning 警告 此端点仅应用于使用 **client_side** 签名类型的操作，或用于提交 SA 或合作社类型公司的批准会议纪要。对于通过 QI Sign 或 Certifiqi 的流程，合同以正常方式生成。 ::: --- ## 提交已签署文件 (POST) ### Request ENDPOINT /cra/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------|--------|-------------------------------|--------| | `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。 | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|--------|--------------------|------------------------------------------------------------| | `contract_type` * | string | 已签署文件的类型。 | **[contract_type 枚举](#contract_type-枚举)** | | `contract_base64` * | string | base64 格式的已签署文件。 | - | ### contract_type 枚举 | 枚举值 | 描述 | |---------------------|--------------------------------------------| | `securitization_term` | CRA 证券化条款。 | | `adhesion_term` | CRA 加入条款。 | | `sa_minute` | **SA** 公司CRA发行批准会议纪要。 | | `ltda_minute` | **LTDA** 公司CRA发行批准会议纪要。 | | `cop_minute` | **合作社** CRA发行批准会议纪要。 | ### Response 响应体为更新后的完整操作 JSON。 --- --- # 登记基础资产（Lastro） URL: /zh-Hans/documentation/escrituracao/emissao-cri/cadastro-lastro 此端点用于登记CRI操作的 **基础资产**（lastro）。基础资产代表为证券化提供支撑的债权。资产文件以 base64 提交，其结构化数据随请求一并发送。 :::info 基础资产在 **操作创建后** 通过单独的请求提交。同一操作可登记多个基础资产。 ::: --- ## **Request** ENDPOINT /cri/operation/ OPERATION-KEY /underlying_asset MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------|--------|-------------------------------|--------| | `OPERATION-KEY` * | string | 操作的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | |---------------------------|--------|----------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | 基础资产类型。 | **[underlying_asset_type 枚举](#underlying_asset_type-枚举)** | | `underlying_asset_base64` * | string | base64 格式的基础资产文件。 | - | | `underlying_asset_data` * | object | 基础资产数据（自由结构）。 | - | ### underlying_asset_type 枚举 | 枚举值 | 描述 | |------------|--------| | `contract` | 合同。 | ## **Response** STATUS 201 Response Body ```json { "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23", "underlying_asset_type": "contract", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Response Body Params | 字段 | 类型 | 描述 | |---------------------------|--------|--------------------| | `underlying_asset_key` * | string | 所登记基础资产的唯一键。 | | `underlying_asset_type` * | string | 基础资产类型。 | | `underlying_asset_data` * | object | 基础资产数据。 | --- --- # 登记CRI操作 URL: /zh-Hans/documentation/escrituracao/emissao-cri/cadastro-operacao 此端点通过单个请求创建完整的CRI操作。 :::info `financial` 对象为 **必填**，且必须以已计算好的形式提交，因为此端点不执行财务模拟。发行人及其银行账户必须事先登记。 ::: --- ## **Request** ENDPOINT /cri/create_operation MÉTODO POST 请求体既可以是仅含 **必填字段的负载**（包含财务对象），也可以是同时包含关联方的 **完整负载**。两种变体见下文。 必填字段负载 ```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 } ] } } ``` 完整负载（含关联方） ```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** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | ------------------------------------------ | -------------------------- | | `tenant_key` * | string | tenant 的唯一键。 | - | | `issuer_key` * | string | 发行人的唯一键（须事先登记）。 | - | | `issue_number` * | integer | 发行编号。 | - | | `issue_series` * | integer | 发行系列。 | - | | `issue_date` * | string | 操作发行日期（格式："YYYY-MM-DD"）。 | - | | `signature_method` | string | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举](#signature_method-枚举)** | | `investors` * | array | 相关投资人列表。 | **investors 对象** | | `financial` * | object | 操作的已计算财务数据。 | **financial 对象** | | `contract_number` | string | 合同编号。 | - | | `related_party_list` | array | 操作的关联方（担保人、债务人等）。 | **related_party 对象** | ### investors 对象 | 字段 | 类型 | 描述 | | --------------------------- | ------ | ------------------------------------------ | | `investor_key` * | string | 投资人的唯一键（须事先登记）。 | | `bank_account` * | object | 投资人的银行账户（**bank_account 对象**）。 | | `subscription_percentage` | number | 认购比例。 | | `subscription_quantity` | number | 认购数量。 | ### bank_account 对象 | 字段 | 类型 | 描述 | | ------------------------------------- | ------ | ----------------------------------------------- | | `account_number` * | string | 银行账户号码。 | | `account_digit` * | string | 银行账户校验位。 | | `account_branch` * | string | 银行账户支行。 | | `financial_institution_code_number` | string | 金融机构代码。 | | `financial_institution_ispb` * | string | 金融机构 ISPB 代码。 | | `account_type` * | string | 账户类型（`checking`、`savings`、`salary`、`payment`）。 | ### financial 对象 | 字段 | 类型 | 描述 | | --------------------------- | ------- | ------------------------------------------ | | `financial_base_date` * | string | 财务基准日期（格式："YYYY-MM-DD"）。 | | `interest_type` * | string | 利率类型。 | | `issue_amount` | number | 发行总金额。 | | `issue_quantity` | integer | 发行单位数量。 | | `unit_price` | number | 每单位发行价格。 | | `released_amount` | number | 释放的净金额。 | | `cet` / `annual_cet` | number | 有效总成本（月度与年度），百分比。 | | `number_of_installments` * | integer | 期数。 | | `prefixed_interest_rate` * | object | 固定利率。 | | `fine_delay_rate` | object | 滞纳金利率。 | | `contract_fine_rate` | number | 合同罚款百分比。 | | `fees` | array | 费用列表。 | | `installments` | array | 已计算的期次列表。 | ### related_party 对象 `related_party_list` 中的每一项代表参与该操作的一方。 | 字段 | 类型 | 描述 | | ----------------- | ------- | ----------------------------------------------- | | `person_type` * | string | 人员类型（`natural` 自然人，`legal` 法人）。 | | `name` * | string | 关联方名称。 | | `document_number` * | string | CPF（自然人）或 CNPJ（法人）。 | | `role_type` * | string | 关联方在操作中的角色。**[role_type 枚举](#role_type-枚举)** | | `street` * | string | 街道。 | | `number` * | string | 门牌号。 | | `neighborhood` | string | 街区。 | | `postal_code` * | string | 邮政编码（格式："00000-000"）。 | | `city` * | string | 城市。 | | `state` * | string | 州/省（2 个字母）。 | | `complement` | string | 地址补充信息。 | | `is_pep` | boolean | （自然人）是否为政治公众人物。 | | `marital_status` | string | （自然人）婚姻状况。 | | `property_system` | string | （自然人）财产制度。 | | `birthdate` | string | （自然人）出生日期。 | | `mother_name` | string | （自然人）母亲姓名。 | | `occupation` | string | （自然人）职业。 | | `trading_name` | string | （法人）商号。 | | `cnae_code` | string | （法人）CNAE 代码（格式："00.00-0-00"）。 | | `company_type` | string | （法人）公司类型。 | | `foundation_date` | string | （法人）成立日期。 | :::warning 注意 必填字段因 `person_type` 而异： - **自然人（`natural`）**：除通用字段外，`is_pep` 为必填。 - **法人（`legal`）**：除通用字段外，`trading_name`、`cnae_code`、`company_type` 和 `foundation_date` 为必填。 ::: ### role_type 枚举 | 枚举值 | 描述 | |--------|------| | `issuer` | 发行人。 | | `investor` | 投资人。 | | `cosigner` | 共同债务人。 | | `fiduciary_debtor` | 信托债务人。 | | `solidary_debtor` | 连带债务人。 | | `guarantor` | 担保人。 | | `bonafide_depositary` | 善意保管人。 | | `intervening_guarantor` | 介入担保人。 | | `intervening_consentor` | 介入同意人。 | | `intervening_discharger` | 介入清偿人。 | | `assignor` | 转让人。 | | `endorser` | 背书人。 | | `consulting` | 咨询方。 | | `fund_administrator` | 基金管理人。 | | `fund_representative` | 基金代表。 | | `company_representative` | 公司代表。 | | `attestant` | 见证人。 | | `debtor` | 债务人。 | | `bestowal` | 授予人。 | | `manager` | 管理人。 | :::tip 担保和基础资产在操作创建后通过 **单独的端点** 提交。请参阅本节的 **登记基础资产** 页面。 ::: ### signature_method 枚举 | 枚举值 | 描述 | |--------|------| | `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。 | | `qi_sign` | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 | ## **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": { ... } } ``` 响应返回所创建操作的完整 JSON，包括 `operation_key`、投资人与关联方列表，以及已计算的财务对象。 --- # 提交文件 URL: /zh-Hans/documentation/escrituracao/emissao-cri/envio-documento 此端点用于 **上传文件** 并返回标识该文件的 `document_key`。当其他操作端点需要先前已上传文件的键时，该 `document_key` 用于引用这些文件。 --- ## **Request** ENDPOINT /cri/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 必需 | |-------------------|--------|----------------------------|------| | `document_base64` * | string | base64 编码的文件内容。 | 是 | | `document_name` | string | 文件名称。 | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |----------------|--------|-------------------------------|------------| | `document_key` * | string | 所上传文件的唯一键（UUID v4）。 | 36 | --- --- # 提交操作的外部文件 URL: /zh-Hans/documentation/escrituracao/emissao-cri/envio-documento-externo 此端点允许将在外部签署的文件提交至书写系统，提交的 base64 将由书写方进行分析和批准。 :::warning 警告 此端点仅应用于使用 **client_side** 签名类型的操作，或用于提交 SA 或合作社类型公司的批准会议纪要。对于通过 QI Sign 或 Certifiqi 的流程，合同以正常方式生成。 ::: --- ## 提交已签署文件 (POST) ### Request ENDPOINT /cri/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------|--------|-------------------------------|--------| | `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。 | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|--------|--------------------|------------------------------------------------------------| | `contract_type` * | string | 已签署文件的类型。 | **[contract_type 枚举](#contract_type-枚举)** | | `contract_base64` * | string | base64 格式的已签署文件。 | - | ### contract_type 枚举 | 枚举值 | 描述 | |---------------------|--------------------------------------------| | `securitization_term` | CRI 证券化条款。 | | `adhesion_term` | CRI 加入条款。 | | `sa_minute` | **SA** 公司CRI发行批准会议纪要。 | | `ltda_minute` | **LTDA** 公司CRI发行批准会议纪要。 | | `cop_minute` | **合作社** CRI发行批准会议纪要。 | ### Response 响应体为更新后的完整操作 JSON。 --- --- # 更新操作的拨付账户 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso 此端点允许更新操作的拨付账户。 --- ## **更新操作的拨付账户 (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /issuer_bank_account MÉTODO PUT ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | Request Body ```json { "issuer_bank_account": { "account_number": "4464541", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ``` ### Request Body Params ### **issuer_bank_account 对象** | 字段 | 类型 | 描述 | | --------------------------------------- | ------ | ------------------------------------------ | | `account_number` * | string | 银行账户号码。 | | `account_digit` * | string | 银行账户校验位。 | | `account_branch` * | string | 银行账户支行。 | | `financial_institution_code_number` * | string | 金融机构代码。 | | `financial_institution_ispb` * | string | 金融机构 ISPB 代码。 | | `account_type` * | string | 账户类型（`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": [], "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** | 字段 | 类型 | 描述 | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | tenant 的唯一键。 | | `operation_key` * | string | 操作的唯一键。 | | `operation_status` * | string | 操作的状态。 | | `issuer_key` * | string | 发行人的唯一键。 | | `issuer_name` * | string | 发行人的名称。 | | `issuer_document_number` * | string | 发行人的证件号码。 | | `financial` * | object | **[financial 对象](#objeto-financial-response)** | ### financial response 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | 操作的财务基准日期（格式："YYYY-MM-DD"）。 | - | | `issue_amount` * | number | 操作发行的总金额。 | - | | `released_amount` * | number | 操作中释放的净金额。 | - | | `issue_quantity` * | integer | 发行的总单位数量。 | - | | `unit_price` * | number | 每单位发行价格。 | - | | `cet` * | number | 有效总成本（CET）百分比。 | - | | `annual_cet` * | number | 年化 CET 百分比。 | - | | `number_of_installments` * | integer | 总期数。 | - | | `prefixed_interest_rate` * | object | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** | | `fees` | array | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** | | `installments` | array | 操作中生成的期数详情列表。 | **[installments 对象](#objeto-installments)** | | `fine_delay_rate` * | object | 包含滞纳金详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | 合同罚款百分比。 | - | ### prefixed_interest_rate 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | 利率计算基础。 | **[interest_base 枚举](#enumeradores-interest_base)** | | `monthly_rate` * | number | 适用的月利率。 | - | | `daily_rate` * | number | 适用的日利率。 | - | | `annual_rate` * | number | 适用的年利率。 | - | ### fees 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | 费率百分比值。 | - | | `fee_amount` * | number | 对应的货币金额。 | - | | `amount_type` * | string | 费用值类型。 | **[amount_type 枚举](#enumeradores-amount_type)** | | `fee_type` * | string | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** | | `type` * | string | 费用收款方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** | ### installments 对象 | 字段 | 类型 | 描述 | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | 期数编号。 | | `workdays` * | integer | 至到期日的工作日数。 | | `calendar_days` * | integer | 至到期日的自然日数。 | | `principal_amortization_amount` * | number | 本金摊还金额。 | | `principal_amortization_unit_price` * | number | 每单位摊还金额。 | | `interest_amount` * | number | 该期应计利息金额。 | | `amount` * | number | 该期总金额。 | | `due_date` * | string | 该期到期日（格式："YYYY-MM-DD"）。 | --- # 更新操作的财务数据 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros 此端点允许更新操作中的财务数据，遵循与模拟端点中发送的 financial 对象相同的标准。 --- ## **更新操作的财务数据 (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /financial MÉTODO PUT ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_type` * | string | 适用的利率类型。 | **[interest_type 枚举](#enumeradores-interest_type)** | | `financial_base_date` * | string | 操作基准日期（格式："YYYY-MM-DD"）。 | - | | `released_amount` * | number | 操作释放的总金额。 | - | | `number_of_installments` * | integer | 总期数。 | - | | `prefixed_interest_rate` * | object | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** | | `fine_delay_rate` * | object | 包含滞纳金详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | 合同罚款百分比。 | - | | `fees` | array | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** | ### prefixed_interest_rate 对象 | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | 利率计算基础。 | **[interest_base 枚举](#enumeradores-interest_base)** | | `monthly_rate` * | number | 适用的月利率。 | - | ### fine_delay_rate 对象 | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | 罚款计算基础。 | **[interest_base 枚举](#enumeradores-interest_base)** | | `monthly_rate` * | number | 月罚款率。 | - | ### fees 对象 | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `amount` * | number | 适用的费率值。 | - | | `amount_type` * | string | 费用值类型。 | **[amount_type 枚举](#enumeradores-amount_type)** | | `fee_type` * | string | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** | | `type` * | string | 费用收款方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** | ### interest_type 枚举 | 枚举值 | 描述 | |--------------------|--------------------------------------------| | `pre_price` | Price 模型的固定利率。 | | `pre_price_days` | 按自然日计算的 Price 模型固定利率。 | | `pre_sac` | SAC 模型的固定利率。 | | `post_sac` | SAC 模型的浮动利率。 | ### interest_base 枚举 | 枚举值 | 描述 | |--------------------|--------------------------------------------| | `calendar_days` | 自然日基础。 | | `calendar_days_365`| 365 自然日基础。 | | `workdays` | 工作日基础。 | ### amount_type 枚举 | 枚举值 | 描述 | |-------------|---------------------------| | `percentage` | 百分比值。 | | `absolute` | 货币绝对值。 | ### fee_type 枚举 | 枚举值 | 描述 | |-------------------------------------|-------------------------------------------| | `bookkeeping_fee` | 融资书写费。 | | `structuring_fee` | 融资结构费。 | ### fee_recipient 枚举 | 枚举值 | 描述 | |-----------|-------------------------------------------------------| | `internal` | 支付给书写方的费用。 | | `external` | 支付给发起方的返佣。 | ## **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": [], "installment_list": [] }, "tags": [], "investor_list": [], "related_party_list": [], "collateral_list": [], "metadata_list": [] } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | tenant 的唯一键。 | | `operation_key` * | string | 操作的唯一键。 | | `operation_status` * | string | 操作的状态。 | | `issuer_key` * | string | 发行人的唯一键。 | | `issuer_name` * | string | 发行人的名称。 | | `issuer_document_number` * | string | 发行人的证件号码。 | | `financial` * | object | **[financial 对象](#objeto-financial-response)** | ### financial response 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | 操作的财务基准日期（格式："YYYY-MM-DD"）。 | - | | `issue_amount` * | number | 操作发行的总金额。 | - | | `released_amount` * | number | 操作中释放的净金额。 | - | | `issue_quantity` * | integer | 发行的总单位数量。 | - | | `unit_price` * | number | 每单位发行价格。 | - | | `cet` * | number | 有效总成本（CET）百分比。 | - | | `annual_cet` * | number | 年化 CET 百分比。 | - | | `number_of_installments` * | integer | 总期数。 | - | | `prefixed_interest_rate` * | object | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** | | `fees` | array | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** | | `installments` | array | 操作中生成的期数详情列表。 | **[installments 对象](#objeto-installments)** | | `fine_delay_rate` * | object | 包含滞纳金详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | 合同罚款百分比。 | - | ### prefixed_interest_rate 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | 利率计算基础。 | **[interest_base 枚举](#enumeradores-interest_base)** | | `monthly_rate` * | number | 适用的月利率。 | - | | `daily_rate` * | number | 适用的日利率。 | - | | `annual_rate` * | number | 适用的年利率。 | - | ### fees 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | 费率百分比值。 | - | | `fee_amount` * | number | 对应的货币金额。 | - | | `amount_type` * | string | 费用值类型。 | **[amount_type 枚举](#enumeradores-amount_type)** | | `fee_type` * | string | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** | | `type` * | string | 费用收款方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** | ### installments 对象 | 字段 | 类型 | 描述 | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | 期数编号。 | | `workdays` * | integer | 至到期日的工作日数。 | | `calendar_days` * | integer | 至到期日的自然日数。 | | `principal_amortization_amount` * | number | 本金摊还金额。 | | `principal_amortization_unit_price` * | number | 每单位摊还金额。 | | `interest_amount` * | number | 该期应计利息金额。 | | `amount` * | number | 该期总金额。 | | `due_date` * | string | 该期到期日（格式："YYYY-MM-DD"）。 | --- # 更新操作的签名方式 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura 此端点允许更新操作中的签名方式。 --- ## **更新操作的签名方式 (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signature_method MÉTODO PUT ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | Request Body ```json { "signature_method": "qi_sign" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `signature_method` * | string | 签名系统类型。 | certifiqi 或 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", "financial": {}, "tags": [], "investor_list": [], "related_party_list": [], "collateral_list": [], "metadata_list": [], "signature_method": "qi_sign" } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | tenant 的唯一键。 | | `operation_key` * | string | 操作的唯一键。 | | `operation_status` * | string | 操作的状态。 | | `issuer_key` * | string | 发行人的唯一键。 | | `issuer_name` * | string | 发行人的名称。 | | `issuer_document_number` * | string | 发行人的证件号码。 | | `financial` * | object | **[financial 对象](#objeto-financial-response)** | --- # 在操作中添加担保品 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia 此端点集合允许**添加**与操作关联的担保品。**担保品（collateral）将与操作文件一同提交签名**。每种担保品类型都有其所需文件的规则，所有担保品类型均在本文档中涵盖。 --- ## **提交担保品 (POST)** ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | --- 担保品系统支持添加不同类型的工具，每种类型都有其附加文件的配置。本节涵盖所有可用的担保品模型及其相应的 payload。 ### **担保品类型** **[1 - 不动产信托转让](#alienação-fiduciária-de-imóvel)** **[2 - 车辆信托转让](#alienação-fiduciária-de-veículo)** **[3 - 航空器信托转让](#alienação-fiduciária-de-aeronave)** **[4 - 设备/产品/库存信托转让](#alienação-fiduciária-de-equipamentos-produtos-e-estoque)** **[5 - 艺术品信托转让](#alienação-fiduciária-de-obras-de-arte)** **[6 - 有价证券信托转让](#alienação-fiduciária-de-títulos-e-valores-mobiliários)** **[7 - 股份和份额信托转让](#alienação-fiduciária-de-ações-e-cotas)** **[8 - 信贷权信托转让](#alienação-fiduciária-de-direitos-creditórios)** **[9 - 不动产抵押](#hipoteca-de-imóveis)** **[10 - 船舶抵押](#hipoteca-de-embarcações)** **[11 - 保证人](#aval)** **[12 - 担保人](#fiador)** **[13 - 银行保函](#fiança-bancária)** **[14 - 信用卡应收款](#recebiveis-de-cartão)** **[15 - 库存担保](#garantia-de-estoque)** **[16 - 担保品监控](#monitoramento-de-garantias)** **[17 - 其他担保品](#outras-garantias)** ## **不动产信托转让** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `property_appraisal_report`** | 不动产评估报告。 | | `property_registration_updated`** | 最新产权登记。 | | `property_full_content_certificate`** | 产权完整内容证明。 | | `property_insurance_policy` | 保险单（合同规定时要求）。 | | `others` | 其他文件。 | :::warning (**) 不动产信托转让必须提供 ::: ## **车辆信托转让** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `vehicle_appraisal_report`** | 车辆评估报告（最多延迟30天）或 FIPE 表。 | | `vehicle_inspection_report`** | 车辆检验报告。 | | `vehicle_crv_certificate`** | 最新车辆登记证书（CRLV）。 | | `others` | 其他文件。 | :::warning (**) 车辆信托转让必须提供 ::: ## **航空器信托转让** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `aircraft_certificate_anac`** | 登记证书 - ANAC。 | | `aircraft_rab_consult`** | 巴西航空登记册中的航空器查询。 | | `aircraft_insurance_policy`** | 保险单 - 受益人为基金。 | | `aircraft_appraisal_report`** | 航空器评估报告。 | | `others` | 其他文件。 | :::warning (**) 航空器信托转让必须提供 ::: ## **设备产品和库存信托转让** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `equipment_purchase_invoice`** | 发票 - 购买记录。 | | `equipment_appraisal_report`** | 设备评估报告（最多延迟30天）。 | | `equipment_insurance_policy` | 设备保险单（合同规定时要求）。 | | `fiduciary_depositary_declaration` | 忠实保管人声明。 | | `others` | 其他文件。 | :::warning (**) 设备/产品/库存信托转让必须提供 ::: ## **艺术品信托转让** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `artwork_appraisal_report`** | 艺术品评估报告。 | | `artwork_storage_certificate`** | 带合规证书的存储地点。 | | `artwork_insurance_policy` | 保险单（合同规定时要求）。 | | `others` | 其他文件。 | :::warning (**) 艺术品信托转让必须提供 ::: ## **有价证券信托转让** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `securities_negotiation_block`** | 在托管方处的交易冻结。 | | `securities_registration_gravame` | 带合规证书的存储地点。 | | `others` | 其他文件。 | :::warning (**) 有价证券信托转让必须提供 ::: ## **股份和份额信托转让** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `share_registration_book`** | 带质押注记的记名股份登记簿。 | | `others` | 其他文件。 | :::warning (**) 股份/份额信托转让/质押必须提供 ::: ## **信贷权信托转让** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_assignment_shares" } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `others` | 其他文件。 | ## **不动产抵押** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `property_appraisal_report`** | 不动产评估报告。 | | `property_registration`** | 最新产权登记。 | | `property_full_content_certificate`** | 产权完整内容证明。 | | `property_insurance_policy` | 保险单（合同规定时要求）。 | | `others` | 其他文件。 | :::warning (**) 不动产抵押必须提供 ::: ## **船舶抵押** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `ship_registration`** | 最新船舶产权登记。 | | `ship_appraisal_report`** | 船舶评估报告（最多延迟3个月）。 | | `ship_insurance_policy` | 船舶保险单（合同规定时要求）。 | | `others` | 其他文件。 | :::warning (**) 船舶抵押必须提供 ::: ## **保证人** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `guarantor_civil_status_declaration`** | 保证人婚姻状况声明。 | | `guarantor_personal_document`** | 保证人个人证件。 | | `guarantor_income_tax_declaration` | 保证人所得税申报表。 | | `others` | 其他文件。 | :::warning (**) 保证人必须提供 ::: ## **担保人** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `surety_civil_status_declaration`** | 担保人婚姻状况声明。 | | `surety_personal_document`** | 担保人个人证件。 | | `surety_income_tax_declaration` | 担保人所得税申报表。 | | `others` | 其他文件。 | :::warning (**) 担保人必须提供 ::: ## **银行保函** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `others` | 其他文件。 | ## **信用卡应收款** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `others` | 其他文件。 | ## **库存担保** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `others` | 其他文件。 | ## **担保品监控** 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" } ] } ``` ### **文件类型** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `guarantee_contract`** | 担保合同。 | | `guarantee_agent_contract`** | 担保代理合同。 | | `others` | 其他文件。 | :::warning (**) 担保品监控必须提供 ::: --- ## **Request Body Params** | 字段 | 类型 | 描述 | 必填 | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `collateral_document_key` * | string | 担保工具的键。 | 是 | | `collateral_type` * | string | 担保品类型。 | **[collateral_type 枚举](#enumeradores-collateral_type)** | | `collateral_data` | object | 与担保品相关的元数据结构。 | 是 | | `additional_documents` | list | 与担保品相关的文件。 | - | ### **additional_documents 列表** | 字段 | 类型 | 描述 | 必填 | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `document_key` * | string | 担保工具的键。 | 是 | | `document_type` * | string | 担保品文件类型。 | 是 | ### **collateral_type 枚举** | 枚举值 | 描述 | |-----------------|-----------------------------------| | `fiduciary_alienation_property` | 不动产信托转让。 | | `fiduciary_alienation_vehicle` | 车辆信托转让。 | | `fiduciary_alienation_aircraft` | 航空器信托转让。 | | `fiduciary_alienation_equipment` | 设备/产品/库存信托转让。 | | `fiduciary_alienation_artwork` | 艺术品信托转让。 | | `fiduciary_alienation_securities` | 有价证券信托转让。 | | `fiduciary_assignment_shares` | 股份/份额信托转让/质押。 | | `fiduciary_assignment_credit_rights` | 信贷权信托转让。 | | `mortgage_property` | 不动产抵押。 | | `mortgage_ship` | 船舶抵押。 | | `guarantor` | 保证人。 | | `surety` | 担保人。 | | `bank_surety` | 银行保函。 | | `card_receivables` | 信用卡应收款。 | | `stock_guarantee` | 库存担保。 | | `monitoring_guarantee` | 担保品监控。 | | `others` | 其他担保品。 | --- # 从操作中移除担保品 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia 此端点允许**移除**与操作关联的担保品。 --- ## **移除 Collateral (DELETE)** ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral/ COLLATERAL-KEY MÉTODO DELETE ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | | `COLLATERAL-KEY` * | string | 待移除的担保品唯一键（UUID v4）。 | 36 | ## **Response** STATUS 204 **响应体中不返回任何内容。** --- # 文件上传 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento 此端点允许上传与操作关联的**文件**。这些文件可用于担保品系统，在担保工具之外添加附属文件。 --- ## **上传文件 (POST)** ## **Request** ENDPOINT /commercial_paper/upload MÉTODO POST Request Body ```json { "document_base64": "sringb64" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 必填 | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `document_base64` * | string | Base64 编码的文件内容。 | 是 | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ## **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|----------------------------------------------|-----------------| | `document_key` * | string | 已添加文件的唯一键（UUID v4）。 | 36 | --- --- # 在操作中登记和删除元数据 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao 此端点集合允许在操作中登记和删除元数据。 --- ## **在操作中登记元数据 (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | Request Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | 元数据键。 | 255 | | `metadata_value` * | string | 元数据值。 | 1023 | ### **Response** STATUS 201 Response Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | 元数据键。 | 255 | | `metadata_value` * | string | 元数据值。 | 1023 | --- ## **从操作中删除元数据 (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata MÉTODO DELETE ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | Request Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | 元数据键。 | 255 | | `metadata_value` * | string | 元数据值。 | 1023 | --- ### **Response** STATUS 204 **响应体中不返回任何内容。** --- # 发送和删除关联方代表的文件 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento 此端点集合允许发送和删除与操作关联方代表相关的文件。 --- ## **发送代表文件 (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | | `RELATED-PARTY-KEY` * | string | 关联方的唯一键（UUID v4）。 | 36 | Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|-----------------------------------------------------------------|-----------------| | `document_base64` * | string | Base64 编码的文件内容。 | - | | `document_type` * | string | 提交的文件类型。 | **[document_type 枚举](#enumeradores-document_type)** | ## **Response** STATUS 201 Response Body **场景 1：自动验证（OCR 成功）** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **含义**：文件已由我们的 OCR 自动处理并验证。 **场景 2：需要人工核查** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnh", "ocr_key": null } ``` **含义**：文件无法通过 OCR 自动验证，已转入人工核查队列。 :::warning 注意 成功请求的响应（提交成功）根据自动验证（OCR）结果会呈现两种不同行为。 ::: ### **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|----------------------------------------------|-----------------| | `document_key` * | string | 提交文件的唯一标识符。 | 36 | | `document_type` * | string | 提交的文件类型。 | **[document_type 枚举](#enumeradores-document_type)** | | `ocr_key` | string | 与提交文件关联的 OCR 键。 | 36 | --- ## **删除代表文件 (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | | `RELATED-PARTY-KEY` * | string | 关联方的唯一键（UUID v4）。 | 36 | | `DOCUMENT-KEY` * | string | 待删除文件的唯一键。 | 36 | ### **Response** STATUS 204 **响应体中不返回任何内容。** ### **document_type 枚举** | 枚举值 | 描述 | |---------------------------|-----------------------------------------| | `proof_of_address` | 地址证明。 | | `letter_of_attorney` | 委托书。 | | `company_statute` | 公司章程。 | | `cnh` | 全国驾驶证（CNH）。 | | `cnh_front` | CNH 正面。 | | `cnh_back` | CNH 背面。 | | `cnh_digital` | 数字 CNH。 | | `rg_front` | 身份证正面。 | | `rg_back` | 身份证背面。 | --- # 发送和删除关联方代表的签名人组 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes 此端点集合允许发送和删除与操作关联方代表相关的签名人组。 --- ## **发送签名人组 (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |-----------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | | `RELATED-PARTY-KEY` * | string | 关联方的唯一键（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** | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|--------------------------------------------------------|-----------------| | `minimum_required_signers` * | integer | 组内所需的最少签名人数。 | - | | `signers` * | array | 组内签名人列表。 | **[signers 对象](#objeto-signers)** | --- ### **signers 对象** | 字段 | 类型 | 描述 | 最大字符数 | |--------------------------|----------|-------------------------------------------------|-----------------| | `name` * | string | 签名人全名。 | 255 | | `document_number` * | string | 签名人 CPF（11 位数字）。 | 11 | | `email` * | string | 签名人电子邮件地址。 | 1023 | | `phone_number` * | string | 含国际区号的签名人电话号码。 | 20 | | `is_group_mandatory` * | boolean | 指示签名人是否为必须签名人。 | - | ## **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** | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|-------------------------------------------------|-----------------| | `signer_group_key` * | string | 签名人组的唯一键（UUID v4）。 | 36 | | `minimum_required_signers` * | integer | 组内所需的最少签名人数。 | - | | `signers` * | array | 组内签名人列表。 | **[signers 对象](#objeto-signers)** | --- ## **删除签名人组 (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group/ SIGNER-GROUP-KEY MÉTODO DELETE ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |-----------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | | `RELATED-PARTY-KEY` * | string | 关联方的唯一键（UUID v4）。 | 36 | | `SIGNER-GROUP-KEY` * | string | 签名人组的唯一键。 | 36 | ### **Response** STATUS 204 **响应体中不返回任何内容。** --- # 在特定文件中登记和删除关联方 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento 此端点集合允许在操作的特定文件中登记和删除关联方。 --- ## **将关联方添加到文件 (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document /FORMALIZATION-DOCUMENT-KEY /related_party MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | | `FORMALIZATION-DOCUMENT-KEY` * | string | 操作文件的唯一键（UUID v4）。 | 36 | Request Body ```json { "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 最大字符数 | | --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `related_party_key` * | string | 关联方的键。 | 36 | ## **Response** STATUS 204 **响应体中不返回任何内容。** ## **删除关联方 (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document/ FORMALIZATION-DOCUMENT-KEY /related_party MÉTODO DELETE ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | | ----------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | | `FORMALIZATION-DOCUMENT-KEY` * | string | 操作文件的唯一键（UUID v4）。 | 36 | Request Body ```json { "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Response** STATUS 204 **响应体中不返回任何内容。** --- # 登记和删除关联方 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada 此端点集合允许在操作中登记和删除关联方。 :::warning 所有关联方默认会被添加到组成性条款（**commercial_paper**）中，如需将该关联方添加到特定文件，请在 **related_document_key** 字段中填写所需文件的键。 ::: --- ## **登记关联方 (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | :::info 重要 **构建 payload 时请注意人员类型：** - **自然人（PF）**：`"person_type": "natural"` - **法人（PJ）**：`"person_type": "legal"` ::: Request Body - 自然人（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 - 法人（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** | 字段 | 类型 | 描述 | 最大字符数 | | --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `person_type` * | string | 人员类型。 | **[person_type 枚举](#enumeradores-person_type)** | | `name` * | string | 关联方名称。 | 255 | | `document_number` * | string | CPF（格式："XXX.XXX.XXX-XX"）或 CNPJ（格式："XX.XXX.XXX/XXXX-XX"）。 | 14 | | `street` * | string | 地址街道。 | 500 | | `neighborhood` | string | 地址区域。 | 100 | | `number` * | string | 地址门牌号。 | 10 | | `postal_code` * | string | 邮政编码（格式："XXXXX-XXX"）。 | 8 | | `city` * | string | 地址城市。 | 255 | | `state` * | string | 州缩写（2个字符）。 | 2 | | `role_type` * | string | 关联方角色。 | **[role_type 枚举](#enumeradores-role_type)** | | `related_document_key` | string | 文件标识键（UUIDv4）。 | 36 | ### **person_type 枚举** | 枚举值 | 描述 | | ----------- | ---------------- | | `natural` | 自然人 | | `legal` | 法人 | ### **自然人额外字段** | 字段 | 类型 | 描述 | 最大字符数 | | ---------------------------------- | ------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------- | | `document_identification_number` | string | 身份证号（无格式）。 | 20 | | `marital_status` | string | 婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** | | `property_system` | string | 夫妻财产制度。 | **[property_system 枚举](#enumeradores-property_system)** | | `birthdate` | string | 出生日期（YYYY-MM-DD）。 | - | | `nationality` | string | 国籍。 | 255 | | `mother_name` | string | 母亲姓名。 | 255 | | `father_name` | string | 父亲姓名。 | 255 | | `occupation` | string | 职业。 | 255 | | `is_pep` * | boolean | 指示关联方是否为政治公众人物（PEP）。 | | ### **法人额外字段** | 字段 | 类型 | 描述 | 最大字符数 | | --------------------- | ------ | -------------------------------------- | -------------------------------------------------------------- | | `trading_name` * | string | 公司商业名称。 | 1023 | | `cnae_code` * | string | 公司 CNAE 代码（10位数字）。 | 10 | | `company_type` * | string | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** | | `foundation_date` * | string | 成立日期（YYYY-MM-DD）。 | - | ### **role_type 枚举** | 枚举值 | 描述 | | -------------------------- | ------------------------ | | `cosigner` | 共同签署人 | | `fiduciary_debtor` | 信托债务人 | | `solidary_debtor` | 连带债务人 | | `surety` | 保证人 | | `guarantor` | 担保人 | | `bonafide_depositary` | 忠实保管人 | | `intervening_guarantor` | 介入担保人 | | `intervening_consentor` | 介入同意人 | | `intervening_discharger` | 介入清偿人 | | `assignor` | 出让人 | | `endorser` | 背书人 | | `consulting` | 顾问 | | `fund_administrator` | 基金管理人 | | `fund_representative` | 基金代表 | | `company_representative` | 公司代表 | | `attestant` | 见证人 | | `debtor` | 债务人 | | `bestowal` | 配偶同意 | | `manager` | 管理人 | ### marital_status 枚举 | 枚举值 | 描述 | | ----------- | ---------------- | | `single` | 单身 | | `married` | 已婚 | | `divorced` | 离婚 | | `widowed` | 丧偶 | | `separated` | 分居 | | `stable_union`| 稳定伴侣关系 | ### property_system 枚举 | 枚举值 | 描述 | | --------------------------------- | -------------------------------------- | | `total_communion_of_goods` | 完全共同财产制 | | `partial_communion_of_goods` | 部分共同财产制 | | `total_separation_of_goods` | 完全分别财产制 | | `final_participation_of_acquisitions` | 婚后所得共同制 | | `compulsory_separation_of_goods` | 法定分别财产制 | ### company_type 枚举 | 枚举值 | 描述 | | ------------------- | ---------------------------- | | `ltda` | 有限责任公司 | | `sa` | 股份公司 | | `cop` | 合作社 | ## **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** | 字段 | 类型 | 描述 | 最大字符数 | | ----------------------- | ------- | ---------------------------------------------------- | ------------------------------------------------------------ | | `related_party_key` * | string | 关联方的唯一键。 | 36 | | `name` * | string | 关联方名称。 | 255 | | `document_number` * | string | 关联方的 CPF/CNPJ。 | 14 | | `role_type` * | string | 关联方角色。 | 50 | | `is_active` * | boolean | 指示是否处于活动状态。 | - | | `updated_at` | string | 最后更新日期（YYYY-MM-DD HH:mm:ss）。 | - | | `person_type` * | string | 人员类型。 | **[person_type 枚举](#enumeradores-person_type)** | | `street` * | string | 街道。 | 500 | | `neighborhood` | string | 区域。 | 100 | | `number` * | string | 门牌号。 | 10 | | `postal_code` * | string | 邮政编码（仅数字）。 | 8 | | `city` * | string | 城市。 | 255 | | `state` * | string | 州缩写（2个字符）。 | 2 | --- ## **删除关联方 (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY MÉTODO DELETE ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | | ----------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | | `RELATED-PARTY-KEY` * | string | 关联方的唯一键。 | 36 | ### **Response** STATUS 204 **响应体中不返回任何内容。** --- # 登记商业票据操作 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao 此端点允许根据财务数据和投资人数据创建新的商业票据操作。 --- ## **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** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------------- | ------ | ------------------------------------------------------ | ---------------------------------------------------------------- | | `issuer_key` * | string | 发行人的唯一键。 | - | | `issuer_bank_account` * | object | 发行人的银行账户。 | **[issuer_bank_account 对象](#objeto-issuer_bank_account)** | | `investors` * | array | 相关投资人列表。 | **[investors 对象](#objeto-investors)** | | `issue_date` * | string | 操作发行日期（格式："YYYY-MM-DD"）。 | - | | `signature_method` | string | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举值](#signature_method-枚举值)** | | `financial` * | object | 操作的财务数据。 | **[financial 对象](#objeto-financial)** | | `third_party_disbursement` | object | 第三方拨付指令。可选；需先开通该功能。 | **[third_party_disbursement 对象](#third_party_disbursement-对象)** | ### **issuer_bank_account 对象** | 字段 | 类型 | 描述 | | --------------------------------------- | ------ | ------------------------------------------ | | `account_number` * | string | 银行账户号码。 | | `account_digit` * | string | 银行账户校验位。 | | `account_branch` * | string | 银行账户支行。 | | `financial_institution_code_number` * | string | 金融机构代码。 | | `financial_institution_ispb` * | string | 金融机构 ISPB 代码。 | | `account_type` * | string | 账户类型（`checking`、`savings`）。 | ### **investors 对象** | 字段 | 类型 | 描述 | | ----------------------------- | ------ | ------------------------------ | | `investor_key` * | string | 投资人的唯一键。 | | `subscription_percentage` * | number | 认购比例。 | | `bank_account` * | object | 投资人的银行账户。 | ### **financial 对象** | 字段 | 类型 | 描述 | | ---------------------------- | ------- | -------------------------------------------- | | `interest_type` * | string | 利率类型。 | | `financial_base_date` * | string | 财务基准日期（格式："YYYY-MM-DD"）。 | | `released_amount` | number | 释放金额。 | | `issue_amount` | number | 发行金额。 | | `number_of_installments` * | integer | 期数。 | | `installments` | array | **[installments 对象](#objeto-installments)** | | `prefixed_interest_rate` * | object | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** | | `fine_delay_rate` * | object | 滞纳金利率。 | | `contract_fine_rate` * | number | 合同罚款百分比。 | | `fees` | array | 费用列表。 | :::warning 注意 **financial 对象**必须包含有效的参数组合才能被处理。接受的组合为：发行/释放金额 + 利率、发行/释放金额 + 每期金额、每期金额 + 利率、发行/释放金额 + 利率 + 每期摊还比例。 ::: ### installments 对象 | 字段 | 类型 | 描述 | |------------------------------|----------|-----| | `due_date` * | string | 期次到期日（格式："YYYY-MM-DD"）。 | | `amount` | number | 期次总金额。 | | `principal_amortization_percentage` | number | 本金摊还百分比值。 | ### prefixed_interest_rate 对象 | 字段 | 类型 | 描述 | |------------------------------|----------|-----| | `interest_base` * | string | 利率计算基础。 | | `daily_rate` | number | 适用的日利率。 | | `monthly_rate` | number | 适用的月利率。 | | `annual_rate` | number | 适用的年利率。 | ### **third_party_disbursement 对象** 可选指令，表示释放的金额将支付给第三方收款方，而不是支付到发行人的清算账户。该对象不接受所列字段之外的任何字段（`additionalProperties: false`），且 TED 与 boleto 两条通道互斥。 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | `payment_method` * | string | 拨付所使用的支付通道（`ted`、`bank_slip`、`pix`）。 | - | | `target_account` | object | 收款方的银行账户。当 `payment_method` 为 `ted` 时必填；在其他通道下禁止发送。 | **[target_account 对象](#target_account-对象)** | | `digitable_line` | string | 收款方 boleto 的可键入行，仅数字（格式 `^[0-9]{47}$`）。当 `payment_method` 为 `bank_slip` 时必填；在其他通道下禁止发送。 | 47 | | `pix_key` | string | 收款方的 Pix 密钥；CPF 与 CNPJ **不带格式符号**。当 `payment_method` 为 `pix` 时必填；在其他通道下禁止发送。 | 77 | | `pix_key_type` | string | 所声明的 Pix 密钥类型（`cpf`、`cnpj`、`phone`、`email`、`evp`）。当 `payment_method` 为 `pix` 时必填；在其他通道下禁止发送。 | - | | `beneficiary` | object | 第三方收款人的资格信息。当 `payment_method` 为 `pix` 时**必填**；在 `ted` 与 `bank_slip` 下为可选。 | **[操作的第三方拨付](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro)** | :::info 需申请开通的功能 发送 `third_party_disbursement` 需要事先向 QI Tech 申请开通；未开通时，创建操作会以 `COM000062` 被拒绝。完整规则 — 包括 boleto 金额的核对、Pix 密钥类型以及 `beneficiary` 对象的字段 — 见[操作的第三方拨付](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro)。 ::: ### **target_account 对象** | 字段 | 类型 | 描述 | 最大字符数 | | --------------------------------------- | ---------------- | ------------------------------------------------------------ | --------------- | | `account_branch` * | string | 收款方银行账户的支行，仅数字（正好 4 位）。 | 4 | | `account_number` * | string | 收款方银行账户的号码，仅数字（1 至 20 位）。 | 20 | | `account_digit` * | string | 收款方银行账户的校验位，仅数字（正好 1 位）。 | 1 | | `financial_institution_ispb` * | string | 收款方金融机构的 ISPB 代码，仅数字（正好 8 位）。决定 TED 的路由。 | 8 | | `financial_institution_code_number` | string 或 `null` | 收款方金融机构的代码，仅数字（3 位）。可选，且不参与路由。 | 3 | | `account_type` * | string | 收款方的账户类型（`checking`、`savings`、`salary`、`payment`）。 | - | | `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ，需**带格式**（`000.000.000-00` 或 `00.000.000/0000-00`）。系统会校验其校验位。 | 18 | | `owner_name` * | string | 账户持有人的姓名（1 至 50 个字符）。 | 50 | ### signature_method 枚举值 | 值 | 描述 | | ----------- | ------------------------------------------------------------------------------------------------------------ | | `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。 | | `qi_sign` | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 | | `client_side` | 文件在 QI Tech 平台之外签署，并通过**[提交已签署文件端点](/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados)**提交。不会生成签名 URL。 | ## **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** | 字段 | 类型 | 描述 | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | tenant 的唯一键。 | | `operation_key` * | string | 操作的唯一键。 | | `operation_status` * | string | 操作的状态。 | | `issuer_key` * | string | 发行人的唯一键。 | | `issuer_name` * | string | 发行人的名称。 | | `issuer_document_number` * | string | 发行人的证件号码。 | | `financial` * | object | **[financial 对象](#objeto-financial-response)** | ### financial response 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | 操作的财务基准日期（格式："YYYY-MM-DD"）。 | - | | `issue_amount` * | number | 操作发行的总金额。 | - | | `released_amount` * | number | 操作中释放的净金额。 | - | | `issue_quantity` * | integer | 发行的总单位数量。 | - | | `unit_price` * | number | 每单位发行价格。 | - | | `cet` * | number | 有效总成本（CET）百分比。 | - | | `annual_cet` * | number | 年化 CET 百分比。 | - | | `number_of_installments` * | integer | 总期数。 | - | | `prefixed_interest_rate` * | object | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate-response)** | | `fees` | array | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** | | `installments` | array | 操作中生成的期数详情列表。 | **[installments 对象](#objeto-installments-response)** | | `fine_delay_rate` * | object | 包含滞纳金详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | 合同罚款百分比。 | - | ### prefixed_interest_rate response 对象 | 字段 | 类型 | 描述 | | ------------------- | ------ | ------------------------------- | | `interest_base` * | string | 利率计算基础。 | | `monthly_rate` | number | 适用的月利率。 | | `daily_rate` | number | 适用的日利率。 | | `annual_rate` | number | 适用的年利率。 | ### fees 对象 | 字段 | 类型 | 描述 | | ----------------- | ------ | ---------------------------------------- | | `amount` * | number | 费率百分比值。 | | `fee_amount` * | number | 对应的货币金额。 | | `amount_type` * | string | 费用值类型。 | | `fee_type` * | string | 费用类型。 | | `type` * | string | 费用收款方。 | ### installments response 对象 | 字段 | 类型 | 描述 | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | 期数编号。 | | `workdays` * | integer | 至到期日的工作日数。 | | `calendar_days` * | integer | 至到期日的自然日数。 | | `principal_amortization_amount` * | number | 本金摊还金额。 | | `principal_amortization_unit_price` * | number | 每单位摊还金额。 | | `interest_amount` * | number | 该期应计利息金额。 | | `amount` * | number | 该期总金额。 | | `due_date` * | string | 该期到期日（格式："YYYY-MM-DD"）。 | --- # 操作的第三方拨付 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro 此端点用于设置或替换一笔操作的第三方拨付指令，表示释放的金额将支付给第三方收款方（例如供应商），而不是支付到发行人的清算账户。 :::info 需申请开通的功能 第三方拨付默认不开通。集成前请先向 QI Tech 申请开通 — 未开通时，请求会以 `COM000062` 被拒绝。 ::: :::warning 整体替换与可变更窗口 该请求会**替换整条指令** — 不支持字段级的部分更新。只有当操作处于 `in_filling` 状态时才能设置或变更该指令；不在该状态时，请求会以 `COM000010` 被拒绝。 ::: --- ## **操作的第三方拨付 (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /third_party_disbursement MÉTODO PUT ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | Request Body — TED ```json { "payment_method": "ted", "target_account": { "account_branch": "0001", "account_number": "4464541", "account_digit": "3", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329", "account_type": "checking", "owner_document_number": "11.222.333/0001-81", "owner_name": "Fornecedor Exemplo LTDA" } } ``` Request Body — Boleto ```json { "payment_method": "bank_slip", "digitable_line": "34191790010104351004791020150008291070100000000" } ``` Request Body — Pix ```json { "payment_method": "pix", "pix_key": "52998224725", "pix_key_type": "cpf", "beneficiary": { "person_type": "natural", "name": "João da Silva", "document_number": "529.982.247-25", "street": "Rua das Flores", "number": "100", "postal_code": "01234-567", "city": "São Paulo", "state": "SP", "is_pep": false } } ``` ### **Request Body Params** 请求体不接受所列字段之外的任何字段（`additionalProperties: false`）。三条通道互斥，且该互斥性由 schema 保证：在某一通道下发送其他通道的字段、遗漏所选通道的必填字段，或发送未知字段，都会返回 `QIT000001`。 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | `payment_method` * | string | 拨付所使用的支付通道。 | **[payment_method 枚举值](#payment_method-枚举值)** | | `target_account` | object | 收款方的银行账户。当 `payment_method` 为 `ted` 时必填；在其他通道下禁止发送。 | **[target_account 对象](#target_account-对象)** | | `digitable_line` | string | 收款方 boleto 的可键入行，仅数字（格式 `^[0-9]{47}$`）。当 `payment_method` 为 `bank_slip` 时必填；在其他通道下禁止发送。 | 47 | | `pix_key` | string | 收款方的 Pix 密钥；CPF 与 CNPJ **不带格式符号**。当 `payment_method` 为 `pix` 时必填；在其他通道下禁止发送。 | 77 | | `pix_key_type` | string | 所声明的 Pix 密钥类型。当 `payment_method` 为 `pix` 时必填；在其他通道下禁止发送。 | **[pix_key_type 枚举值](#pix_key_type-枚举值)** | | `beneficiary` | object | 第三方收款人的资格信息。当 `payment_method` 为 `pix` 时**必填**；在 `ted` 与 `bank_slip` 下为可选。 | **[beneficiary 对象](#beneficiary-对象)** | ### **payment_method 枚举值** | 值 | 描述 | | ------------- | ------------------------------------------------ | | `ted` | 通过 TED 支付至 `target_account` 中填写的账户。 | | `bank_slip` | 支付 `digitable_line` 中填写的 boleto。 | | `pix` | 通过 Pix 支付至 `pix_key` 中填写的密钥。 | ### **pix_key_type 枚举值** | 值 | 描述 | | -------- | -------------------------------------------- | | `cpf` | CPF，11 位数字，不带标点。 | | `cnpj` | CNPJ，14 位数字，不带标点。 | | `phone` | 电话号码，格式为 `+55` 后接 10 或 11 位数字。 | | `email` | 电子邮箱地址，最多 77 个字符。 | | `evp` | 随机密钥（小写 UUID）。 | 密钥的**格式**由 schema 依据所声明的 `pix_key_type` 校验 — 格式不符时返回 `QIT000001`。对于 `cpf` 与 `cnpj`，随后还会校验**校验位**：格式正确但校验位错误时返回 `COM000071`。 ### **target_account 对象** | 字段 | 类型 | 描述 | 最大字符数 | | --------------------------------------- | ---------------- | ------------------------------------------------------------ | ------------------------------------------------------ | | `account_branch` * | string | 收款方银行账户的支行，仅数字（正好 4 位）。 | 4 | | `account_number` * | string | 收款方银行账户的号码，仅数字（1 至 20 位）。 | 20 | | `account_digit` * | string | 收款方银行账户的校验位，仅数字（正好 1 位）。 | 1 | | `financial_institution_ispb` * | string | 收款方金融机构的 ISPB 代码，仅数字（正好 8 位）。决定 TED 的路由。 | 8 | | `financial_institution_code_number` | string 或 `null` | 收款方金融机构的代码，仅数字（3 位）。可选，且不参与路由。 | 3 | | `account_type` * | string | 收款方的账户类型。 | **[account_type 枚举值](#account_type-枚举值)** | | `owner_document_number` * | string | 账户持有人的 CPF 或 CNPJ，需**带格式**（`000.000.000-00` 或 `00.000.000/0000-00`）。系统会校验其校验位。 | 18 | | `owner_name` * | string | 账户持有人的姓名（1 至 50 个字符）。 | 50 | ### **account_type 枚举值** | 值 | 描述 | | ------------ | ---------------------- | | `checking` | 活期账户。 | | `savings` | 储蓄账户。 | | `salary` | 工资账户。 | | `payment` | 支付账户。 | ### **beneficiary 对象** 用于标识收款第三方。在 `pix` 通道下为必填 — 仅凭 Pix 密钥无法说明收款人是谁 — 在 `ted` 与 `bank_slip` 下为可选。该对象随指令一同流转，与操作一同被签署，并用于形成第三方付款的公司会议纪要。 **仅 `name` 与 `document_number` 为必填。** 其余字段均为可选，用于在会议纪要中补充收款方的资格信息。 | 字段 | 类型 | 描述 | 是否必填 | | ----- | ---- | ------ | -------- | | `person_type` | string | `natural`（自然人）或 `legal`（法人）。 | 可选 | | `name` * | string | 收款方名称。 | 始终 | | `document_number` * | string | CPF 或 CNPJ，**带格式符号**（`000.000.000-00` 或 `00.000.000/0000-00`）。 | 始终 | | `street` | string | 街道名称。 | 可选 | | `number` | string | 门牌号。 | 可选 | | `postal_code` | string | 邮编，格式为 `00000-000`。 | 可选 | | `city` | string | 城市。 | 可选 | | `state` | string | 州（UF），两位大写字母。 | 可选 | | `is_pep` | boolean | 是否为政治公众人物（PEP）。 | 可选 | | `trading_name` | string | 商号名称。 | 可选 | | `cnae_code` | string | CNAE，格式为 `00.00-0-00`。 | 可选 | | `company_type` | string | 企业类型。 | 可选 | | `foundation_date` | string | 成立日期（`YYYY-MM-DD`）。 | 可选 | | `neighborhood` | string | 街区。 | 可选 | | `complement` | string | 地址补充信息。 | 可选 | | `document_identification_number` | string | 身份证件号码。 | 可选 | | `marital_status` | string | 婚姻状况。 | 可选 | | `property_system` | string | 夫妻财产制。 | 可选 | | `birthdate` | string | 出生日期（`YYYY-MM-DD`）。 | 可选 | | `nationality` | string | 国籍。 | 可选 | | `mother_name` | string | 母亲姓名。 | 可选 | | `father_name` | string | 父亲姓名。 | 可选 | | `occupation` | string | 职业。 | 可选 | :::tip 发送得越多，会议纪要越完整 提供 `person_type` 时，会议纪要会包含收款方的**资格信息**；同时提供 `street`、`number`、`postal_code`、`city` 与 `state`（五项齐备）时，还会包含格式化后的**地址**。仅发送姓名与证件号码时，会议纪要只会列出收款方名称，不含资格信息与地址：不会报错，只是文档内容较为简略。 ::: :::warning TED — 请核对 ISPB TED 的目标机构由 `financial_institution_ispb` 决定。ISPB 填错会把资金汇往错误的机构，即使 `financial_institution_code_number` 是正确的。 ::: :::warning Boleto — 金额必须与释放金额一致 Boleto 的金额取自**可键入行的最后 10 位数字，以分为单位**，且必须等于操作的 `financial.released_amount`。任何差异都会以 `COM000061` 被拒绝。 由于计算得到的 `released_amount` 会因费用而与申请金额不同，实际可行的做法是：先创建操作，读取响应中的 `released_amount`，然后再附上正好为该金额的 boleto。**请勿改写真实可键入行中的金额** — 这会使其校验位失效，boleto 将无法支付。 一张商业票据只支付一个收款方，且为全额支付：不支持付款拆分。 ::: ## **Response** STATUS 200 响应返回操作的完整对象，其形式与[按键值查询操作](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave)返回的一致。 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_type": "commercial_paper", "operation_status": "in_filling", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28.980.395/0001-55", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "financial": { ... } } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | tenant 的唯一键。 | | `operation_key` * | string | 操作的唯一键。 | | `operation_status` * | string | 操作的状态。 | | `issuer_key` * | string | 发行人的唯一键。 | | `issuer_name` * | string | 发行人的名称。 | | `issuer_document_number` * | string | 发行人的证件号码。 | | `financial` * | object | 操作的财务数据。 | :::info 该指令在操作对象中以 `third_party_disbursement` 的形式出现，与提交时的形式一致。当操作没有第三方拨付时，该键会从响应中**省略** — 不会返回 `null`。 ::: --- ## **错误** 以下错误代码同样记录在[错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros)中。 | 错误代码 | HTTP | 描述 | | ---------- | ---- | ---------------------------------------------------------- | | `QIT000001` | 400 | Schema 校验失败 — 例如 `payment_method` 缺失或不在枚举范围内、`target_account` 与 `digitable_line` 的组合无效、`digitable_line` 不符合 47 位数字的格式，或请求体中含有未知字段。 | | `COM000010` | 400 | 操作不处于 `in_filling` 状态，无法更新。 | | `COM000061` | 400 | Boleto 金额与操作的 `released_amount` 不一致。 | | `COM000062` | 400 | 未开通第三方拨付功能。 | | `COM000063` | 400 | 收款方证件号码无效。 | | `COM000071` | 400 | `cpf`/`cnpj` 类型的 `pix_key` 校验位无效。 | | `COM000007` | 404 | 未找到该操作。 | | `COM000008` | 403 | 该操作不属于发起请求的 tenant。 | --- # 扩展字段（Extra Fields） URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields 这组端点用于查询文档模板中可用的扩展字段，并为某笔操作中的这些字段保存自定义取值。 :::warning 使用扩展字段的前提是文档模板已经确定。否则，请先生成一份草稿预览，再使用这些端点。 ::: :::info 重要 扩展字段按文档类型（`document_type`）组织。通过 POST 保存扩展字段时，该 `document_type` 下此前的取值会被**整体替换** — 不会与已有取值进行合并。 ::: --- ## **查询可用扩展字段（GET）** 返回与该操作文档类型关联的模板中可用的扩展字段。 ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields 方法 GET ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | --------------------------- | --------- | | `OPERATION-KEY` * | string | 操作的唯一键值（UUID v4）。 | 36 | ### **Query Params** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | ----------- | --------- | | `document_type` * | string | 文档类型。 | **[document_type 枚举值](#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** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | --------------------------------------- | --------- | | `operation_key` * | string | 操作的唯一键值（UUID v4）。 | 36 | | `document_type` * | string | 所查询的文档类型。 | **[document_type 枚举值](#document_type-枚举值)** | | `template_key` * | string | 关联模板的唯一键值（UUID v4）。 | 36 | | `extra_fields` * | array | 模板中可用的扩展字段列表。 | - | ### **extra_fields 对象的字段** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | --------------------------------- | --------- | | `field_key` * | string | 扩展字段的唯一标识。 | 255 | | `field_label` * | string | 扩展字段的描述性标签。 | 255 | | `field_type` * | string | 扩展字段的数据类型（例如 `string`）。 | 50 | --- ## **保存扩展字段（POST）** 为某笔操作中特定文档类型保存扩展字段的取值。所提交的取值会整体替换该 `document_type` 下此前的扩展字段。 ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields 方法 POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | --------------------------- | --------- | | `OPERATION-KEY` * | string | 操作的唯一键值（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** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | --------------------------------------- | --------- | | `document_type` * | string | 文档类型。 | **[document_type 枚举值](#document_type-枚举值)** | | `extra_fields` * | object | 包含扩展字段及其取值的对象。其键必须与 GET 查询返回的 `field_key` 一致。所有取值必须为字符串。 | - | :::warning `extra_fields` 对象中提交的键必须与模板中可用的 `field_key` 完全一致。无效的键会导致报错。 ::: ### **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** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | --------------------------------------- | --------- | | `operation_key` * | string | 操作的唯一键值（UUID v4）。 | 36 | | `document_type` * | string | 文档类型。 | **[document_type 枚举值](#document_type-枚举值)** | | `extra_fields` * | object | 包含已保存扩展字段及其相应取值的对象。 | - | --- ## **document_type 枚举值** | 枚举值 | 描述 | | -------------------- | ------------- | | `commercial_paper` | 设立条款 | | `adhesion_term` | 加入条款 | --- ## **错误** | 错误码 | HTTP | 描述 | | ---------- | ---- | --------------------------------------------------------------- | | `COM000007` | 404 | 未找到该操作。 | | `COM000008` | 403 | 该操作不属于发起请求的租户。 | | `COM000044` | 400 | 该文档类型尚未定义模板。请先生成草稿预览，再继续操作。 | | `COM000045` | 400 | 扩展字段的键在模板中不可用。 | --- # 客户接受日志上传 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite 此端点用于向一笔操作附加一份包含客户接受日志的 PDF — 即最终客户已接受该操作条件的证据记录。该端点服务于**自动签署**流程：当 QI Tech 使用在 CertifiQI 中放行的私有证书代发行人签署 Termo Constitutivo 时，不会为客户生成任何签署链接，客户的同意即由接受日志来记录。 :::info 上传为可选项 上传**不是必需的**，发行流程的任何环节都不依赖它。即使没有接受日志，操作也会正常进入审核、签署和发行 — 该文件仅作为附加在操作上的证据保存。 ::: :::warning 要求发行人已开通自动签署 只有当操作的发行人在发行人系统中的自动签署开通状态为 `enabled` 时，才会接受上传。未开通的发行人，或开通状态为其他任意值（`pending_term_generation`、`pending_signature`、`reproved`、`canceled`）的发行人，请求会以 `COM000077` 被拒绝，且不会存储任何内容。 此外，只有当操作处于 `in_filling` 状态时才接受上传；不在该状态时，请求会以 `COM000010` 被拒绝。 ::: --- ## **客户接受日志上传 (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /acceptance_log MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | | ----------------- | ------ | ------------------------- | ----------- | | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | Request Body ```json { "document_base64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..." } ``` ### **Request Body Params** 请求体不接受除下列字段以外的任何字段（`additionalProperties: false`） — 含有未知字段或缺少 `document_base64` 时返回 `QIT000001`。 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------ | --------------------------------------------------------------------- | ----------- | | `document_base64` * | string | 客户接受日志的 PDF，采用 base64 编码，不含 `data:` 前缀，不含换行符。 | — | ## **Response** STATUS 201 Response Body ```json { "document_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "created_at": "2026-09-10T14:30:00.000000+00:00" } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | | ----------------- | ------ | ------------------------------------- | | `document_key` * | string | 本次上传生成的文件唯一键（UUID v4）。 | | `operation_key` * | string | 该文件所附加操作的唯一键。 | | `created_at` * | string | 上传的日期与时间，UTC 时区。 | :::info 如何确认已附加的内容 该操作会在[按键值查询操作](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave)中开始返回 `acceptance_log_document_key` 字段，其取值来自最近一次上传。首次上传之前，该字段返回 `null`。 ::: :::warning 再次上传会替换此前的文件 对同一笔操作再次上传会生成新的 `document_key`，并成为当前生效的接受日志 — 此前的引用不再被该操作指向。不支持部分更新，也没有删除端点。 ::: --- ## **错误** 以下错误代码同样记录在[错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros)中。 | 错误代码 | HTTP | 描述 | | ----------- | ---- | -------------------------------------------------------- | | `QIT000001` | 400 | Schema 校验失败 — `document_base64` 缺失或请求体中含有未知字段。 | | `COM000010` | 400 | 操作不处于 `in_filling` 状态，无法更新。 | | `COM000077` | 400 | 该操作的发行人未开通自动签署。 | | `COM000007` | 404 | 未找到该操作。 | | `COM000008` | 403 | 该操作不属于发起请求的 tenant。 | --- # 取消操作 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/cancelar-operacao 此端点允许将操作状态更改为"已取消"，适用于客户不再继续完成操作的最终状态。 --- ## 取消操作 (PATCH) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。 | 36 | --- ### Request Body ```json { "operation_status": "canceled" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 必填 | |--------------------|----------|------------------------------------------------------------|-------------| | `operation_status` | string | 操作状态。必须设置为 `canceled`。 | 是 | --- ### Response 响应体为更新后的完整操作 JSON。 --- --- # 查询通过 QI SIGN 签署的操作合同链接 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign 此端点允许通过操作的唯一键查询特定操作中所有通过 QI SIGN 签署的文件。 --- :::warning 注意 已签署合同的链接有效期为 24 小时。之后需要通过再次调用该端点来更新链接。 ::: ## 查询操作的已签署链接 (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signed_url MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | 操作的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `envelope_key` | string | 信封的唯一键（UUID v4）。 | 36 | | `status` | string | 信封的状态。 | [operation-status 枚举](#enumeradores-operation-status) | | `documents` | list | 信封中的文件列表。 | - | ### document 对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_type` | string | 文件类型。 | [document type 枚举](#enumeradores-document-type) | | `signed_url` | string | 已签署合同的下载 URL。 | - | | `signers` | list | 签名人列表。 | - | ## **operation-status 枚举** | 枚举值 | 描述 | |--------------------------------|----------------------------------------------------------------| | `waiting_signature` | 等待相关方签名。 | | `signed` | 签名完成。 | | `signature_rejected` | 签名被拒绝。 | | `canceled` | 操作已取消。 | ## **document-type 枚举** | 枚举值 | 描述 | |----------------------------------|------------------------------------------------------------------| | `contract` | 合同标识符。 | | `ncom_pre_price` | 商业票据 Pre price。 | | `ncom_pre_price_days` | 商业票据 Pre price days。 | | `ncom_pre_sac` | 商业票据 Pre sac。 | | `ncom_post_sac_cdi` | 与 CDI 挂钩的 Pós sac 商业票据。 | | `ncom_post_sac_ipca` | 与 IPCA 挂钩的 Pós sac 商业票据。 | | `ncom_post_sac_igpm` | 与 IGP-M 挂钩的 Pós sac 商业票据。 | | `ncom_post_price_cdi` | 与 CDI 挂钩的 Pós price 商业票据。 | | `ncom_post_price_ipca` | 与 IPCA 挂钩的 Pós price 商业票据。 | | `ncom_post_price_igpm` | 与 IGP-M 挂钩的 Pós price 商业票据。 | | `ncom_post_price_days_cdi` | 与 CDI 挂钩的 Pós price days 商业票据。 | | `ncom_post_price_days_ipca` | 与 IPCA 挂钩的 Pós price days 商业票据。 | | `ncom_post_price_days_igpm` | 与 IGP-M 挂钩的 Pós price days 商业票据。 | | `subscription_note` | 认购公告。 | | `adhesion_term` | 加入条款。 | --- # 查询通过 QI SIGN 签署操作的链接 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign 此端点允许通过操作的唯一键查询特定操作中所有通过 QI SIGN 进行签名的链接。 --- ## 查询操作的签名链接 (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signers MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。 | 36 | ### Query Params | 字段 | 类型 | 描述 | 必填 | |------------------------|---------|-------------------------------------------------------------------------|----------| | `exclude_qi_signers` | boolean | 如果为 `true`，将从响应中隐藏 QI 的签名人。默认值：`false`。 | 否 | --- ### 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 | 字段 | 类型 | 描述 | 最大字符数 | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `envelope_key` | string | 信封的唯一键（UUID v4）。 | 36 | | `status` | string | 信封的状态。 | [operation-status 枚举](#enumeradores-operation-status) | | `documents` | list | 信封中的文件列表。 | - | ### document 对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_type` | string | 文件类型。 | [document type 枚举](#enumeradores-document-type) | | `signers` | list | 签名人列表。 | - | ### signer 对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_number` | string | 签名人的证件号码。 | 18 | | `signature_url` | string | 签名人的签名链接。 | - | | `status` | string | 签名人的状态。 | [status 枚举](#enumeradores-status) | | `name` | string | 签名人姓名。 | - | | `email` | string | 签名人电子邮件。 | - | ## **operation-status 枚举** | 枚举值 | 描述 | |--------------------------------|----------------------------------------------------------------| | `waiting_signature` | 等待相关方签名。 | | `signed` | 签名完成。 | | `signature_rejected` | 签名被拒绝。 | | `canceled` | 操作已取消。 | ## **status 枚举** | 枚举值 | 描述 | |--------------------------------|----------------------------------------------------------------| | `on_signature` | 等待相关方签名。 | | `analyzed` | 通过 API 完成签名。 | | `signed` | 签名完成。 | | `signature_rejected` | 签名被拒绝。 | | `canceled` | 操作已取消。 | | `created` | 签名已创建。 | | `submitted` | 已发送给签名人。 | | `sending_sign_receipt` | 正在发送简化签名档案。 | | `analyzing` | 签名人正在分析中。 | | `completed` | 签名完成。 | | `expired` | 签名已过期。 | | `removed` | 签名人已移除。 | | `failed_waiting_for_manual_fix` | 签名创建失败，需要 QI 人工处理。 | ## **document-type 枚举** | 枚举值 | 描述 | |----------------------------------|------------------------------------------------------------------| | `contract` | 合同标识符。 | | `ncom_pre_price` | 商业票据 Pre price。 | | `ncom_pre_price_days` | 商业票据 Pre price days。 | | `ncom_pre_sac` | 商业票据 Pre sac。 | | `ncom_post_sac_cdi` | 与 CDI 挂钩的 Pós sac 商业票据。 | | `ncom_post_sac_ipca` | 与 IPCA 挂钩的 Pós sac 商业票据。 | | `ncom_post_sac_igpm` | 与 IGP-M 挂钩的 Pós sac 商业票据。 | | `ncom_post_price_cdi` | 与 CDI 挂钩的 Pós price 商业票据。 | | `ncom_post_price_ipca` | 与 IPCA 挂钩的 Pós price 商业票据。 | | `ncom_post_price_igpm` | 与 IGP-M 挂钩的 Pós price 商业票据。 | | `ncom_post_price_days_cdi` | 与 CDI 挂钩的 Pós price days 商业票据。 | | `ncom_post_price_days_ipca` | 与 IPCA 挂钩的 Pós price days 商业票据。 | | `ncom_post_price_days_igpm` | 与 IGP-M 挂钩的 Pós price days 商业票据。 | | `subscription_note` | 认购公告。 | | `adhesion_term` | 加入条款。 | --- # Consulta dos Documentos da Operação URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao Estes endpoints devolvem, em base64, o termo constitutivo e o termo de adesão gerados para a operação. São eles que entregam o arquivo a ser assinado no fluxo de **assinatura externa**: o documento devolvido aqui é exatamente o que a QI Tech gerou na aprovação, e é sobre esses bytes que a assinatura precisa ser calculada. :::warning Atenção Os documentos só existem depois que a operação é aprovada na análise. Antes disso a consulta responde `404`. ::: --- ## Consulta do Termo Constitutivo (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /contract MÉTODO GET --- ## Consulta do Termo de Adesão (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /adhesion_term MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "document_base64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAo..." } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|--------------------------------------------|-----------------| | `document_base64` | string | Conteúdo do documento em base64. | - | --- ## Uso na assinatura externa Decodifique o `document_base64` e assine o arquivo resultante sem reprocessá-lo. A QI Tech compara o resumo SHA-256 do documento com o declarado dentro do `.p7s`, e reabrir o PDF em outra ferramenta para salvá-lo altera esse resumo. O envio da assinatura é feito pelo endpoint de **[envio de documentos assinados](/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados)**. --- # 通过键查询操作 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave 此端点允许使用操作的唯一键查询特定操作的完整详情。 --- ## 查询操作 (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | 操作的唯一键（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", "financial": {}, "tags": [], "investor_list": [], "related_party_list": [], "collateral_list": [], "metadata_list": [], "integralization_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "security_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ``` ### Response Body Params | 字段 | 类型 | 描述 | 最大字符数 | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `tenant_key` * | string | tenant 的唯一键（UUID v4）。 | 36 | | `operation_key` * | string | 操作的唯一键（UUID v4）。 | 36 | | `operation_type` * | string | 操作类型。`commercial_paper` | - | | `operation_status` * | string | 操作状态。 | [operation_status 枚举](#enumeradores-operation_status) | | `issuer_key` * | string | 发行人的唯一键（UUID v4）。 | 36 | | `issuer_name` * | string | 发行人名称。 | - | | `issuer_document_number` * | string | 发行人证件号码（CNPJ）。 | 18 | | `issuer_bank_account` * | object | 发行人的银行数据。 | [bank_account 对象](#objeto-bank_account) | | `issuer_onboarding_approved` * | boolean | 指示发行人的 onboarding 是否已获批准。 | - | | `issue_number` * | integer | 发行编号。 | - | | `issue_series` * | integer | 发行系列。 | - | | `contract_number` * | string | 合同编号。 | - | | `issue_date` * | string | 发行日期（ISO 8601 格式）。 | - | | `financial_base_date` * | string | 操作的财务基准日期（ISO 8601 格式）。 | - | | `commercial_paper_template_key` * | string | 商业票据模板的唯一键。 | 36 | | `commercial_paper_document_key` * | string | 商业票据文件的键。 | - | | `adhesion_term_template_key` * | string | 加入条款模板的唯一键。 | 36 | | `adhesion_term_document_key` * | string | 加入条款文件的键。 | - | | `investor_list` * | object | 投资人列表。 | [investor 对象](#objeto-investor) | ### bank_account 对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_type` * | string | 账户类型（例如：checking）。 | - | | `account_digit` * | string | 银行账户校验位。 | - | | `account_branch` * | string | 银行支行。 | - | | `account_number` * | string | 银行账户号码。 | - | | `financial_institution_ispb` * | string | 金融机构 ISPB 代码。 | - | | `financial_institution_code_number` * | string | 金融机构代码。 | - | ### financial 对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------------------------|----------|-----------------------------------------------------------------|-----------------------------------------------------------------| | `financial_base_date` * | string | 操作的财务基准日期（ISO 8601 格式）。 | - | | `issue_quantity` * | integer | 发行的总单位数量。 | - | | `unit_price` * | float | 每单位发行价格。 | - | | `issue_amount` * | float | 发行总金额。 | - | | `released_amount` * | float | 释放总金额。 | - | | `cet` * | float | 操作的有效总成本（%）。 | - | | `annual_cet` * | float | 年化有效总成本（%）。 | - | | `number_of_installments` * | integer | 操作的总期数。 | - | | `prefixed_interest_rate` * | object | 固定利率。 | [prefixed_interest_rate 对象](#objeto-prefixed_interest_rate) | | `fine_delay_rate` * | object | 滞纳金利率。 | [fine_delay_rate 对象](#objeto-fine_delay_rate) | | `contract_fine_rate` * | float | 合同罚款利率（%）。 | - | | `financial_index` | string | 参考金融指数（如适用）。 | - | | `post_fixed_interest_rate` | object | 浮动利率（如适用）。 | - | | `fees` * | array | 适用费用列表。 | [fees 对象](#objeto-fees) | | `installment_list` * | array | 期次列表。 | [installment 对象](#objeto-installment) | ### prefixed_interest_rate 对象 | 字段 | 类型 | 描述 | 最大字符数 | |-----------------------|--------|------------------------------------------------------------|-----------------| | `daily_rate` * | float | 日利率（%）。 | - | | `annual_rate` * | float | 年化利率（%）。 | - | | `monthly_rate` * | float | 月利率（%）。 | - | | `interest_base` * | string | 利率计算基础（`calendar_days_365`）。 | - | ## fine_delay_rate 对象 | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|--------|--------------------------------------------------|-----------------| | `monthly_rate` * | float | 月滞纳金利率（%）。 | - | | `interest_base` * | string | 利率计算基础（`calendar_days_365`）。 | - | ## fees 对象 | 字段 | 类型 | 描述 | 最大字符数 | |---------------|---------|------------------------------------------------|-----------------| | `type` * | string | 费用类型（`internal`、`external`）。 | - | | `amount` * | float | 适用费率百分比。 | - | | `fee_type` * | string | 费用类型。 | - | | `fee_amount` * | float | 费用绝对值。 | - | | `amount_type` * | string | 值类型（`percentage`、`fixed`）。 | - | ## installment 对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------------------------------|---------|----------------------------------------------------------|-----------------| | `installment_number` * | integer | 期次编号。 | - | | `workdays` * | integer | 至到期日的工作日数。 | - | | `calendar_days` * | integer | 至到期日的自然日数。 | - | | `principal_amortization_unit_price` * | float | 本金摊还单位值。 | - | | `principal_amortization_amount` * | float | 本金摊还总额。 | - | | `interest_amount` * | float | 该期利息总额。 | - | | `amount` * | float | 该期总金额。 | - | | `due_principal` * | float | 该期后待偿本金。 | - | | `due_interest` * | float | 该期后待偿利息。 | - | | `due_date` * | string | 该期到期日（ISO 8601 格式）。 | - | | `has_interest` * | boolean | 指示该期是否含利息计费。 | - | ## investor 对象 | 字段 | 类型 | 描述 | 最大字符数 | |--------------------------------|---------|----------------------------------------------------------------------|----------------------------------------------| | `investor_key` * | string | 投资人的唯一键（UUID v4）。 | 36 | | `investor_name` * | string | 投资人名称。 | - | | `investor_document_number` * | string | 投资人证件号码（CNPJ/CPF）。 | 18 | | `subscription_percentage` * | float | 投资人在操作中的参与比例。 | - | | `subscription_quantity` * | integer | 投资人认购的单位数量。 | - | | `investor_onboarding_approved` * | boolean | 指示投资人的 onboarding 是否已获批准。 | - | | `bank_account` * | object | 投资人的银行信息。 | [bank_account 对象](#objeto-bank_account) | ## **operation_status 枚举** | 枚举值 | 描述 | |--------------------------------|----------------------------------------------------------------| | `in_filling` | 操作处于填写阶段。 | | `in_analysis` | 操作正在分析中。 | | `waiting_onboarding_approval` | 等待发行人 onboarding 批准。 | | `pending_signature_submission` | 等待提交签名。 | | `waiting_signature` | 等待相关方签名。 | | `issued` | 操作已发行。 | | `finished` | 操作已完成。 | | `signature_rejected` | 签名被拒绝。 | | `onboarding_reproved` | 发行人 onboarding 未获批准。 | | `compliance_reproved` | 合规审查未通过。 | | `canceled` | 操作已取消。 | --- # 通过筛选条件查询操作 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros 此端点允许使用可选筛选条件查询**商业票据**操作。 --- ## **Request** ENDPOINT /commercial_paper/operation MÉTODO GET ### **Query Params** | 字段 | 类型 | 描述 | 必填 | |----------------------------|----------|-----------------------------------------------|-------------| | `issuer_document_number` | string | 发行人证件号码（CNPJ）。 | 否 | | `investor_document_number` | string | 投资人证件号码（CPF/CNPJ）。 | 否 | | `operation_status` | string | 操作状态。 | **[operation_status 枚举](#enumeradores-operation_status)** | 否 | | `metadata_key` | array | 元数据键。 | 否 | | `metadata_value` | array | 元数据值。 | 否 | --- ## **Response** STATUS 200 Response Body ```json { "data": [ { "tenant_key": "13edaf06-9810-4689-b00b-2367274d1a14", "operation_key": "34bc5da7-89df-467d-93af-ed25184ab72e", "operation_type": "commercial_paper", "operation_status": "in_filling", "backoffice_analysis_status": "waiting_submission_for_analysis", "issuer_key": "7fbe9f89-b9ca-4445-85ac-6098da86bb56", "issuer_name": "Global Networks", "issuer_document_number": "73364815000123", "issue_number": 1, "contract_number": "0000000004" }, { "tenant_key": "13edaf06-9810-4689-b00b-2367274d1a14", "operation_key": "f456ee66-5844-4ebc-b69d-365ce6df7138", "operation_type": "commercial_paper", "operation_status": "in_filling", "backoffice_analysis_status": "waiting_submission_for_analysis", "issuer_key": "7fbe9f89-b9ca-4445-85ac-6098da86bb56", "issuer_name": "Global Networks", "issuer_document_number": "73364815000123", "issue_number": 2, "contract_number": "0000000005" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 2 } } ``` --- ### **Response Body Params** #### **Data 对象** | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|-----------------------------------------------------------|-----------------| | `tenant_key` * | string | tenant 的唯一键（UUID v4）。 | 36 | | `operation_key` * | string | 操作的唯一键（UUID v4）。 | 36 | | `operation_type` * | string | 操作类型。始终为 `commercial_paper`。 | 50 | | `operation_status` * | string | 操作的当前状态。 | **[operation_status 枚举](#enumeradores-operation_status)** | 50 | | `backoffice_analysis_status` | string | 后台分析状态。 | 50 | | `issuer_key` * | string | 与操作关联的发行人唯一键（UUID v4）。 | 36 | | `issuer_name` * | string | 与操作关联的发行人名称。 | 255 | | `issuer_document_number` * | string | 发行人证件号码（CNPJ）。 | 14 | | `issue_number` * | integer | 与操作关联的发行编号。 | - | | `contract_number` * | string | 与操作关联的合同编号。 | 20 | #### **Pagination 对象** | 字段 | 类型 | 描述 | |-------------------|----------|----------------------------------------------------------| | `current_page` * | integer | 查询的当前页。 | | `next_page` | integer | 下一页（如存在）。 | | `rows_per_page` * | integer | 每页记录数。 | | `total_pages` * | integer | 可用总页数。 | | `total_rows` * | integer | 符合筛选条件的总记录数。 | --- ## **operation_status 枚举** | 枚举值 | 描述 | |--------------------------------|----------------------------------------------------------------| | `in_filling` | 操作处于填写阶段。 | | `in_analysis` | 操作正在分析中。 | | `waiting_onboarding_approval` | 等待发行人 onboarding 批准。 | | `pending_signature_submission` | 等待提交签名。 | | `waiting_signature` | 等待相关方签名。 | | `issued` | 操作已发行。 | | `finished` | 操作已完成。 | | `signature_rejected` | 签名被拒绝。 | | `onboarding_reproved` | 发行人 onboarding 未获批准。 | | `compliance_reproved` | 合规审查未通过。 | | `canceled` | 操作已取消。 | --- # 按发行人查询下一个发行编号 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao 本端点返回由 `issuer_key` 标识的发行人可用的下一个 `issue_number`（发行编号）。返回值同时考虑该发行人在**未取消**操作中已使用的最大编号，以及发行人配置中的内部编号控制值 — 始终返回两者中较大的一个。 如果该发行人尚不存在编号配置，系统会自动创建，`current_issue_number = 1`，并返回该值。 --- ## **Request** ENDPOINT /commercial_paper/issuer/ ISSUER-KEY /issue_number 方法 GET ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |----------------|--------------|----------------------------------------------------------|----------| | `ISSUER-KEY` * | string/uuid | 在 Issuer Management 中登记的发行人的唯一标识（UUID v4）。 | 36 | --- ## **Response** STATUS 200 Response Body ```json { "issue_number": 42 } ``` --- ### **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|-----------------------------------------------------------------------------------|----------| | `issue_number` * | integer | 为该发行人的新操作建议的下一个发行编号。对既无操作也无既有配置的发行人，从 `1` 开始。 | - | --- # 提交已签署的批准会议纪要 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao 此端点允许将 SA 或 COP 类型公司在外部签署的批准会议纪要提交至书写系统，提交的 base64 将由书写方进行分析和批准。 --- ## 提交已签署的操作 (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。 | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "sa_minute" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `contract_type` * | string | 已签署合同的类型。 | **[contract_type 枚举](#enumeradores-contract_type)** | | `contract_base64` * | string | base64 格式的已签署批准会议纪要。 | - | ### contract_type 枚举 {#enumeradores-contract_type} | 枚举值 | 描述 | |--------------------|--------------------------------------------| | `sa_minute` | **SA** 公司商业票据发行批准会议纪要。 | | `cop_minute` | **合作社** 公司商业票据发行批准会议纪要。 | ### Response 响应体为更新后的完整操作 JSON。 --- --- # 提交操作的已签署文件 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados 此端点用于接收 `signature_method` 为 **client_side** 的操作中形式化文件的签名。 发行方在自有认证机构签署文件，并且只向 QI Tech 提交签名文件（`p7s_base64`），不提交 PDF。 :::warning 警告 此端点仅应用于 `signature_method` 为 **client_side** 的操作。在 **QI Sign** 和 **CertifiQI** 流程中，合同由平台自行生成并签署。批准会议纪要请使用**[批准会议纪要提交端点](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao)**。 ::: --- ## 提交已签署文件 (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document 方法 POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------|--------|----------------------------------------------------------|--------| | `OPERATION-KEY` | string | 操作的唯一标识 (UUID v4)。 | 36 | --- ### Request Body 设立条款的签名 ```json { "contract_type": "commercial_paper", "p7s_base64": "MIIJugYJKoZIhvcNAQcCoIIJqzCCCacC..." } ``` 担保物的签名 ```json { "contract_type": "collateral", "collateral_key": "8f0b6f0a-1a2b-4c3d-9e8f-7a6b5c4d3e2f", "p7s_base64": "MIIJugYJKoZIhvcNAQcCoIIJqzCCCacC..." } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|--------|-------------------------------------------------------------------------------|------------| | `contract_type` * | string | 提交文件的类型。 | **[contract_type 枚举值](#contract_type-enumerators)** | | `p7s_base64` * | string | base64 编码的 CAdES 签名，分离式或附加式均可。 | - | | `collateral_key` | string | 签名所对应担保物的标识。当 `contract_type` 为 `collateral` 时必填。 | 36 | ### contract_type 枚举值 {#contract_type-enumerators} | 枚举值 | 描述 | |---------------------|---------------------------------------------| | `commercial_paper` | 商业票据的设立条款。 | | `adhesion_term` | 商业票据的加入条款。 | | `collateral` | 操作的担保物文件。需要 `collateral_key`。 | ### Response 响应体为更新后操作的完整 JSON。 --- ## 形式化文件的签署 操作在分析中获批后，可通过**[操作文件查询端点](/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao)**下载这些文件。 每个文件只接受一个 `.p7s`，并需单独发起请求提交。所有必需文件均被接受后，QI Tech 的签署人完成签署，操作即可发行。 :::danger 请严格签署下载到的文件 QI Tech 会将 `.p7s` 中声明的摘要（SHA-256）与获批时生成的文件摘要进行比对。在签署前重新处理 PDF 的工具，例如重新打开并保存或重新压缩，都会改变该摘要，签名将以 `COM000074` 被拒绝。 ::: ## **错误码** 以下错误码也记录在[错误目录](/documentation/escrituracao/catalogo-erros/catalogo-erros)中。 | 错误码 | HTTP | 描述 | |---------------|--------|------------------------------------------------------------| | `COM000072` | 400 | 形式化文件需要签名文件，但未提交 `p7s_base64`。 | | `COM000073` | 400 | 文件无法被解析为 CMS 结构，或超出允许的大小。 | | `COM000074` | 422 | 签名与 QI Tech 出具的文件不匹配。 | | `COM000075` | 409 | 该文件已有一个被接受的签名。 | --- # 将操作提交分析 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/envio-para-analise 此端点允许将操作状态更改为"分析中"，将其发送至书写方进行合规验证流程。 --- ## 将操作提交分析 (PATCH) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。 | 36 | --- ### Request Body ```json { "operation_status": "in_analysis" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 必填 | |--------------------|----------|------------------------------------------------------------|-------------| | `operation_status` | string | 操作状态。必须设置为 `in_analysis`。 | 是 | --- ### Response 响应体为更新后的完整操作 JSON。 --- --- # 将操作提交签名 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/envio-para-assinatura :::warning 警告 合规审查通过的操作会定期自动发送签名。此端点仅应在需要立即发送时使用。 ::: --- ## 将操作提交签名 (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /send_to_signature MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。 | 36 | --- ### Request Body 无需请求体。 --- ### Response 响应体为更新后的完整操作 JSON。 --- --- # 更改加入条款模板 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta 此端点允许为特定操作更改加入条款模板。 ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | --- Request Body ```json { "adhesion_term_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 必填 | |--------------------------------------|----------|--------------------------------------------------|-------------| | `adhesion_term_template_key` * | string | 要使用的新模板的唯一键（UUID v4）。 | 是 | ## Response 响应体为更新后的完整操作 JSON。 --- # 更改组成性条款模板 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc 此端点允许为特定操作更改组成性条款模板。 ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | --- Request Body ```json { "commercial_paper_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 必填 | |--------------------------------------|----------|--------------------------------------------------|-------------| | `commercial_paper_template_key` * | string | 要使用的新模板的唯一键（UUID v4）。 | 是 | ## Response 响应体为更新后的完整操作 JSON。 --- # 预览加入条款 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao 此端点允许使用预定义模板预览特定操作的加入条款草稿。 --- ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_adhesion_term MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | Request Body ```json { "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 必填 | |--------------------------------------|----------|--------------------------------------------------|-------------| | `template_key` * | string | 要使用的新模板的唯一键（UUID v4）。 | 是 | ## **Response** STATUS 201 Response Body ```json { "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "document_type": "adhesion_term", "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0" } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|------------------------------------------------|-----------------| | `operation_key` * | string | 操作的唯一键（UUID v4）。 | 36 | | `document_type` * | string | 生成的文件类型。始终为 `adhesion_term`。 | 50 | | `document_base64` * | string | Base64 编码的生成文件内容。 | - | --- # 预览组成性条款 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato 此端点允许使用预定义模板为特定操作生成组成性条款草稿。 --- ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_commercial_paper MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | Request Body ```json { "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 必填 | |--------------------------------------|----------|--------------------------------------------------|-------------| | `template_key` * | string | 要使用的新模板的唯一键（UUID v4）。 | 是 | ## **Response** STATUS 201 Response Body ```json { "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "document_type": "commercial_paper", "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0" } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|------------------------------------------------|-----------------| | `operation_key` * | string | 操作的唯一键（UUID v4）。 | 36 | | `document_type` * | string | 生成的文件类型。始终为 `commercial_paper`。 | 50 | | `document_base64` * | string | Base64 编码的生成文件内容。 | - | --- # 商业票据发行介绍 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/inicio 商业票据是企业直接从市场上筹集资金的金融工具。该流程涉及多个环节，从发行人和投资人的登记，到财务条件的确定，直至证券的正式发行。每个环节对于确保合规性和筹资流程效率至关重要。 --- ## 发行流程概览 商业票据的发行流程由多个环节构成，确保透明度、安全性和控制力。以下是流程的主要步骤： 1. **发行人和投资人登记** 希望发行商业票据的公司和有意购买这些证券的投资人需要在系统中进行登记。登记包括详细信息，如文件和银行账户。 2. **确定操作条件** 发行人确定操作的财务条件，包括利率、还款期数、发行和到期日期，以及任何费用和手续费。 3. **模拟** 在正式发行之前，进行模拟以计算发行金额、还款流程和其他财务细节。此环节允许根据发行人和投资人的需求调整操作条件。 4. **关联方和文件登记** 包括登记参与各方（如担保人和共同义务人），以及提交相关文件（如合同和条款）。 5. **文件生成和签署** 生成主要文件的草稿，如**加入条款**和**组成性条款**。批准后，文件被发送进行电子签名。 6. **提交分析和审批** 操作提交进行合规和后台分析，确保满足所有监管和合同要求。 7. **正式发行和登记** 审批通过后，商业票据正式发行并向投资人开放。 从接下来的页面开始，我们将详细探讨商业票据发行流程的每个环节，包括将您的系统集成到 API 的端点和实际示例。 --- # 财务条件模拟 URL: /zh-Hans/documentation/escrituracao/emissao-de-notas/simulacao 此端点允许模拟操作的财务条件和付款流程 --- :::warning 注意 **Request Body** 必须包含有效的参数组合才能被处理。接受的组合包括： - 发行金额/释放金额 + 利率 - 发行金额/释放金额 + 每期金额 - 每期金额 + 利率 - 发行金额/释放金额 + 利率 + 每期摊销百分比。 ::: ## Request ENDPOINT /commercial_paper/simulation MÉTODO POST ## 固定利率操作 发行金额 + 利率 ```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, } ``` 释放金额 + 利率 ```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" } ``` 每期金额 + 利率 ```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" } ] } ``` 发行金额 + 每期摊销百分比 + 利率 ```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" } ] } ``` 发行金额 + 每期金额 ```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" } ] } ``` ## 浮动利率操作 发行金额 + 利率 + 浮动利率 ```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" } ``` 释放金额 + 利率 + 浮动利率 ```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" } ``` 每期金额 + 利率 + 浮动利率 ```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" } ``` 发行金额 + 每期摊销百分比 + 利率 + 浮动利率 ```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" } ``` 发行金额 + 每期金额 + 浮动利率 ```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 | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_type` * | string | 应用的利率类型。 | **[interest_type 枚举](#enumeradores-interest_type)** | | `financial_base_date` * | string | 操作基准日期（格式 "YYYY-MM-DD"）。 | - | | `released_amount` | number | 操作中释放的总金额。 | - | | `issue_amount` | number | 操作的发行金额。 | - | | `number_of_installments` * | integer | 分期总数。 | - | | `installments` | array | 包含每期详情的对象。 | **[installments 对象](#objeto-installments)** | | `prefixed_interest_rate` * | object | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)** | | `fine_delay_rate` * | object | 包含违约罚款详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | 以百分比表示的合同罚款。 | - | | `fees` | array | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** | | `post_fixed_interest_rate` | number | 浮动利率的利率值。 | - | | `financial_index` | string | 浮动利率类型。 | **[financial_index 枚举](#enumeradores-financial_index)** | | `first_due_date` | date | 第一期日期。 | - | | `first_due_date_delay` | number | 第一期付款开始前的天数。 | - | ### installments 对象 | 字段 | 类型 | 描述 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------| | `due_date` * | string | 分期到期日（格式 "YYYY-MM-DD"）。 | | `amount` | number | 分期总金额。 | | `principal_amortization_percentage` | number | 本金的摊销百分比。 | ### prefixed_interest_rate 对象 | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | 利率计算基准。 | **[interest_base 枚举](#enumeradores-interest_base)** | | `daily_rate` | number | 适用的日利率。 | - | | `monthly_rate` | number | 适用的月利率。 | - | | `annual_rate` | number | 适用的年利率。 | - | ### fine_delay_rate 对象 | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | 罚款计算基准。 | **[interest_base 枚举](#enumeradores-interest_base)** | | `monthly_rate` * | number | 月罚款率。 | - | ### fees 对象 | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `amount` * | number | 适用的费用金额。 | - | | `amount_type` * | string | 费用金额类型。 | **[amount_type 枚举](#enumeradores-amount_type)** | | `fee_type` * | string | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** | | `type` * | string | 费用收取方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** | ### interest_type 枚举 | 枚举值 | 描述 | |--------------------|-----------------------------------------| | `pre_price` | Price 模型固定利率。 | | `pre_price_days` | 按日历天数计算的 Price 模型固定利率。 | | `pre_sac` | SAC 模型固定利率。 | | `post_sac` | SAC 模型浮动利率。 | | `post_price_days` | 按日历天数计算的 Price 模型浮动利率。 | ### financial_index 枚举 | 枚举值 | 描述 | |--------------------|-----------------------------------------| | `CDI` | CDI 浮动利率 | | `IPCA` | IPCA 浮动利率 | | `IGPM` | IGPM 浮动利率 | ### interest_base 枚举 | 枚举值 | 描述 | |--------------------|-----------------------------------------| | `calendar_days` | 日历天数基准。 | | `calendar_days_365`| 365 日历天数基准。 | | `workdays` | 工作日基准。 | ### amount_type 枚举 | 枚举值 | 描述 | |-------------|---------------------------| | `percentage` | 百分比金额。 | | `absolute` | 货币绝对金额。 | ### fee_type 枚举 | 枚举值 | 描述 | |-------------------------------------|-------------------------------------------| | `bookkeeping_fee` | 融资书写费。 | | `structuring_fee` | 融资结构费。 | ### fee_recipient 枚举 | 枚举值 | 描述 | |-----------|-------------------------------------------------------| | `internal` | 支付给书写方的费用。 | | `external` | 支付给发起人的返点。 | ## 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 | 字段 | 类型 | 描述 | 最大字符数 | |------------------------------|----------|---------------------------------------------------------------------------------------------------------|-----------------| | `financial_base_date` * | string | 操作的财务基准日期（格式 "YYYY-MM-DD"）。 | - | | `issue_amount` * | number | 操作发行的总金额。 | - | | `released_amount` * | number | 操作中释放的净金额。 | - | | `issue_quantity` * | integer | 发行的总单位数量。 | - | | `unit_price` * | number | 发行的单位价格。 | - | | `cet` * | number | 以百分比表示的总有效成本（CET）。 | - | | `annual_cet` * | number | 以百分比表示的年化 CET。 | - | | `number_of_installments` * | integer | 分期总数。 | - | | `prefixed_interest_rate` * | object | 包含固定利率详情的对象。 | **[prefixed_interest_rate 对象](#objeto-response-prefixed_interest_rate)** | | `fees` | array | 与操作相关的费用列表。 | **[fees 对象](#objeto-fees)** | | `installments` | array | 操作中生成的分期详情列表。 | **[installments 对象](#objeto-response-installments)** | | `fine_delay_rate` * | object | 包含违约罚款详情的对象。 | **[fine_delay_rate 对象](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | 以百分比表示的合同罚款。 | - | ### Response prefixed_interest_rate 对象 | 字段 | 类型 | 描述 | 最大字符数 | |---------------|----------|------------------------------------------------------------|-----------------| | `interest_base` * | string | 利率计算基准。 | **[interest_base 枚举](#enumeradores-interest_base)** | | `monthly_rate` * | number | 适用的月利率。 | - | | `daily_rate` * | number | 适用的日利率。 | - | | `annual_rate` * | number | 适用的年利率。 | - | ### fees 对象 | 字段 | 类型 | 描述 | 最大字符数 | |------------|--------|------------------------------------------------------------|-----------------| | `amount` * | number | 费用的百分比金额。 | - | | `fee_amount` * | number | 费用对应的货币金额。 | - | | `amount_type` * | string | 费用金额类型。 | **[amount_type 枚举](#enumeradores-amount_type)** | | `fee_type` * | string | 费用类型。 | **[fee_type 枚举](#enumeradores-fee_type)** | | `type` * | string | 费用收取方。 | **[fee_recipient 枚举](#enumeradores-fee_recipient)** | ### Response installments 对象 | 字段 | 类型 | 描述 | |----------------------------|----------|--------------------------------------------------------| | `installment_number` * | integer | 分期编号。 | | `workdays` * | integer | 到分期到期的工作日数。 | | `calendar_days` * | integer | 到分期到期的日历天数。 | | `principal_amortization_amount` * | number | 本金摊销金额。 | | `principal_amortization_unit_price` * | number | 每单位摊销金额。 | | `interest_amount` * | number | 分期应用的利息金额。 | | `amount` * | number | 分期总金额。 | | `due_date` * | string | 分期到期日（格式 "YYYY-MM-DD"）。 | --- # 登记债券操作 URL: /zh-Hans/documentation/escrituracao/emissao-debentures/cadastro-operacao 此端点通过单个请求创建完整的债券操作。 :::info `financial` 对象为 **必填**，且必须以已计算好的形式提交，因为此端点不执行财务模拟。发行人及其银行账户必须事先登记。 ::: --- ## **Request** ENDPOINT /debenture/create_operation MÉTODO POST 请求体既可以是仅含 **必填字段的负载**（包含财务对象），也可以是同时包含关联方的 **完整负载**。两种变体见下文。 必填字段负载 ```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 } ] } } ``` 完整负载（含关联方） ```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** | 字段 | 类型 | 描述 | 最大字符数 | | ------------------- | ------- | ------------------------------------------ | -------------------------- | | `tenant_key` * | string | tenant 的唯一键。 | - | | `issuer_key` * | string | 发行人的唯一键（须事先登记）。 | - | | `issue_number` * | integer | 发行编号。 | - | | `issue_series` * | integer | 发行系列。 | - | | `issue_date` * | string | 操作发行日期（格式："YYYY-MM-DD"）。 | - | | `signature_method` | string | 操作中使用的签名方式。可选；省略时默认为 `certifiqi`。 | **[signature_method 枚举](#signature_method-枚举)** | | `investors` * | array | 相关投资人列表。 | **investors 对象** | | `financial` * | object | 操作的已计算财务数据。 | **financial 对象** | | `contract_number` | string | 合同编号。 | - | | `related_party_list` | array | 操作的关联方（担保人、债务人等）。 | **related_party 对象** | ### investors 对象 | 字段 | 类型 | 描述 | | --------------------------- | ------ | ------------------------------------------ | | `investor_key` * | string | 投资人的唯一键（须事先登记）。 | | `bank_account` * | object | 投资人的银行账户（**bank_account 对象**）。 | | `subscription_percentage` | number | 认购比例。 | | `subscription_quantity` | number | 认购数量。 | ### bank_account 对象 | 字段 | 类型 | 描述 | | ------------------------------------- | ------ | ----------------------------------------------- | | `account_number` * | string | 银行账户号码。 | | `account_digit` * | string | 银行账户校验位。 | | `account_branch` * | string | 银行账户支行。 | | `financial_institution_code_number` | string | 金融机构代码。 | | `financial_institution_ispb` * | string | 金融机构 ISPB 代码。 | | `account_type` * | string | 账户类型（`checking`、`savings`、`salary`、`payment`）。 | ### financial 对象 | 字段 | 类型 | 描述 | | --------------------------- | ------- | ------------------------------------------ | | `financial_base_date` * | string | 财务基准日期（格式："YYYY-MM-DD"）。 | | `interest_type` * | string | 利率类型。 | | `issue_amount` | number | 发行总金额。 | | `issue_quantity` | integer | 发行单位数量。 | | `unit_price` | number | 每单位发行价格。 | | `released_amount` | number | 释放的净金额。 | | `cet` / `annual_cet` | number | 有效总成本（月度与年度），百分比。 | | `number_of_installments` * | integer | 期数。 | | `prefixed_interest_rate` * | object | 固定利率。 | | `fine_delay_rate` | object | 滞纳金利率。 | | `contract_fine_rate` | number | 合同罚款百分比。 | | `fees` | array | 费用列表。 | | `installments` | array | 已计算的期次列表。 | ### related_party 对象 `related_party_list` 中的每一项代表参与该操作的一方。 | 字段 | 类型 | 描述 | | ----------------- | ------- | ----------------------------------------------- | | `person_type` * | string | 人员类型（`natural` 自然人，`legal` 法人）。 | | `name` * | string | 关联方名称。 | | `document_number` * | string | CPF（自然人）或 CNPJ（法人）。 | | `role_type` * | string | 关联方在操作中的角色。**[role_type 枚举](#role_type-枚举)** | | `street` * | string | 街道。 | | `number` * | string | 门牌号。 | | `neighborhood` | string | 街区。 | | `postal_code` * | string | 邮政编码（格式："00000-000"）。 | | `city` * | string | 城市。 | | `state` * | string | 州/省（2 个字母）。 | | `complement` | string | 地址补充信息。 | | `is_pep` | boolean | （自然人）是否为政治公众人物。 | | `marital_status` | string | （自然人）婚姻状况。 | | `property_system` | string | （自然人）财产制度。 | | `birthdate` | string | （自然人）出生日期。 | | `mother_name` | string | （自然人）母亲姓名。 | | `occupation` | string | （自然人）职业。 | | `trading_name` | string | （法人）商号。 | | `cnae_code` | string | （法人）CNAE 代码（格式："00.00-0-00"）。 | | `company_type` | string | （法人）公司类型。 | | `foundation_date` | string | （法人）成立日期。 | :::warning 注意 必填字段因 `person_type` 而异： - **自然人（`natural`）**：除通用字段外，`is_pep` 为必填。 - **法人（`legal`）**：除通用字段外，`trading_name`、`cnae_code`、`company_type` 和 `foundation_date` 为必填。 ::: ### role_type 枚举 | 枚举值 | 描述 | |--------|------| | `issuer` | 发行人。 | | `investor` | 投资人。 | | `cosigner` | 共同债务人。 | | `fiduciary_debtor` | 信托债务人。 | | `solidary_debtor` | 连带债务人。 | | `guarantor` | 担保人。 | | `bonafide_depositary` | 善意保管人。 | | `intervening_guarantor` | 介入担保人。 | | `intervening_consentor` | 介入同意人。 | | `intervening_discharger` | 介入清偿人。 | | `assignor` | 转让人。 | | `endorser` | 背书人。 | | `consulting` | 咨询方。 | | `fund_administrator` | 基金管理人。 | | `fund_representative` | 基金代表。 | | `company_representative` | 公司代表。 | | `attestant` | 见证人。 | | `debtor` | 债务人。 | | `bestowal` | 授予人。 | | `manager` | 管理人。 | :::tip 担保和基础资产在操作创建后通过 **单独的端点** 提交。请参阅本节的 **提交担保** 页面。 ::: ### signature_method 枚举 | 枚举值 | 描述 | |--------|------| | `certifiqi` | 默认值。操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。 | | `qi_sign` | 操作将发送至签名服务；创建签名信封，客户端将收到签名 URL（`signature_url`）。此外还支持查询操作的签署人。 | ## **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": { ... } } ``` 响应返回所创建操作的完整 JSON，包括 `operation_key`、投资人与关联方列表，以及已计算的财务对象。 --- # 提交文件 URL: /zh-Hans/documentation/escrituracao/emissao-debentures/envio-documento 此端点用于 **上传文件** 并返回标识该文件的 `document_key`。该 `document_key` 用于在其他端点中引用文件——例如 [提交担保](./envio-garantia.md) 中的 `collateral_document_key` 和 `additional_documents`。 --- ## **Request** ENDPOINT /debenture/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | 字段 | 类型 | 描述 | 必需 | |-------------------|--------|----------------------------|------| | `document_base64` * | string | base64 编码的文件内容。 | 是 | | `document_name` | string | 文件名称。 | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | 最大字符数 | |----------------|--------|-------------------------------|------------| | `document_key` * | string | 所上传文件的唯一键（UUID v4）。 | 36 | --- --- # 提交操作的外部文件 URL: /zh-Hans/documentation/escrituracao/emissao-debentures/envio-documento-externo 此端点允许将在外部签署的文件提交至书写系统，提交的 base64 将由书写方进行分析和批准。 :::warning 警告 此端点仅应用于使用 **client_side** 签名类型的操作，或用于提交 SA 或合作社类型公司的批准会议纪要。对于通过 QI Sign 或 Certifiqi 的流程，合同以正常方式生成。 ::: --- ## 提交已签署文件 (POST) ### Request ENDPOINT /debenture/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------|--------|-------------------------------|--------| | `OPERATION-KEY` | string | 操作的唯一键（UUID v4）。 | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "debenture" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|--------|--------------------|------------------------------------------------------------| | `contract_type` * | string | 已签署文件的类型。 | **[contract_type 枚举](#contract_type-枚举)** | | `contract_base64` * | string | base64 格式的已签署文件。 | - | ### contract_type 枚举 | 枚举值 | 描述 | |---------------------|--------------------------------------------| | `debenture` | 债券发行契约。 | | `adhesion_term` | 债券 加入条款。 | | `sa_minute` | **SA** 公司债券发行批准会议纪要。 | | `ltda_minute` | **LTDA** 公司债券发行批准会议纪要。 | | `cop_minute` | **合作社** 债券发行批准会议纪要。 | ### Response 响应体为更新后的完整操作 JSON。 --- --- # 提交操作担保 URL: /zh-Hans/documentation/escrituracao/emissao-debentures/envio-garantia 此端点允许为债券操作 **添加担保（collateral）**。担保将与操作文件一起提交签署。每种担保类型（`collateral_type`）都有各自的必需文件规则，见下文。 :::info `document_key` 的来源 `collateral_document_key` 和（`additional_documents` 中的）`document_key` 引用先前已上传的文件。每个键都通过 [提交文件](./envio-documento.md) 端点（`POST /debenture/upload`）获取，该端点接收 Base64 文件并返回对应的 `document_key`。 ::: --- ## **Request** ENDPOINT /debenture/operation/ OPERATION-KEY /collateral MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------|------|------|--------| | `OPERATION-KEY` * | string | 操作的唯一键（UUID v4）。 | 36 | --- ## 担保类型 :::warning 标记为 **必需** 的文件是相应担保类型所要求的。 ::: ### 不动产信托让与 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `property_appraisal_report` | 不动产评估报告。 | 是 | | `property_registration_updated` | 更新的不动产登记。 | 是 | | `property_full_content_certificate` | 不动产登记全文证明。 | 是 | | `property_insurance_policy` | 保险单（如合同要求）。 | - | | `others` | 其他文件。 | - | ### 车辆信托让与 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `vehicle_appraisal_report` | 车辆评估报告或 FIPE 表。 | 是 | | `vehicle_inspection_report` | 检验报告。 | 是 | | `vehicle_crv_certificate` | 更新的车辆登记证（CRLV）。 | 是 | | `others` | 其他文件。 | - | ### 航空器信托让与 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `aircraft_certificate_anac` | 注册证书（ANAC）。 | 是 | | `aircraft_rab_consult` | 巴西航空登记（RAB）查询。 | 是 | | `aircraft_insurance_policy` | 保险单（基金为受益人）。 | 是 | | `aircraft_appraisal_report` | 航空器评估报告。 | 是 | | `others` | 其他文件。 | - | ### 设备/产品/库存信托让与 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `equipment_purchase_invoice` | 采购发票。 | 是 | | `equipment_appraisal_report` | 设备评估报告。 | 是 | | `equipment_insurance_policy` | 设备保险单（如适用）。 | - | | `fiduciary_depositary_declaration` | 善意保管人声明。 | - | | `others` | 其他文件。 | - | ### 艺术品信托让与 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `artwork_appraisal_report` | 艺术品评估报告。 | 是 | | `artwork_storage_certificate` | 存放地点合规证明。 | 是 | | `artwork_insurance_policy` | 保险单（如适用）。 | - | | `others` | 其他文件。 | - | ### 证券信托让与 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `securities_negotiation_block` | 在托管人处的交易冻结。 | 是 | | `securities_registration_gravame` | 留置权登记。 | - | | `others` | 其他文件。 | - | ### 股份/股权信托让与 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `share_registration_book` | 记名股份登记簿（含留置权批注）。 | 是 | | `others` | 其他文件。 | - | ### 不动产抵押 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `property_appraisal_report` | 不动产评估报告。 | 是 | | `property_registration` | 更新的产权登记。 | 是 | | `property_full_content_certificate` | 不动产登记全文证明。 | 是 | | `property_insurance_policy` | 保险单（如合同要求）。 | - | | `others` | 其他文件。 | - | ### 船舶抵押 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `ship_registration` | 更新的船舶产权登记。 | 是 | | `ship_appraisal_report` | 船舶评估报告。 | 是 | | `ship_insurance_policy` | 船舶保险单（如适用）。 | - | | `others` | 其他文件。 | - | ### 票据保证（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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `guarantor_civil_status_declaration` | 担保人婚姻状况声明。 | 是 | | `guarantor_personal_document` | 担保人身份证件。 | - | | `guarantor_income_tax_declaration` | 担保人所得税申报。 | - | | `others` | 其他文件。 | - | ### 保证（保证人） (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `surety_civil_status_declaration` | 保证人婚姻状况声明。 | 是 | | `surety_personal_document` | 保证人身份证件。 | 是 | | `surety_income_tax_declaration` | 保证人所得税申报。 | 是 | | `others` | 其他文件。 | - | ### 保险 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `insurance_policy_endorsed` | 已背书保险单。 | 是 | | `insurance_policy_with_expiration_and_renewal` | 含有效期与续保的保险单。 | 是 | | `others` | 其他文件。 | - | ### 担保监控 (`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" } ] } ``` #### 文件类型 | 枚举值 | 描述 | 必需 | |--------|------|------| | `guarantee_contract` | 担保合同。 | 是 | | `guarantee_agent_contract` | 担保代理合同。 | 是 | | `others` | 其他文件。 | - | --- ## Request Body Params | 字段 | 类型 | 描述 | 必需 | |------|------|------|------| | `collateral_document_key` * | string | 担保工具文件的键。 | 是 | | `collateral_type` * | string | 担保类型。 | **[collateral_type 枚举](#collateral_type-枚举)** | | `additional_documents` | array | 担保的附加文件。 | - | ### additional_documents | 字段 | 类型 | 描述 | 必需 | |------|------|------|------| | `document_key` * | string | 文件键。 | 是 | | `document_type` * | string | 文件类型。 | 是 | ### collateral_type 枚举 | 枚举值 | 描述 | |--------|------| | `fiduciary_alienation_property` | 不动产信托让与. | | `fiduciary_alienation_vehicle` | 车辆信托让与. | | `fiduciary_alienation_aircraft` | 航空器信托让与. | | `fiduciary_alienation_equipment` | 设备/产品/库存信托让与. | | `fiduciary_alienation_artwork` | 艺术品信托让与. | | `fiduciary_alienation_securities` | 证券信托让与. | | `fiduciary_assignment_shares` | 股份/股权信托让与. | | `mortgage_property` | 不动产抵押. | | `mortgage_ship` | 船舶抵押. | | `guarantor` | 票据保证（Aval）. | | `surety` | 保证（保证人）. | | `insurance` | 保险. | | `monitoring_guarantee` | 担保监控. | | `bank_surety` | 银行保函。 | | `fiduciary_assignment_credit_rights` | 债权信托转让。 | | `card_receivables` | 卡应收款。 | | `stock_guarantee` | 库存担保。 | | `others` | 其他担保。 | ## Response 响应体为更新后的完整操作 JSON，新担保位于 `collateral_list` 中。 --- --- # 更新发行人登记 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/ 要对发行人登记进行修改，需要将其状态设置为"in_filling"，这将重新启用所有添加/删除端点。 完成修改后，必须再次将登记提交分析，状态为"in_analysis"。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY MÉTODO PATCH ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | ### Request Body Request Body ```json { "issuer_status": "in_filling" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 必填 | | ------------------ | ------ | ---------------------------------------------------- | ------------ | | `issuer_status`* | string | 发行人的新状态。接受值：`in_filling`。 | 是 | ## Response 响应为发行人更新后的完整 JSON。 --- # Consulta da Auto-assinatura URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura Este endpoint permite consultar a auto-assinatura ativa de um emissor — status atual, dados do termo de adesão e histórico de eventos. Os links de assinatura de cada assinante ficam em um endpoint próprio: [consulta dos links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura). Consulte o [fluxo da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) para entender como a habilitação é criada e quais são os status possíveis. --- ## Consulta da Auto-assinatura (GET) ### Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|-----------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | --- ### Response STATUS 200 Response Body — aguardando assinatura do termo ```json { "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "pending_signature", "signed_at": null, "enabled_at": null, "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "created_at": "2026-02-10T09:15:44", "event_list": [ { "event_type": "auto_signature_creation", "status": "pending_term_generation", "event_data": { "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154" }, "created_at": "2026-02-10T09:15:44" }, { "event_type": "adhesion_term_generation", "status": "pending_term_generation", "event_data": { "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "template_key": "b71f1a2c-9e44-4c1d-8f3a-6d2c0b5e7a19" }, "created_at": "2026-02-10T09:16:02" }, { "event_type": "envelope_creation", "status": "pending_signature", "event_data": { "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34" }, "created_at": "2026-02-10T09:16:03" } ] } ``` Response Body — termo assinado (habilitado) ```json { "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "enabled", "signed_at": "2026-02-11T14:02:31", "enabled_at": "2026-02-11T14:02:31", "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "created_at": "2026-02-10T09:15:44", "event_list": [ { "event_type": "signature_webhook_received", "status": "pending_signature", "event_data": { "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "envelope_status": "signed" }, "created_at": "2026-02-11T14:02:31" }, { "event_type": "auto_signature_status_change", "status": "enabled", "event_data": { "status": "enabled" }, "created_at": "2026-02-11T14:02:31" } ] } ``` --- ### Response Body Params | Campo | Tipo | Descrição | |-----------------------------|--------|--------------------------------------------------------------------------------------------------------------| | `issuer_auto_signature_key` | string | Chave única da auto-assinatura. | | `status` | string | Status atual: `pending_term_generation`, `pending_signature`, `enabled`, `reproved` ou `canceled`. | | `signed_at` | string | Data e hora da assinatura do termo. `null` enquanto o termo não é assinado. | | `enabled_at` | string | Data e hora da habilitação. `null` enquanto o status não é `enabled`. | | `issuer_key` | string | Chave única do emissor. | | `term_document_key` | string | Caminho do documento do termo de adesão gerado. | | `envelope_key` | string | Chave única do envelope de assinatura do termo. | | `created_at` | string | Data e hora de criação da auto-assinatura. | | `event_list` | array | Histórico de eventos da auto-assinatura, em ordem cronológica. | **Campos de `event_list`:** | Campo | Tipo | Descrição | |--------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `event_type` | string | Tipo do evento: `auto_signature_creation`, `adhesion_term_generation`, `adhesion_term_generation_failure`, `envelope_creation`, `envelope_creation_failure`, `signature_webhook_received` ou `auto_signature_status_change`. | | `status` | string | Status da auto-assinatura no momento do evento. | | `event_data` | object | Dados do evento. O conteúdo varia conforme o `event_type`. | | `created_at` | string | Data e hora do evento. | --- ### Erros | HTTP | Código | Quando ocorre | |------|---------------------------------------|-----------------------------------------------------------------------------------------------------| | 403 | `ISS000011` (`TenantForbidden`) | O cliente não possui acesso completo ao cadastro do emissor informado. | | 404 | `ISS000009` (`IssuerNotFound`) | Não existe emissor para a chave informada. | | 404 | `ISS0000028` (`AutoSignatureNotFound`)| O emissor não possui auto-assinatura ativa. | :::info Auto-assinaturas encerradas A consulta retorna apenas a auto-assinatura **ativa** — aquela em `pending_term_generation`, `pending_signature` ou `enabled`. Depois que uma auto-assinatura vai para `reproved` ou `canceled`, este endpoint responde `ISS0000028` até que uma nova habilitação seja criada. O último estado conhecido continua visível no campo `auto_signature` da [consulta do emissor](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave). ::: --- # Consulta dos Links de Assinatura do Termo de Adesão URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura Este endpoint retorna **um link de assinatura por assinante** do termo de adesão da auto-assinatura, com o status individual de cada um. Cada assinante do emissor assina pelo seu próprio link. Os links ficam disponíveis assim que a [solicitação da habilitação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) responde — é ela que abre o envelope e leva a auto-assinatura a `pending_signature`. Se a geração do termo tiver falhado, a auto-assinatura fica em `pending_term_generation`, sem envelope, e este endpoint responde `ISS0000030` até que a solicitação seja repetida. --- ## Consulta dos Links de Assinatura (GET) ### Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature/signers MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------ | ------ | --------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Query Params | Campo | Tipo | Descrição | Obrigatório | | -------------------- | ------- | ------------------------------------------------------------------------------ | ----------- | | `exclude_qi_signers` | boolean | Se `true`, oculta da resposta os assinantes que são da QI. Padrão: `false`. | Não | --- ### Response STATUS 200 Response Body ```json { "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "pending_signature", "documents": [ { "document_type": "adhesion_auto_signature_term", "signers": [ { "document_number": "123.456.789-01", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Joao da Silva", "email": "joao.silva@example.com", "status": "on_signature" }, { "document_number": "987.654.321-00", "signature_url": "https://sign.qitech.com.br/s/f7Kd91P", "name": "Maria de Souza", "email": "maria.souza@example.com", "status": "signed" }, { "document_number": "421.820.518-30", "signature_url": "https://sign.qitech.com.br/s/q1W2e3R", "name": "Assinante QI CTVM", "email": "assinaturas.estruturadas@qitech.com.br", "status": "on_signature" } ] } ], "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34" } ``` --- ### Response Body Params | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------------------- | | `envelope_key` | string | Chave única do envelope de assinatura do termo de adesão. | | `status` | string | Status do envelope no QI SIGN. | | `documents` | array | Documentos do envelope. O termo de adesão é o único documento. | | `issuer_key` | string | Chave única do emissor. | | `issuer_auto_signature_key` | string | Chave única da auto-assinatura. | **Campos de `documents`:** | Campo | Tipo | Descrição | | --------------- | ------ | ------------------------------------------------------------ | | `document_type` | string | Sempre `adhesion_auto_signature_term`. | | `signers` | array | Assinantes do documento, um item por assinante. | **Campos de `signers`:** | Campo | Tipo | Descrição | | ----------------- | ------ | ------------------------------------------------------------------------------ | | `document_number` | string | CPF do assinante. | | `signature_url` | string | Link individual de assinatura desse assinante. | | `name` | string | Nome do assinante. | | `email` | string | E-mail do assinante. | | `status` | string | Status individual da assinatura — por exemplo `on_signature` ou `signed`. | --- ### Erros | HTTP | Código | Quando ocorre | | ---- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | 400 | `ISS0000030` (`AutoSignatureInWrongStatus`) | O termo de adesão ainda não foi enviado para assinatura — a auto-assinatura está em `pending_term_generation`. | | 403 | `ISS000011` (`TenantForbidden`) | O cliente não possui acesso completo ao cadastro do emissor informado. | | 404 | `ISS000009` (`IssuerNotFound`) | Não existe emissor para a chave informada. | | 404 | `ISS0000028` (`AutoSignatureNotFound`) | O emissor não possui auto-assinatura ativa. | --- # Auto-assinatura do Emissor URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio A auto-assinatura permite que a QI Tech assine automaticamente, em nome do emissor, os documentos das emissões seguintes — sem que um representante precise assinar operação por operação. Para isso, o emissor assina **uma única vez** um **termo de adesão à auto-assinatura**. Enquanto esse termo não estiver assinado, as emissões continuam seguindo o fluxo normal de assinatura manual. :::info Habilitação por cliente A auto-assinatura não vem habilitada por padrão. Ela é configurada pela QI Tech por cliente (`tenant`), incluindo o template do termo de adesão utilizado. Para habilitar, entre em contato com o time [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br). ::: --- ## Pré-requisitos | Pré-requisito | Como é atendido | |---------------|-----------------| | Cliente habilitado para auto-assinatura | Configurado pela QI Tech, com o template do termo de adesão | | Emissor com cadastro **aprovado** | Fluxo normal de [homologação do emissor](/documentation/escrituracao/homologacao-emissor/inicio) | | Emissor com **grupo de assinantes** ativo | [Cadastro de assinantes do emissor](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) | O grupo de assinantes cadastrado no emissor é exatamente quem assina o termo de adesão. Se ele estiver vazio ou desatualizado no momento da aprovação, corrija o cadastro antes de prosseguir. --- ## Fluxo ponta a ponta A habilitação é **solicitada pelo integrador**, e só é aceita depois que o cadastro do emissor está aprovado. Não há criação automática: enquanto a solicitação não for feita, o emissor não tem auto-assinatura. 1. **Emissor aprovado.** O cadastro passa pelo fluxo normal de homologação até o status `approved`. Nada é criado nesse momento. 2. **Solicitação da habilitação.** O integrador chama [`POST /issuer_management/issuer/{issuer_key}/auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura). Na mesma chamada, a QI Tech cria a auto-assinatura, gera o termo de adesão a partir do template configurado para o cliente e abre o envelope de assinatura — independente de qualquer operação. A resposta já vem no status `pending_signature`, com `issuer_auto_signature_key` e `envelope_key`. 3. **Assinatura do termo.** O integrador consulta os [links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) e direciona **cada assinante do emissor ao seu próprio link**. O termo é assinado fora de qualquer operação, e pode ser assinado antes da primeira emissão. 4. **Termo assinado.** Quando todas as assinaturas necessárias são concluídas, a auto-assinatura passa para `enabled` e os campos `signed_at` e `enabled_at` são preenchidos. A QI Tech emite então o certificado privado do emissor, utilizado para assinar os documentos das emissões. 5. **Recusa ou expiração.** Se o envelope for recusado, cancelado ou expirado, a auto-assinatura vai para `reproved` e as emissões seguem pelo fluxo de assinatura manual. Uma nova habilitação precisa ser solicitada. Os passos 2, 4 e 5 disparam o webhook [`issuer_management.auto_signature_status_change`](/documentation/escrituracao/webhooks-escrituracao) — ou seja, os status `pending_signature`, `enabled` e `reproved`. O cancelamento (`canceled`) não gera webhook e é observado por consulta. Como o `pending_signature` já vem na resposta da solicitação, o webhook desse status é redundante para quem chamou o endpoint — ele é útil para outros consumidores do mesmo tenant. :::caution Não assuma a auto-assinatura ativa A solicitação abre o envelope, mas não conclui a habilitação: o termo ainda precisa ser assinado. Só considere a assinatura automática disponível para uma emissão depois que a auto-assinatura estiver em `enabled`. Em qualquer outro status, o documento segue para assinatura manual — a integração precisa tratar os dois caminhos. ::: --- ## Máquina de status | Status | Significado | Assinatura de uma nova emissão | |--------|-------------|--------------------------------| | `pending_term_generation` | Estado transitório durante a solicitação | Manual | | `pending_signature` | Termo gerado e enviado para assinatura; links dos assinantes disponíveis | Manual | | `enabled` | Termo assinado; emissor habilitado à assinatura automática | **Automática** | | `reproved` | Envelope do termo recusado, cancelado ou expirado | Manual | | `canceled` | Auto-assinatura cancelada | Manual | **Transições possíveis:** - `pending_term_generation` → `pending_signature` (ambos dentro da solicitação) → `enabled` - `pending_signature` → `reproved` (envelope recusado, cancelado ou expirado) - `pending_term_generation` ou `pending_signature` → `canceled` A auto-assinatura é cancelada automaticamente quando o emissor deixa o status `approved` — ou seja, quando passa para `reproved`, `expired` ou `canceled`. Nesse caso, a habilitação precisa ser refeita após a nova aprovação do cadastro. --- ## Endpoints | Endpoint | Para quê | |---|---| | [`POST .../auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) | Solicitar a habilitação para um emissor aprovado | | [`GET .../auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) | Consultar o estado atual e o histórico de eventos | | [`GET .../auto_signature/signers`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) | Obter o link de assinatura de cada assinante do termo | ## Como acompanhar Há dois caminhos, complementares: - **Webhook** — [`issuer_management.auto_signature_status_change`](/documentation/escrituracao/webhooks-escrituracao) é enviado nos status `pending_signature`, `enabled` e `reproved`. Ao receber `pending_signature`, consulte os links de assinatura. - **Consulta** — [consulta da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) retorna o estado atual e o histórico completo de eventos. O bloco resumido também aparece na [consulta do emissor](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave), no campo `auto_signature`: ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "status": "approved", "auto_signature": { "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "enabled", "signed_at": "2026-02-11T14:02:31", "enabled_at": "2026-02-11T14:02:31" } } ``` O campo é `null` para emissores que nunca tiveram uma auto-assinatura solicitada. --- # Solicitação da Auto-assinatura URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura Este endpoint solicita a habilitação da auto-assinatura para um emissor **aprovado**. Na mesma chamada, a QI Tech gera o termo de adesão e abre o envelope de assinatura, de modo que a resposta já volta com a habilitação pronta para ser assinada. Consulte o [fluxo da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) para o encadeamento completo. :::info Emissor aprovado A solicitação só é aceita quando o cadastro do emissor está no status `approved` e o cliente está habilitado para auto-assinatura. Não há criação automática — nada acontece até que este endpoint seja chamado. ::: --- ## Solicitação da Auto-assinatura (POST) ### Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------ | ------ | --------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Este endpoint não recebe corpo. O grupo de assinantes e o template do termo de adesão são resolvidos pela QI Tech a partir do cadastro do emissor e da configuração do cliente. --- ### Response STATUS 201 Response Body ```json { "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "pending_signature", "signed_at": null, "enabled_at": null, "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce", "created_at": "2026-02-10T09:15:44", "event_list": [ { "event_type": "auto_signature_creation", "status": "pending_term_generation", "event_data": { "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154" }, "created_at": "2026-02-10T09:15:44" }, { "event_type": "adhesion_term_generation", "status": "pending_term_generation", "event_data": { "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55", "template_key": "b71f1a2c-9e44-4c1d-8f3a-6d2c0b5e7a19" }, "created_at": "2026-02-10T09:15:46" }, { "event_type": "envelope_creation", "status": "pending_signature", "event_data": { "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce" }, "created_at": "2026-02-10T09:15:47" } ] } ``` A resposta é o mesmo objeto da [consulta da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura), normalmente já em `pending_signature`, com `term_document_key` e `envelope_key` preenchidos. Em seguida, consulte os [links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) para obter o link de cada assinante. --- ### Erros | HTTP | Código | Quando ocorre | | ---- | --------------------------------------------------- | ------------------------------------------------------------------------------------- | | 400 | `ISS0000032` (`IssuerNotApproved`) | O emissor não está no status `approved`. | | 400 | `ISS0000033` (`AutoSignatureNotEnabledForTenant`) | O cliente não está habilitado para auto-assinatura. | | 403 | `ISS000011` (`TenantForbidden`) | O cliente não possui acesso completo ao cadastro do emissor informado. | | 404 | `ISS000009` (`IssuerNotFound`) | Não existe emissor para a chave informada. | | 404 | `ISS0000026` (`TenantConfigurationNotFound`) | O cliente não possui configuração de auto-assinatura cadastrada. | | 409 | `ISS0000029` (`AutoSignatureAlreadyExists`) | O emissor já possui uma auto-assinatura ativa em `pending_signature` ou `enabled`. Cancele a atual antes de solicitar outra. | --- # 登记发行人签名人组 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor 此端点允许登记与已登记发行人关联的签名人组。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | 发行人的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- | | `minimum_required_signers` * | integer | 验证该组所需的最少签名人数。 | - | | `signers` * | array | 组成签名人组的 Signer 对象列表。 | **[Signer 对象](#objeto-signer)** | ### Signer 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | 签名人全名。 | 255 | | `document_number` * | string | 签名人的 CPF（格式"XXX.XXX.XXX-XX"）。 | 11 | | `email` * | string | 签名人电子邮件地址。 | 1023 | | `phone_number`* | string | 签名人电话号码（完整格式：国家代码、区号和号码。例如：+5511999999999）。 | 20 | | `is_group_mandatory` * | boolean | 指示签名人在组内是必须还是可选的。 | - | ## 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 | 字段 | 类型 | 描述 | 最大字符数 | | ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- | | `signer_group_key` | string | 签名人组的唯一标识符（UUID v4）。 | 36 | | `minimum_required_signers` | integer | 组内所需的最少签名人数。 | - | | `signers` * | array | 组成签名人组的 Signer 对象列表。 | **[Signer 对象](#objeto-signer)** | --- # 删除发行人签名人组 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao 此端点允许删除与已登记发行人关联的签名人组。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group/ SIGNER-GROUP-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------------|--------|----------------------------------------------------------|------------| | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | | `SIGNER-GROUP-KEY` | string | 待删除签名人组的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 发行人基本登记 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico 此端点允许登记发行人的基本信息。 ## 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 | 字段 | 类型 | 描述 | 最大字符数 | | --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- | | `name` * | string | 公司全名。 | 255 | | `document_number` * | string | 公司 CNPJ（格式："XX.XXX.XXX/XXXX-XX"）。 | 14 | | `trading_name`* | string | 公司商业名称。 | 1023 | | `cnae_code`* | string | 公司 CNAE 代码（格式："XX.XX-X-XX"）。 | 7 | | `company_type`* | string | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** | | `foundation_date`* | string | 公司成立日期（格式："YYYY-MM-DD"）。 | - | | `address` * | string | 地址引用对象。 | **[address 对象](#objeto-address)** | | `annual_revenues` | number | 出让人年收入申报。 | - | | `is_in_national_financial_system` | boolean | 指示出让人是否为国家金融系统（SFN）成员。 | - | ### Address 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | 公司地址街道名称。 | 500 | | `neighborhood` * | string | 公司地址区域名称。 | 100 | | `number` * | string | 地址门牌号。 | 10 | | `postal_code` * | string | 邮政编码（格式："XXXXX-XXX"）。 | 8 | | `city` * | string | 地址城市名称。 | 255 | | `state` * | string | 州缩写（2个字符）。 | 2 | | `complement` | string | 地址补充信息（如适用）。 | 100 | ### company_type 枚举 | 枚举值 | 描述 | | -------- | ------------------ | | `ltda` | 有限责任公司 | | `sa` | 股份公司 | | `cop` | 合作社 | ## 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 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------------- | ------ | ----------------------------------- | -------------------------------------------------------------- | | `issuer_key` | string | 发行人的唯一键（UUID）。 | 36 | | `name` | string | 发行人全名。 | 255 | | `document_number` | string | 发行人的 CNPJ。 | 14 | | `status` | string | 发行人状态。 | - | | `person_type` | string | 人员类型。 | **[person_type 枚举](#enumeradores-person_type)** | | `trading_name` | string | 发行人商业名称。 | 1023 | | `cnae_code` | string | 发行人的 CNAE 代码。 | 7 | | `company_type` | string | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** | | `foundation_date` | string | 发行人成立日期。 | - | | `address` | string | 地址引用对象。 | **[address 对象](#objeto-address)** | | `registration_datetime` | string | 发行人注册日期和时间。 | - | | `expiration_date` | string | 发行人到期日期。 | - | | `annual_revenues` | number | 出让人年收入申报。 | - | | `is_in_national_financial_system` | boolean | 指示出让人是否为国家金融系统（SFN）成员。 | - | ### person_type 枚举 | 枚举值 | 描述 | | ----------- | ---------------- | | `legal` | 法人 | | `natural` | 自然人 | :::warning 警告 登记发行人时，将预留一个内部账户，该账户仅在操作完成后才会开设。 ::: ### payment_bank_account 对象 | 字段 | 类型 | 描述 | 最大字符数 | | -------------------- | ------ | --------------------------- | ---------------- | | `account_digit` * | string | 银行账户校验位。 | - | | `account_branch` * | string | 银行支行。 | - | | `account_number` * | string | 银行账户号码。 | - | --- # 登记发行人银行账户 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor 此端点允许登记与已登记发行人关联的银行账户。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | 发行人的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | | -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- | | `account_number` * | string | 银行账户号码，只能包含数字。 | 20 | | `account_digit` * | string | 账户校验位，只能包含一位数字。 | 1 | | `account_branch` * | string | 银行支行号码，只能包含数字。 | 6 | | `financial_institution_code_number`* | string | 金融机构代码（3位数字）。 | 3 | | `financial_institution_ispb` * | string | 金融机构 ISPB 代码（8位数字）。 | 8 | | `account_type` * | string | 银行账户类型。 | **[account_type 枚举](#enumeradores-account_type)** | ### account_type 枚举 | 枚举值 | 描述 | | ------------ | ------------------ | | `checking` | 活期账户 | | `savings` | 储蓄账户 | | `salary` | 工资账户 | | `payment` | 支付账户 | ## 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 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `bank_account_key` | string | 已登记银行账户的唯一标识符（UUID v4）。 | 36 | | `account_number` | string | 银行账户号码。 | 20 | | `account_digit` | string | 银行账户校验位。 | 1 | | `account_branch` | string | 银行支行号码。 | 6 | | `financial_institution_code_number` | string | 金融机构代码。 | 3 | | `financial_institution_ispb` | string | 金融机构 ISPB 代码。 | 8 | | `account_type` | string | 银行账户类型。 | **[account_type 枚举](#enumeradores-account_type)** | --- # 设置发行人主银行账户 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal 本端点将发行人已有的某个银行账户提升为主账户（`is_default: true`）。此前被标记为主账户的账户会自动变为 `is_default: false`。 --- ## 更换发行人的主银行账户 发行人可以登记多个银行账户，其中只有一个被标记为主账户。若需更正主账户中有误的数据（校验位、分行、ISPB），请使用下述流程。 :::warning 前提条件 发行人必须处于 `in_filling` 状态。超过该状态之后，主账户便不可更改 — 这是有意为之的行为，因为主账户会在金融操作中被引用。 ::: ### 更换流程（3 次调用） 1. **POST** `.../bank_account` → 创建新的（正确的）账户。 2. **POST** `.../bank_account/{key}/set_default` → 将新账户提升为主账户。 3. **DELETE** `.../bank_account/{old_key}` → 删除旧账户。 同样的顺序约束在此适用：由于不允许删除主账户，提升操作必须先于删除操作。若尝试颠倒顺序，会返回 `HTTP 400 / ISS0000012`。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY /set_default 方法 POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------------|---------|---------------------------------------------|-------| | `ISSUER-KEY` | string | 发行人的唯一键值（UUID v4）。 | 36 | | `BANK-ACCOUNT-KEY` | string | 将被提升为主账户的银行账户的唯一键值（UUID v4）。 | 36 | ### Request Body 请求体中无需提交任何内容。 --- ## Response STATUS 204 账户已提升为主账户。响应体中不返回任何内容。 --- ## 错误 | HTTP | 错误码 | 场景 | |------|--------------|--------------------------------------------| | 400 | `ISS0000011` | 发行人不处于 `in_filling` 状态。 | | 403 | `ISS000011` | 该租户无权访问此发行人。 | | 404 | `ISS000005` | 在该发行人下未找到对应的 `bank_account_key`。 | | 404 | `ISS000009` | 未找到 `issuer_key`。 | --- # 删除发行人银行账户 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao 此端点允许删除与已登记发行人关联的银行账户。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------------|--------|------------------------------------------------------|------------| | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | | `BANK-ACCOUNT-KEY` | string | 待删除银行账户的唯一键（UUID v4）。 | 36 | --- ## Response STATUS 204 响应体中不返回任何内容。 --- --- # 提交发行人文件 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor 此端点允许提交与已登记发行人关联的文件。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "proof_of_address" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | | --------------------- | ------ | ------------------------------------------------------- | ---------------------------------------------------------------- | | `document_base64` * | string | Base64 编码的文件内容。 | - | | `document_type` * | string | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** | ### document_type 枚举 | 枚举值 | 描述 | | ------------------------------- | ---------------------------------- | | `proof_of_address` | 地址证明 | | `letter_of_attorney` | 授权书 | | `company_statute` * | 公司章程或合同 | | `commercial_board_certificate` | 商业委员会证书 | | `board_election_record` | 董事会选举记录 | | `manager_declaration` | 经理声明 | | `financial_statement` | 财务报表 | | `credit_report` | 信用报告 | | `manager_statement` | 管理员声明 | | `compliance_statement` | 合规声明 | | `cnpj_card` | CNPJ 卡 | | `additional_document` | 附加文件 | :::warning 注意 所有登记均需提供 **company_statute**（公司章程）。 ::: ## Response STATUS 201 Response Body **场景 1：自动验证（OCR 成功）** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_address", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **含义**：文件已由 OCR 自动处理和验证。 **场景 2：需要人工审核** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnpj_card", "ocr_key": null } ``` **含义**：文件无法通过 OCR 自动验证，已转入人工审核队列。 :::warning 注意 成功请求（提交成功）的响应有两种不同行为，取决于自动验证（OCR）的结果。 ::: ### Response Body Params | 字段 | 类型 | 描述 | 最大长度 | | ----------------- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------- | | `document_key` | string | 提交文件的唯一标识符（UUID v4）。 | 36 | | `document_type` | string | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** | | `ocr_key` | string | 与提交文件关联的 OCR 键。 | 36 | --- # 删除发行人文件 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao 此端点允许删除已提交至发行人登记的文件。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |----------------|--------|------------------------------------------|------------| | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | | `DOCUMENT-KEY` | string | 待删除文件的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 提交发行人代表文件 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor 此端点允许提交与已登记发行人的代表关联的文件。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|--------|---------------------------------------------------|------------| | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | 发行人代表的唯一键（UUID v4）。 | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | |--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------| | `document_base64` *| string | Base64 编码的文件内容。 | - | | `document_type` * | string | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** | ### document_type 枚举 | 枚举值 | 描述 | | ------------------------------- | ---------------------------------- | | `cnh` | 驾驶证 | | `cnh_front` | 驾驶证正面 | | `cnh_back` | 驾驶证背面 | | `cnh_digital` | 数字驾驶证 | | `rg_front` | 身份证正面 | | `rg_back` | 身份证背面 | | `proof_of_address` | 地址证明 | | `letter_of_attorney` | 授权书 | | `passport` | 护照 | | `national_registry_of_foreigners`| 外国人国家登记 | :::warning 注意 所有登记均需至少提供一份身份证件（cnh、rg、passport 或 national_registry_of_foreigners），且如果代表类型为 **attorney**（代理人），还需提供授权书（letter_of_attorney）。 ::: ## Response STATUS 201 Response Body **场景 1：自动验证（OCR 成功）** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **含义**：文件已由 OCR 自动处理和验证。 **场景 2：需要人工审核** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnh", "ocr_key": null } ``` **含义**：文件无法通过 OCR 自动验证，已转入人工审核队列。 :::warning 注意 成功请求（提交成功）的响应有两种不同行为，取决于自动验证（OCR）的结果。 ::: ### Response Body Params | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|-----------------------------------------------------|-----------------------| | `document_key` | string | 提交文件的唯一标识符（UUID v4）。 | 36 | | `document_type` | string | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** | | `ocr_key` | string | 与提交文件关联的 OCR 键。 | 36 | --- # 删除发行人代表文件 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao 此端点允许删除与已登记发行人代表关联的文件。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|--------|---------------------------------------------------|------------| | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | 发行人代表的唯一键（UUID v4）。 | 36 | | `DOCUMENT-KEY` | string | 待删除文件的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 登记发行人联系信息 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor 此端点允许登记与已登记发行人关联的联系信息。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | 发行人的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | 联系人全名。 | 255 | | `document_number` * | string | 联系人证件号码（CPF，格式"XXX.XXX.XXX-XX"）。 | 14 | | `email`* | string | 联系人电子邮件地址。 | 1023 | | `phone_number`* | string | 联系人电话号码（完整格式：国家代码、区号和号码。例如：+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 | 字段 | 类型 | 描述 | 最大字符数 | | ---------------------------------- | ------ | --------------------------------------------------------------------- | --------------------- | | `issuer_contact_information_key` | string | 已登记联系信息的唯一标识符（UUID v4）。 | 36 | | `name` | string | 联系人全名。 | 255 | | `document_number` | string | 联系人证件号码（CPF）。 | 11 | | `email` | string | 联系人电子邮件地址。 | 1023 | | `phone_number` | string | 联系人电话号码。 | 20 | --- # 设置发行人主联系人 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal 本端点将发行人已有的某个联系人提升为主联系人（`is_default: true`）。此前被标记为主联系人的联系人会自动变为 `is_default: false`。 --- ## 更换发行人的主联系人 发行人可以登记多个联系人，但其中只有一个被标记为主联系人。若主联系人在登记时填入了错误数据（电子邮件拼写错误、电话号码位数有误），请使用下述流程进行替换。 :::warning 前提条件 发行人必须处于 `in_filling` 状态。一旦发行人离开该状态，就不再允许更改主联系人/主账户 — 端点会返回 `HTTP 400 / ISS0000011`。 ::: ### 更换流程（3 次调用） 1. **POST** `.../issuer_contact_information` → 创建新的（正确的）联系人。 2. **POST** `.../issuer_contact_information/{key}/set_default` → 将新联系人提升为主联系人。 3. **DELETE** `.../issuer_contact_information/{old_key}` → 删除旧的（有拼写错误的）联系人。 顺序很重要：由于不允许删除被标记为主联系人的联系人，必须先提升新联系人，再删除旧联系人。若尝试颠倒顺序，会返回 `HTTP 400 / ISS0000013`。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY /set_default 方法 POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |----------------------------------|---------|-----------------------------------------------|-------| | `ISSUER-KEY` | string | 发行人的唯一键值（UUID v4）。 | 36 | | `ISSUER-CONTACT-INFORMATION-KEY` | string | 将被提升为主联系人的联系人的唯一键值（UUID v4）。 | 36 | ### Request Body 请求体中无需提交任何内容。 --- ## Response STATUS 204 联系人已提升为主联系人。响应体中不返回任何内容。 --- ## 错误 | HTTP | 错误码 | 场景 | |------|--------------|-------------------------------------------------------------| | 400 | `ISS0000011` | 发行人不处于 `in_filling` 状态。 | | 403 | `ISS000011` | 该租户无权访问此发行人。 | | 404 | `ISS000008` | 在该发行人下未找到对应的 `issuer_contact_information_key`。 | | 404 | `ISS000009` | 未找到 `issuer_key`。 | --- # 删除发行人联系信息 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao 此端点允许删除与已登记发行人关联的联系信息。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |----------------------------------|--------|-----------------------------------------------------------|------------| | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | | `ISSUER-CONTACT-INFORMATION-KEY` | string | 待删除联系信息的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 登记发行人代表 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor 此端点允许登记与已登记发行人关联的代表。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | 发行人的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | | ---------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | `name` * | string | 发行人代表的全名。 | 255 | | `document_number` * | string | 证件号码（CPF，格式"XXX.XXX.XXX-XX"）。 | 11 | | `birthdate` | string | 代表的出生日期，ISO 8601 格式（YYYY-MM-DD）。 | - | | `document_identification_number` | string | 身份证件号码。 | 255 | | `marital_status` | string | 代表的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** | | `property_system` | string | 财产制度。 | **[property_system 枚举](#enumeradores-property_system)** | | `nationality` * | string | 受益人所在国家。 | 3，依据 ISO 3166-1 alpha-3 | | `mother_name` | string | 代表母亲的全名。 | 1023 | | `father_name` | string | 代表父亲的全名。 | 1023 | | `occupation` | string | 代表的职业或工作。 | 255 | | `is_pep` | boolean | 指示代表是否为政治敏感人物（PEP）。 | - | | `address` * | string | 地址引用对象。 | **[address 对象](#objeto-address)** | | `annual_revenues` | number | 出让人年收入申报。 | - | | `related_party_type` * | 枚举 | 关联方的关系类型。 | 参见 **[关联方类型枚举](#related-party-type)** | ### Address 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | 公司地址街道名称。 | 500 | | `neighborhood` | string | 公司地址区域名称。 | 100 | | `number` * | string | 地址门牌号。 | 10 | | `postal_code` * | string | 邮政编码（格式"XXXXX-XXX"）。 | 8 | | `city` * | string | 地址城市名称。 | 255 | | `state` * | string | 州缩写（2个字符）。 | 2 | | `complement` | string | 地址补充信息（如适用）。 | 100 | ### marital_status 枚举 | 枚举值 | 描述 | | ---------------- | ------------------ | | `single` | 未婚 | | `married` | 已婚 | | `widower` | 丧偶 | | `separated` | 分居 | | `stable_union` | 同居关系 | | `divorced` | 离婚 | ### property_system 枚举 | 枚举值 | 描述 | | --------------------------------------- | --------------------------------- | | `total_communion_of_goods` | 完全财产共同制 | | `partial_communion_of_goods` | 部分财产共同制 | | `total_separation_of_goods` | 完全财产分离制 | | `final_participation_of_acquisitions` | 婚后所得共同制 | | `compulsory_separation_of_goods` | 强制财产分离制 | ### Related Party Type | 枚举值 | 描述 | | ----------------------- | ------------- | | **president** | 总裁 | | **partner** | 合伙人 | | **administrator** | 管理员 | | **director** | 董事 | | **manager** | 经理 | | **attorney** | 代理人 | --- ## Response STATUS 201 Response Body ```json { "issuer_representative_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "document_identification_number": "987654321", "marital_status": "single", "property_system": "partial_communion_of_goods", "birthdate": "1990-01-01", "nationality": "BRA", "mother_name": "Maria da Silva", "father_name": "José da Silva", "occupation": "Advogado", "is_pep": false, "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "related_party_type": "attorney", "annual_revenues": 150000, "issuer_representative_document_list": [] } ``` ### Response Body Params | 字段 | 类型 | 描述 | 最大字符数 | | --------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | `issuer_representative_key` | string | 发行人代表的唯一标识符（UUID v4）。 | 36 | | `name` | string | 发行人代表的全名。 | 255 | | `document_number` | string | 代表的证件号码（格式"XXX.XXX.XXX-XX"）。 | 11 | | `document_identification_number` | string | 身份证件号码。 | 255 | | `marital_status` | string | 代表的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** | | `property_system` | string | 财产制度。 | **[property_system 枚举](#enumeradores-property_system)** | | `birthdate` | string | 代表的出生日期。 | - | | `nationality` * | string | 受益人所在国家。 | 3，依据 ISO 3166-1 alpha-3 | | `mother_name` | string | 代表母亲的全名。 | 1023 | | `father_name` | string | 代表父亲的全名。 | 1023 | | `occupation` | string | 代表的职业或工作。 | 255 | | `is_pep` | boolean | 指示代表是否为政治敏感人物（PEP）。 | - | | `address` * | string | 地址引用对象。 | **[address 对象](#objeto-address)** | | `issuer_representative_document_list` | array | 与代表关联的文件列表。 | - | | `annual_revenues` | number | 出让人年收入申报。 | - | | `related_party_type` * | 枚举 | 关联方的关系类型。 | 参见 **[关联方类型枚举](#related-party-type)** | --- # 删除发行人代表 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao 此端点允许删除已提交至发行人登记的代表。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|--------|--------------------------------------------------------|------------| | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | 待删除代表的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 查询发行人 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave 此端点允许通过唯一键查询系统中已登记发行人的完整详情。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------|--------|------------------------------------------|------------| | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | ## Response RESPONSE STATUS 200 状态为 *in_filling* 的 Response Body ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "in_filling", "backoffice_analysis_status": "in_analysis", "person_type": "legal", "trading_name": "Fabrica Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2025-01-23T13:47:57.354528", "expiration_date": "2026-01-23", "signer_group_list": [], "bank_account_list": [], "issuer_representative_list": [], "issuer_contact_information_list": [], "issuer_document_list": [], "issuer_analysis_list": [], "payment_bank_account": { "account_number": "19500", "account_digit": "7", "account_branch": "0001" }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` RESPONSE STATUS 200 状态为 *reproved* 的 Response Body ```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": [], "signer_group_list": [], "issuer_representative_list": [], "issuer_contact_information_list": [], "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": [], "documents": [], "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 状态为 *approved* 的 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", "bank_account_list": [], "signer_group_list": [], "issuer_representative_list": [], "issuer_contact_information_list": [], "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": [], "documents": [], "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 | 字段 | 类型 | 描述 | 最大字符数 | |--------|----------|--------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | 发行人的唯一标识符。 | 36 | | `name` | string | 发行人全名。 | 255 | | `document_number` | string | 发行人证件号码（CNPJ）。 | 14 | | `status` | string | 发行人状态。 | **[status 枚举](#enumeradores-status)** | | `backoffice_analysis_status`| string | 后台分析状态。 | - | | `person_type` | string | 人员类型（`legal` 或 `natural`）。 | - | | `trading_name` | string | 发行人商业名称。 | 1023 | | `cnae_code` | string | 发行人的 CNAE 代码。 | 10 | | `company_type` | string | 公司类型：`sa`、`ltda`、`cop`、`-`。 | 50 | | `foundation_date` | string | 发行人成立日期。 | - | | `signer_group_list` | array | 与发行人关联的签名人组列表。 | - | | `bank_account_list` | array | 与发行人关联的银行账户列表。 | - | | `issuer_representative_list` | array | 发行人代表列表。 | - | | `issuer_contact_information_list` | array | 与发行人关联的联系信息列表。 | - | | `issuer_document_list` | array | 发行人已登记的文件列表。 | - | | `address` | string | 地址引用对象。 | **[address 对象](#objeto-address)** | | `annual_revenues` | number | 出让人年收入申报。 | - | | `is_in_national_financial_system` | boolean | 指示出让人是否为国家金融系统（SFN）成员。 | - | | `last_analysis` | object | 分析对象。 | **[分析定义](#definição-de-análise)**。 | ### Address 对象 | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` | string | 公司地址街道名称。 | 500 | | `neighborhood` | string | 公司地址区域名称。 | 100 | | `number` | string | 地址门牌号。 | 10 | | `postal_code` | string | 邮政编码（仅数字）。 | 8 | | `city` | string | 地址城市名称。 | 255 | | `state` | string | 州缩写（2个字符）。 | 2 | | `complement` | string | 地址补充信息（如适用）。 | 100 | ### status 枚举 | 枚举值 | 描述 | |--------|-----------------| | `in_filling` | 填写中 | | `in_analysis` | 分析中 | | `canceled` | 已取消 | | `approved` | 已批准 | | `reproved` | 未批准 | | `expired` | 已过期 | ### payment_bank_account 对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_digit` | string | 银行账户校验位。 | - | | `account_branch` | string | 银行支行。 | - | | `account_number` | string | 银行账户号码。 | - | ### 分析定义 | 字段 | 类型 | 描述 | 字符数 | |-------|------|-----------|------------| | `analysis_key` | string | 分析标识符。 | 36 | | `analysis_number` | integer | 分析序列号。 | - | | `status` | string | 分析状态。 | 参见 **[分析状态枚举](#analysis-status)**。 | | `analysis_related_parties` | array | 分析中的关联方。 | 参见 **[分析关联方定义](#definição-de-partes-relacionadas-de-análise)**。 | | `documents` | array | 分析文件。 | 参见 **[分析文件定义](#definição-de-documentos)**。 | | `analysis_data` | object | 产生该分析的请求有效载荷。 | - | | `analysis_datetime` | string | 分析创建日期时间对象。 | - | | `reproval_reason` | string | 分析拒绝原因枚举。 | 参见 **[拒绝原因枚举](#analysis-reproval-reason)**。 | | `reproval_details` | string | 分析拒绝详细信息的自由文本字段。 | - | --- ### Analysis Status | 枚举值 | 描述 | | ----------------------- | --------------------- | | **pending_documents** | 文件待提交 | | **sent_to_analysis** | 已发送分析 | | **pending_internal_validation** | 文件验证中 | | **in_manual_analysis** | 合规人工分析中 | | **approved** | 已批准 | | **reproved** | 未批准 | --- ### 文件定义 | 字段 | 类型 | 描述 | 字符数 | |-------|------|-----------|------------| | `document_key` | string | 文件标识符。 | 36 | | `document_type` | string | 文件类型。 | | | `status` | string | 文件状态。 | | | `observation` | string | 提交的备注。 | - | --- ### 分析关联方定义 | 字段 | 类型 | 描述 | 字符数 | |-------|------|-----------|------------| | `analysis_related_party_key` | string | 关联方标识符。 | 36 | | `document_number` | string | 关联方的证件号码。 | 14 至 18 | | `name` | string | 关联方名称。 | 1 至 255 | | `documents` | array | 关联方分析文件。 | | --- ### Analysis Reproval Reason | 枚举值 | 描述 | |--------------|---------------| | **assignor_update** | 因后续注册更新而取消分析 | | **insuficient_documents** | 未提交验证权限的最少文件 | | **compliance_reproval** | 合规团队分析后拒绝关联关系 | | **unidentified_related_parties** | 已提交关联方但无法证明关联关系 | | **invalid_documents** | 文件无效/已过期 | | **missing_related_parties** | 未提交必需关联方 | --- --- # 按过滤条件查询发行人 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro 此端点允许使用证件号码（CNPJ）或姓名查询系统中已登记的发行人。 --- ## Request ENDPOINT /issuer_management/issuer MÉTODO GET ### Query Params | 字段 | 类型 | 描述 | 必填 | |-------------------|----------|------------------------------------|-------------| | `document_number` | string | 发行人的证件号码。 | 否 | | `name` | string | 发行人姓名。 | 否 | | `page` | integer | 查询的当前页码。 | 否 | | `rows_per_page` | integer | 每页记录数。 | 否 | ## 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 | 字段 | 类型 | 描述 | | |--------------|--------|---------------------|-----------------------------------------------------------------| | `data` | list | 结果列表。 | **[简化发行人对象](#objeto-emissor-simplificado)** | | `pagination` | object | 分页数据。 | **[分页对象](#objeto-paginacao)** | ### 简化发行人对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------|----------|-------------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | 发行人的唯一标识符（UUID v4）。 | 36 | | `name` | string | 发行人全名。 | 255 | | `document_number` | string | 发行人的证件号码（CNPJ）。 | 14 | | `status` | string | 发行人当前状态。 | **[status 枚举](#enumeradores-status)** | ### status 枚举 | 枚举值 | 描述 | |--------|-----------------| | `in_filling` | 填写中 | | `in_analysis` | 分析中 | | `canceled` | 已取消 | | `approved` | 已批准 | | `reproved` | 未批准 | | `expired` | 已过期 | ### 分页对象 | 字段 | 类型 | 描述 | |-------------------|----------|------------------------------------------| | `current_page` | integer | 查询的当前页码。 | | `next_page` | integer | 下一页（如果存在）。 | | `rows_per_page` | integer | 每页记录数。 | | `total_pages` | integer | 总页数。 | | `total_rows` | integer | 找到的总记录数。 | --- # 提交发行人分析 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/envio-analise/ 此端点允许将发行人的状态更改为分析中，将其发送至验证流程。 --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY MÉTODO PATCH ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | 发行人的唯一键（UUID v4）。 | 36 | ### Request Body Request Body ```json { "issuer_status": "in_analysis" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 必填 | | ----------------- | ------ | ------------------------------------------------------- | ------------ | | `issuer_status` | string | 发行人的新状态。接受值：`in_analysis`。 | 是 | ## Response 响应为发行人更新后的完整 JSON。 --- # 介绍 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/inicio 发行人登记部分对于开始发行商业票据至关重要。本节将说明整个流程，从提交初始信息到提交分析。 要访问以下章节中讨论的服务，请联系团队 [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br)，以便在沙盒环境和生产环境中进行相应授权。 ### 发行人登记 在此步骤中，必须提交发行人及其代表的所有信息、文件、联系信息、签名人组和银行账户。 一旦信息提交完成，登记将被发送至出让人登记团队进行分析，批准后该发行人将有资格参与票据发行。 如果登记已在 QI CTVM 出让人登记平台上完成，则可以使用登记访问申请端点轻松重用该登记。 ### 更新发行人 如需更新登记，必须重新提交所有发行人信息及所需修改。提交后，将生成新的分析进行验证。 一旦新的分析获批，发行人的新登记数据将正式生效。 --- # 申请访问发行人数据 URL: /zh-Hans/documentation/escrituracao/homologacao-emissor/solicitacao-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": [], "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" } } ``` ### Response Body Params | 字段 | 类型 | 描述 | 最大字符数 | |--------|----------|--------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | 发行人的唯一标识符。 | 36 | | `name` | string | 发行人全名。 | 255 | | `document_number` | string | 发行人证件号码（CNPJ）。 | 14 | | `status` | string | 发行人状态。 | **[status 枚举](#enumeradores-status)** | | `backoffice_analysis_status`| string | 后台分析状态。 | - | | `person_type` | string | 人员类型（`legal` 或 `natural`）。 | - | | `trading_name` | string | 发行人商业名称。 | 1023 | | `cnae_code` | string | 发行人的 CNAE 代码。 | 10 | | `company_type` | string | 公司类型，接受：`sa`、`ltda`、`cop`。 | 50 | | `foundation_date` | string | 发行人成立日期。 | - | | `signer_group_list` | array | 与发行人关联的签名人组列表。 | - | | `bank_account_list` | array | 与发行人关联的银行账户列表。 | - | | `issuer_representative_list` | array | 发行人代表列表。 | - | | `issuer_contact_information_list` | array | 与发行人关联的联系信息列表。 | - | | `issuer_document_list` | array | 发行人已登记的文件列表。 | - | | `address` * | string | 地址引用对象。 | **[address 对象](#objeto-address)** | ### Address 对象 | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` * | string | 公司地址街道名称。 | 500 | | `neighborhood` | string | 公司地址区域名称。 | 100 | | `number` * | string | 地址门牌号。 | 10 | | `postal_code` * | string | 邮政编码（仅数字）。 | 8 | | `city` * | string | 地址城市名称。 | 255 | | `state` * | string | 州缩写（2个字符）。 | 2 | | `complement` | string | 地址补充信息（如适用）。 | 100 | ### status 枚举 | 枚举值 | 描述 | |--------|-----------------| | `in_filling` | 填写中 | | `in_analysis` | 分析中 | | `canceled` | 已取消 | | `approved` | 已批准 | | `reproved` | 未批准 | | `expired` | 已过期 | ### payment_bank_account 对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_digit` * | string | 银行账户校验位。 | - | | `account_branch` * | string | 银行支行。 | - | | `account_number` * | string | 银行账户号码。 | - | --- # 更新投资人登记 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/ 要对投资人登记进行修改，需要将其状态设置为"in_filling"，这将重新启用所有添加/删除端点。 完成修改后，必须再次将登记提交分析，状态为"in_analysis"。 --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY MÉTODO PATCH ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 | ### Request Body Request Body ```json { "investor_status": "in_filling" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 必填 | |------------------|----------|-----------------------------------------------------|-------------| | `investor_status` | string | 投资人的新状态。接受值：`in_filling`。 | 是 | ## Response 响应为投资人更新后的完整 JSON。 --- # 登记投资人签名人组 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor 此端点允许登记与已登记投资人关联的签名人组。 :::danger 注意 无法为自然人（PF）投资人添加签名人组。 ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `INVESTOR-KEY` | string | 投资人的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- | | `minimum_required_signers` * | integer | 验证该组所需的最少签名人数。 | - | | `signers` * | array | 组成签名人组的 Signer 对象列表。 | **[Signer 对象](#objeto-signer)** | ### Signer 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | 签名人全名。 | 255 | | `document_number` * | string | 签名人的 CPF（格式"XXX.XXX.XXX-XX"）。 | 11 | | `email` * | string | 签名人电子邮件地址。 | 1023 | | `phone_number`* | string | 签名人电话号码（完整格式：国家代码、区号和号码。例如：+5511999999999）。 | 20 | | `is_group_mandatory` * | boolean | 指示签名人在组内是必须还是可选的。 | - | ## 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 | 字段 | 类型 | 描述 | 最大字符数 | | ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- | | `signer_group_key` | string | 签名人组的唯一标识符（UUID v4）。 | 36 | | `minimum_required_signers` | integer | 组内所需的最少签名人数。 | - | | `signers` * | array | 组成签名人组的 Signer 对象列表。 | **[Signer 对象](#objeto-signer)** | --- # 删除投资人签名人组 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao 此端点允许删除与已登记投资人关联的签名人组。 :::danger 注意 无法为自然人（PF）投资人删除签名人组。 ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group/ SIGNER-GROUP-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------------|--------|----------------------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 | | `SIGNER-GROUP-KEY` | string | 待删除签名人组的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 投资人基本登记 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico 此端点允许登记投资人的基本信息。**法人（PJ）**和**自然人（PF）**投资人均使用同一端点 —— 请求体的内容依据 `person_type` 字段而有所不同。 ## Request ENDPOINT /investor_management/investor MÉTODO POST ### Request Body 案例 01：法人（PJ） ```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" } } ``` 案例 02：自然人（PF） ```json { "person_type": "natural", "name": "Maria Exemplo da Silva", "document_number": "123.456.789-00", "document_identification_number": "12.345.678-9", "marital_status": "single", "property_system": null, "birthdate": "1990-05-14", "nationality": "BRA", "mother_name": "Joana Exemplo da Silva", "father_name": "José Exemplo da Silva", "occupation": "软件工程师", "is_pep": false, "email": "maria.exemplo@example.com", "phone_number": "+5511999999999", "investor_category": "retail", "investment_suitability": "moderate", "address": { "street": "Rua Exemplo", "neighborhood": "Centro", "number": "45", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Apto 12" } } ``` :::warning 注意 如果省略 `person_type` 字段，登记将被视为**法人**（`legal`）。要登记**自然人**投资人，请发送 `person_type: "natural"`。 ::: ### Request Body Params — 法人（PJ） | 字段 | 类型 | 描述 | 最大字符数 | | --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- | | `person_type` | string | 可选。如果省略，登记将被视为法人（`legal`）。 | **[person_type 枚举](#enumeradores-person_type)** | | `name` * | string | 公司全名。 | 255 | | `document_number` * | string | 公司 CNPJ（格式："XX.XXX.XXX/XXXX-XX"）。 | 14 | | `trading_name`* | string | 公司商业名称。 | 1023 | | `cnae_code`* | string | 公司 CNAE 代码（格式："XXXXX-XXX"）。 | 7 | | `company_type`* | string | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** | | `foundation_date`* | string | 公司成立日期（格式："YYYY-MM-DD"）。 | - | | `address` * | object | 地址引用对象。 | **[address 对象](#objeto-address)** | ### Request Body Params — 自然人（PF） | 字段 | 类型 | 描述 | 最大字符数 | | ----------------------------------- | ------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `person_type` * | string | 必须发送为 `"natural"`。 | **[person_type 枚举](#enumeradores-person_type)** | | `name` * | string | 投资人全名。 | 255 | | `document_number` * | string | 投资人的 CPF（格式："XXX.XXX.XXX-XX"）。 | 14 | | `document_identification_number`* | string | 投资人的身份证明文件号码（RG、CNH 或护照）。 | 255 | | `marital_status`* | string | 投资人的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** | | `property_system` | string | 财产制度。仅当 `marital_status` 要求财产制度时为必填。 | **[property_system 枚举](#enumeradores-property_system)** | | `birthdate`* | string | 投资人的出生日期（格式："YYYY-MM-DD"）。 | - | | `nationality`* | string | 投资人的国籍。 | **[nationality 枚举](#enumeradores-nationality)** | | `mother_name`* | string | 投资人母亲的姓名。 | 1023 | | `father_name`* | string | 投资人父亲的姓名。 | 1023 | | `occupation`* | string | 投资人的职业。 | 255 | | `is_pep`* | boolean | 表示投资人是否为政治公开人物（PEP）。 | - | | `email`* | string | 投资人的联系邮箱。 | 1023 | | `phone_number`* | string | 投资人的联系电话。 | 20 | | `investor_category` | string | 投资人自我声明的类别。可选。 | **[investor_category 枚举](#enumeradores-investor_category)** | | `investment_suitability` | string | 投资人自我声明的适当性档案。可选。 | **[investment_suitability 枚举](#enumeradores-investment_suitability)** | | `address` * | object | 地址引用对象。 | **[address 对象](#objeto-address)** | ### Address 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ----------------- | ------ | -------------------------------------------- | ---------------- | | `street` * | string | 地址街道名称。 | 500 | | `neighborhood` * | string | 地址区域名称。 | 100 | | `number` * | string | 地址门牌号。 | 10 | | `postal_code` * | string | 邮政编码（格式"XXXXX-XXX"）。 | 8 | | `city` * | string | 地址城市名称。 | 255 | | `state` * | string | 州缩写（2个字符）。 | 2 | | `complement` | string | 地址补充信息（如适用）。 | 100 | ### company_type 枚举 | 枚举值 | 描述 | | -------- | ------------------ | | `ltda` | 有限责任公司 | | `sa` | 股份公司 | | `cop` | 合作社 | ### marital_status 枚举 | 枚举值 | 描述 | | ------------- | ------------ | | `single` | 未婚 | | `married` | 已婚 | | `divorced` | 离婚 | | `widowed` | 丧偶 | | `separated` | 分居 | ### property_system 枚举 | 枚举值 | 描述 | | ---------------------------------------- | --------------------------------------- | | `total_communion_of_goods` | 一般共同财产制 | | `partial_communion_of_goods` | 部分共同财产制 | | `total_separation_of_goods` | 完全分别财产制 | | `final_participation_of_acquisitions` | 最终参与所得财产制 | | `compulsory_separation_of_goods` | 强制分别财产制 | ### nationality 枚举 完整的 [ISO 3166-1 alpha-3](https://www.iso.org/obp/ui/#search) 代码列表（例如：巴西为 `BRA`，美国为 `USA`）。 ### investor_category 枚举 | 枚举值 | 描述 | | ------------------ | ------------------ | | `not_applicable` | 不适用 | | `retail` | 零售 | | `qualified` | 合格投资人 | | `professional` | 专业投资人 | ### investment_suitability 枚举 | 枚举值 | 描述 | | ------------- | ------------- | | `conservative` | 保守型 | | `moderate` | 稳健型 | | `bold` | 进取型 | ## Response STATUS 201 案例 01：法人（PJ） ```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" } ``` 案例 02：自然人（PF） ```json { "investor_key": "9f8e7d6c-5b4a-3210-9876-543210fedcba", "name": "Maria Exemplo da Silva", "document_number": "123.456.789-00", "status": "in_filling", "person_type": "natural", "document_identification_number": "12.345.678-9", "marital_status": "single", "birthdate": "1990-05-14", "nationality": "BRA", "occupation": "软件工程师", "is_pep": false, "investor_category": "retail", "investment_suitability": "moderate", "address": { "street": "Rua Exemplo", "neighborhood": "Centro", "number": "45", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Apto 12" }, "registration_datetime": "2023-01-01T12:00:00Z", "expiration_date": "2024-01-01T12:00:00Z", "investor_contact_information_list": [ { "investor_contact_information_key": "3f1e2d3c-4b5a-6978-8899-aabbccddeeff", "name": "Maria Exemplo da Silva", "document_number": "123.456.789-00", "email": "maria.exemplo@example.com", "phone_number": "+5511999999999", "is_default": true } ], "signer_group_list": [ { "signer_group_key": "7a6b5c4d-3e2f-1a0b-9c8d-1234567890ab", "minimum_required_signers": 1, "signers": [ { "name": "Maria Exemplo da Silva", "document_number": "123.456.789-00", "email": "maria.exemplo@example.com", "phone_number": "+5511999999999", "is_group_mandatory": true } ] } ] } ``` :::info 信息 `investor_contact_information_list` 和 `signer_group_list` 仅在使用完整访问权限（`data_access_type == full_access`）登记时才会返回。 ::: ### Response Body Params | 字段 | 类型 | 人员 | 描述 | 最大字符数 | | ------------------------- | ------- | ----------- | -------------------------------------- | -------------------------------------------------------------- | | `investor_key` | string | 两者 | 投资人的唯一键（UUID）。 | 36 | | `name` | string | 两者 | 全名（PF）或公司名称（PJ）。 | 255 | | `document_number` | string | 两者 | 投资人的 CPF（PF）或 CNPJ（PJ）。 | 14 | | `status` | string | 两者 | 投资人状态。 | - | | `person_type` | string | 两者 | 人员类型。 | **[person_type 枚举](#enumeradores-person_type)** | | `trading_name` | string | 仅 PJ | 投资人商业名称。 | 1023 | | `cnae_code` | string | 仅 PJ | 投资人的 CNAE 代码。 | 7 | | `company_type` | string | 仅 PJ | 公司类型。 | **[company_type 枚举](#enumeradores-company_type)** | | `foundation_date` | string | 仅 PJ | 投资人成立日期。 | - | | `document_identification_number` | string | 仅 PF | 投资人的身份证明文件号码。 | 255 | | `marital_status` | string | 仅 PF | 投资人的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** | | `birthdate` | string | 仅 PF | 投资人的出生日期。 | - | | `nationality` | string | 仅 PF | 投资人的国籍。 | **[nationality 枚举](#enumeradores-nationality)** | | `occupation` | string | 仅 PF | 投资人的职业。 | 255 | | `is_pep` | boolean | 仅 PF | 表示投资人是否为 PEP。 | - | | `investor_category` | string | 仅 PF | 投资人自我声明的类别。 | **[investor_category 枚举](#enumeradores-investor_category)** | | `investment_suitability`| string | 仅 PF | 自我声明的适当性档案。 | **[investment_suitability 枚举](#enumeradores-investment_suitability)** | | `address` | object | 两者 | 地址引用对象。 | **[address 对象](#objeto-address)** | | `investor_contact_information_list` | array | 仅 PF | 投资人的联系信息列表。仅在 `data_access_type == full_access` 时返回。 | - | | `signer_group_list` | array | 仅 PF | 投资人的签署人组列表。仅在 `data_access_type == full_access` 时返回。 | - | | `registration_datetime` | string | 两者 | 投资人注册日期和时间。 | - | | `expiration_date` | string | 两者 | 投资人到期日期。 | - | ### person_type 枚举 | 枚举值 | 描述 | | ----------- | ---------------- | | `legal` | 法人 | | `natural` | 自然人 | --- # 登记投资人银行账户 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor 此端点允许登记与已登记投资人关联的银行账户。 --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `INVESTOR-KEY` | string | 投资人的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | | -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- | | `account_number` * | string | 银行账户号码，只能包含数字。 | 20 | | `account_digit` * | string | 账户校验位，只能包含一位数字。 | 1 | | `account_branch` * | string | 银行支行号码，只能包含数字。 | 6 | | `financial_institution_code_number`* | string | 金融机构代码（3位数字）。 | 3 | | `financial_institution_ispb` * | string | 金融机构 ISPB 代码（8位数字）。 | 8 | | `account_type` * | string | 银行账户类型。 | **[account_type 枚举](#enumeradores-account_type)** | ### account_type 枚举 | 枚举值 | 描述 | | ------------ | ------------------ | | `checking` | 活期账户 | | `savings` | 储蓄账户 | | `salary` | 工资账户 | | `payment` | 支付账户 | ## 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 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `bank_account_key` | string | 已登记银行账户的唯一标识符（UUID v4）。 | 36 | | `account_number` | string | 银行账户号码。 | 20 | | `account_digit` | string | 银行账户校验位。 | 1 | | `account_branch` | string | 银行支行号码。 | 6 | | `financial_institution_code_number` | string | 金融机构代码。 | 3 | | `financial_institution_ispb` | string | 金融机构 ISPB 代码。 | 8 | | `account_type` | string | 银行账户类型。 | **[account_type 枚举](#enumeradores-account_type)** | --- # 删除投资人银行账户 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao 此端点允许删除与已登记投资人关联的银行账户。 --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account/ BANK-ACCOUNT-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------------|--------|------------------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 | | `BANK-ACCOUNT-KEY` | string | 待删除银行账户的唯一键（UUID v4）。 | 36 | --- ## Response STATUS 204 响应体中不返回任何内容。 --- --- # 提交投资人文件 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor 此端点允许提交与已登记投资人关联的文件。 --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /document MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "proof_of_address" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | | --------------------- | ------ | ------------------------------------------------------- | ---------------------------------------------------------------- | | `document_base64` * | string | Base64 编码的文件内容。 | - | | `document_type` * | string | 提交文件的类型。接受的值取决于投资人的 `person_type`。 | **[document_type 枚举](#enumeradores-document_type)** | ### document_type 枚举 接受的值取决于投资人的 `person_type`。 **法人（PJ）** | 枚举值 | 描述 | | ------------------------------- | ---------------------------------- | | `proof_of_address` | 地址证明 | | `letter_of_attorney` | 授权书 | | `company_statute` * | 公司章程或合同 | | `commercial_board_certificate` | 商业委员会证书 | | `board_election_record` | 董事会选举记录 | | `manager_declaration` | 经理声明 | | `financial_statement` | 财务报表 | | `credit_report` | 信用报告 | | `manager_statement` | 管理员声明 | | `compliance_statement` | 合规声明 | | `cnpj_card` | CNPJ 卡 | | `additional_document` | 附加文件 | :::warning 注意 所有登记均需提供 **company_statute**（公司章程）。 ::: **自然人（PF）** | 枚举值 | 描述 | | ------------------------------- | ---------------------------------- | | `cnh` | 驾照（CNH） | | `cnh_front` | CNH 正面 | | `cnh_back` | CNH 背面 | | `cnh_digital` | 电子版 CNH（PDF） | | `rg_front` | RG 正面 | | `rg_back` | RG 背面 | | `passport` | 护照 | ## Response STATUS 201 Response Body **场景 1：自动验证（OCR 成功）** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_address", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **含义**：文件已由 OCR 自动处理和验证。 **场景 2：需要人工审核** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnpj_card", "ocr_key": null } ``` **含义**：文件无法通过 OCR 自动验证，已转入人工审核队列。 :::warning 注意 成功请求（提交成功）的响应有两种不同行为，取决于自动验证（OCR）的结果。 ::: ### Response Body Params | 字段 | 类型 | 描述 | 最大长度 | | ----------------- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------- | | `document_key` | string | 提交文件的唯一标识符（UUID v4）。 | 36 | | `document_type` | string | 提交文件的类型。 | **[document_type 枚举](#enumeradores-document_type)** | | `ocr_key` | string | 与提交文件关联的 OCR 键。 | 36 | --- # 删除投资人文件 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao 此端点允许删除已提交至投资人登记的文件。 --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |----------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 | | `DOCUMENT-KEY` | string | 待删除文件的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 上传投资者代表文件 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor 此端点允许上传与之前注册的投资者代表关联的文件。 :::danger 注意 无法为自然人（PF）投资人添加代表文件。 ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|--------|---------------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资者的唯一键（UUID v4）。 | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | 投资者代表的唯一键（UUID v4）。 | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 最大字符数 | |--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------| | `document_base64` * | string | Base64 编码的文件内容。 | - | | `document_type` * | string | 上传的文件类型。可接受的值： | **[document_type 枚举值](#enumeradores-document_type)** | ### document_type 枚举值 | 枚举值 | 描述 | |--------|-------------------------| | `cnh` | 驾驶执照 | | `cnh_front` | 驾驶执照正面 | | `cnh_back` | 驾驶执照背面 | | `cnh_digital` | 电子版驾驶执照 PDF | | `rg_front` | 身份证正面 | | `rg_back` | 身份证背面 | | `danfe` | DANFE | | `proof_of_address` | 居住证明 | | `letter_of_attorney` | 授权委托书 | ## Response STATUS 201 Response Body ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ``` ### Response Body Params | 字段 | 类型 | 描述 | 最大字符数 | |------------------|----------|-----------------------------------------------------|-----------------------| | `document_key` | string | 上传文件的唯一标识符（UUID v4）。 | 36 | | `document_type` | string | 上传的文件类型。 | **[document_type 枚举值](#enumeradores-document_type)** | | `ocr_key` | string | 与上传文件关联的 OCR 键。 | 36 | --- # 删除投资者代表文件 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao 此端点允许删除与之前注册的投资者代表关联的文件。 :::danger 注意 无法为自然人（PF）投资人删除代表文件。 ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|--------|---------------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资者的唯一键（UUID v4）。 | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | 投资者代表的唯一键（UUID v4）。 | 36 | | `DOCUMENT-KEY` | string | 要删除的文件的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 注册投资者联系信息 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor 此端点允许注册与之前注册的投资者关联的联系信息。 --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | 投资者的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | 联系人全名。 | 255 | | `document_number` * | string | 联系人文件编号（CPF格式，"XX.XXX.XXX/XXXX-XX"）。 | 11 | | `email` * | string | 联系人的电子邮件地址。 | 1023 | | `phone_number` * | string | 联系人的电话号码（完整格式：国家代码、区号和号码。示例：+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 | 字段 | 类型 | 描述 | 最大字符数 | | ------------------------------------ | ------ | --------------------------------------------------------------------- | --------------------- | | `investor_contact_information_key` | string | 注册联系信息的唯一标识符（UUID v4）。 | 36 | | `name` | string | 联系人全名。 | 255 | | `document_number` | string | 联系人文件编号（CPF）。 | 11 | | `email` | string | 联系人的电子邮件地址。 | 1023 | | `phone_number` | string | 联系人的电话号码。 | 20 | --- # 删除投资者联系信息 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao 此端点允许删除与之前注册的投资者关联的联系信息。 --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information/ INVESTOR-CONTACT-INFORMATION-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |----------------------------------|--------|-----------------------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资者的唯一键（UUID v4）。 | 36 | | `INVESTOR-CONTACT-INFORMATION-KEY` | string | 要删除的联系信息的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 登记投资人代表 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor 此端点允许登记与已登记投资人关联的代表。 :::danger 注意 无法为自然人（PF）投资人添加代表。 ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `INVESTOR-KEY` | string | 投资人的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | | ---------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | `name` * | string | 投资人代表的全名。 | 255 | | `document_number` * | string | 证件号码（CPF，格式"XXX.XXX.XXX-XX"）。 | 11 | | `birthdate` | string | 代表的出生日期，ISO 8601 格式（YYYY-MM-DD）。 | - | | `document_identification_number` | string | 身份证件号码。 | 255 | | `marital_status` | string | 代表的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** | | `property_system` | string | 财产制度。 | **[property_system 枚举](#enumeradores-property_system)** | | `nationality` * | string | 受益人所在国家。 | 3，依据 ISO 3166-1 alpha-3 | | `mother_name` | string | 代表母亲的全名。 | 1023 | | `father_name` | string | 代表父亲的全名。 | 1023 | | `occupation` | string | 代表的职业或工作。 | 255 | | `is_pep` | boolean | 指示代表是否为政治敏感人物（PEP）。 | - | | `address` * | string | 地址引用对象。 | **[address 对象](#objeto-address)** | | `annual_revenues` | number | 出让人年收入申报。 | - | | `related_party_type` * | 枚举 | 关联方的关系类型。 | 参见 **[关联方类型枚举](#related-party-type)** | ### Address 对象 | 字段 | 类型 | 描述 | 最大字符数 | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | 公司地址街道名称。 | 500 | | `neighborhood` | string | 公司地址区域名称。 | 100 | | `number` * | string | 地址门牌号。 | 10 | | `postal_code` * | string | 邮政编码（格式"XXXXX-XXX"）。 | 8 | | `city` * | string | 地址城市名称。 | 255 | | `state` * | string | 州缩写（2个字符）。 | 2 | | `complement` | string | 地址补充信息（如适用）。 | 100 | ### marital_status 枚举 | 枚举值 | 描述 | | ---------------- | ------------------ | | `single` | 未婚 | | `married` | 已婚 | | `widower` | 丧偶 | | `separated` | 分居 | | `stable_union` | 同居关系 | | `divorced` | 离婚 | ### property_system 枚举 | 枚举值 | 描述 | | --------------------------------------- | --------------------------------- | | `total_communion_of_goods` | 完全财产共同制 | | `partial_communion_of_goods` | 部分财产共同制 | | `total_separation_of_goods` | 完全财产分离制 | | `final_participation_of_acquisitions` | 婚后所得共同制 | | `compulsory_separation_of_goods` | 强制财产分离制 | ### Related Party Type | 枚举值 | 描述 | | ----------------------- | ------------- | | **president** | 总裁 | | **partner** | 合伙人 | | **administrator** | 管理员 | | **director** | 董事 | | **manager** | 经理 | | **attorney** | 代理人 | --- ## 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": "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, "investor_representative_document_list": [] } ``` ### Response Body Params | 字段 | 类型 | 描述 | 最大字符数 | | --------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | `investor_representative_key` | string | 投资人代表的唯一标识符（UUID v4）。 | 36 | | `name` | string | 投资人代表的全名。 | 255 | | `document_number` | string | 代表的证件号码（格式"XXX.XXX.XXX-XX"）。 | 11 | | `document_identification_number` | string | 身份证件号码。 | 255 | | `marital_status` | string | 代表的婚姻状况。 | **[marital_status 枚举](#enumeradores-marital_status)** | | `property_system` | string | 财产制度。 | **[property_system 枚举](#enumeradores-property_system)** | | `birthdate` | string | 代表的出生日期。 | - | | `nationality` * | string | 受益人所在国家。 | 3，依据 ISO 3166-1 alpha-3 | | `mother_name` | string | 代表母亲的全名。 | 1023 | | `father_name` | string | 代表父亲的全名。 | 1023 | | `occupation` | string | 代表的职业或工作。 | 255 | | `is_pep` | boolean | 指示代表是否为政治敏感人物（PEP）。 | - | | `address` * | string | 地址引用对象。 | **[address 对象](#objeto-address)** | | `investor_representative_document_list` | array | 与代表关联的文件列表。 | - | | `annual_revenues` | number | 出让人年收入申报。 | - | | `related_party_type` * | 枚举 | 关联方的关系类型。 | 参见 **[关联方类型枚举](#related-party-type)** | --- # 删除投资人代表 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao 此端点允许删除已提交至投资人登记的代表。 :::danger 注意 无法删除自然人（PF）投资人的代表。 ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY MÉTODO DELETE ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------------------|--------|--------------------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | 待删除代表的唯一键（UUID v4）。 | 36 | ## Response STATUS 204 响应体中不返回任何内容。 --- # 查询投资人 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave 此端点允许通过唯一键查询系统中已登记投资人的完整详情。 --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资人的唯一键（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 | 字段 | 类型 | 描述 | 最大字符数 | |--------|----------|--------------------------------------------------------|-------------------------------------------------| | `investor_key` | string | 投资人的唯一标识符。 | 36 | | `name` | string | 投资人全名。 | 255 | | `document_number` | string | 投资人证件号码（CNPJ）。 | 14 | | `status` | string | 投资人状态。 | **[status 枚举](#enumeradores-status)** | | `backoffice_analysis_status`| string | 后台分析状态。 | - | | `person_type` | string | 人员类型（`legal` 或 `natural`）。 | - | | `trading_name` | string | 投资人商业名称。 | 1023 | | `cnae_code` | string | 投资人的 CNAE 代码。 | 10 | | `company_type` | string | 公司类型。 | 50 | | `foundation_date` | string | 投资人成立日期。 | - | | `signer_group_list` | array | 与投资人关联的签名人组列表。 | - | | `bank_account_list` | array | 与投资人关联的银行账户列表。 | - | | `investor_representative_list` | array | 投资人代表列表。 | - | | `investor_contact_information_list` | array | 与投资人关联的联系信息列表。 | - | | `investor_document_list` | array | 投资人已登记的文件列表。 | - | | `address` | string | 地址引用对象。 | **[address 对象](#objeto-address)** | ### Address 对象 | 字段 | 类型 | 描述 | 最大字符数 | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` | string | 公司地址街道名称。 | 500 | | `neighborhood` | string | 公司地址区域名称。 | 100 | | `number` | string | 地址门牌号。 | 10 | | `postal_code` | string | 邮政编码（仅数字）。 | 8 | | `city` | string | 地址城市名称。 | 255 | | `state` | string | 州缩写（2个字符）。 | 2 | | `complement` | string | 地址补充信息（如适用）。 | 100 | ### status 枚举 | 枚举值 | 描述 | |--------|-----------------| | `in_filling` | 填写中 | | `in_analysis` | 分析中 | | `canceled` | 已取消 | | `approved` | 已批准 | | `reproved` | 未批准 | | `expired` | 已过期 | --- # 按过滤条件查询投资人 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro 此端点允许使用证件号码（CNPJ）或姓名查询系统中已登记的投资人。 --- ## Request ENDPOINT /investor_management/investor MÉTODO GET ### Query Params | 字段 | 类型 | 描述 | 必填 | |-------------------|----------|------------------------------------|-------------| | `document_number` | string | 投资人的证件号码。 | 否 | | `name` | string | 投资人姓名。 | 否 | | `page` | integer | 查询的当前页码。 | 否 | | `rows_per_page` | integer | 每页记录数。 | 否 | ## 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 | 字段 | 类型 | 描述 | | |--------------|--------|---------------------|-----------------------------------------------------------------| | `data` | list | 结果列表。 | **[简化投资人对象](#objeto-investidor-simplificado)** | | `pagination` | object | 分页数据。 | **[分页对象](#objeto-paginacao)** | ### 简化投资人对象 | 字段 | 类型 | 描述 | 最大字符数 | |-------------------|----------|-------------------------------------------------------------|-------------------------------------------------| | `investor_key` | string | 投资人的唯一标识符（UUID v4）。 | 36 | | `name` | string | 投资人全名。 | 255 | | `document_number` | string | 投资人的证件号码（CNPJ）。 | 14 | | `status` | string | 投资人当前状态。 | **[status 枚举](#enumeradores-status)** | ### status 枚举 | 枚举值 | 描述 | |--------|-----------------| | `in_filling` | 填写中 | | `in_analysis` | 分析中 | | `canceled` | 已取消 | | `approved` | 已批准 | | `reproved` | 未批准 | | `expired` | 已过期 | ### 分页对象 | 字段 | 类型 | 描述 | |-------------------|----------|------------------------------------------| | `current_page` | integer | 查询的当前页码。 | | `next_page` | integer | 下一页（如果存在）。 | | `rows_per_page` | integer | 每页记录数。 | | `total_pages` | integer | 总页数。 | | `total_rows` | integer | 找到的总记录数。 | --- # 提交投资人分析 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/envio-analise/ 此端点允许将投资人的状态更改为分析中，将其发送至验证流程。 --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY MÉTODO PATCH ### Path Params | 字段 | 类型 | 描述 | 字符数 | | -------------- | ------ | ---------------------------------- | ---------- | | `INVESTOR-KEY` | string | 投资人的唯一键（UUID v4）。 | 36 | ### Request Body Request Body ```json { "investor_status": "in_analysis" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 必填 | | ----------------- | ------ | ------------------------------------------------------- | ------------ | | `investor_status` | string | 投资人的新状态。接受值：`in_analysis`。 | 是 | ## Response 响应为投资人更新后的完整 JSON。 --- # 介绍 URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/inicio 投资人登记部分对于开始发行商业票据至关重要。本节将说明整个流程，从提交初始信息到提交分析。 要访问以下章节中讨论的服务，请联系团队 [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br)，以便在沙盒环境和生产环境中进行相应授权。 ### 投资人登记 在此步骤中，必须提交投资人及其代表的所有信息、文件、联系信息、签名人组和银行账户。 一旦信息提交完成，登记将被发送至分析团队，批准后该投资人将有资格参与票据发行。 ### 更新投资人 如需更新登记，必须重新提交所有投资人信息及所需修改。提交后，将生成新的分析进行验证。 一旦新的分析获批，投资人的新登记数据将正式生效。 --- # **申请访问投资人数据** URL: /zh-Hans/documentation/escrituracao/homologacao-investidor/solicitacao-acesso 已登记具有**唯一登记**的投资人的客户需要**申请访问投资人数据**，以便在书写系统中以该投资人作为参与方开展业务。 提交该申请后，**投资人将收到一封电子邮件，说明如何批准或拒绝访问**。 --- ## **申请访问 (POST)** ### **Request** ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request MÉTODO POST ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |---------------|--------|-----------------------------------------------|-----------------| | `INVESTOR-KEY` * | string | 投资人的唯一键（UUID v4）。 | 36 | --- ## **Request Body** 无需请求体。 --- ## **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** | 字段 | 类型 | 描述 | 最大字符数 | |--------------------------------|----------|-------------------------------------------------------------|-----------------| | `data_access_request_key` * | string | 访问申请的唯一键（UUID v4）。 | 36 | | `requested_at` * | string | 申请日期和时间（ISO 8601 格式）。 | - | | `responded_at` | string | 申请回复的日期和时间（如已回复）。 | - | | `data_access_request_status` * | string | 申请状态。 | **[data_access_request_status 枚举](#enumeradores-data_access_request_status)** | --- ## **查询申请状态 (GET)** 客户可以查看其申请是否已获批准、被拒绝或仍在审核中。 ## **Request** ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request MÉTODO GET ### **Path Params** | 字段 | 类型 | 描述 | 最大字符数 | |---------------|--------|-----------------------------------------------|-----------------| | `INVESTOR-KEY` * | string | 投资人的唯一键（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** | 字段 | 类型 | 描述 | 最大字符数 | |--------------------------------|----------|-------------------------------------------------------------|-----------------| | `data_access_request_key` * | string | 访问申请的唯一键（UUID v4）。 | 36 | | `requested_at` * | string | 申请日期和时间（ISO 8601 格式）。 | - | | `responded_at` | string | 申请回复的日期和时间（如已回复）。 | - | | `data_access_request_status` * | string | 申请状态。 | **[data_access_request_status 枚举](#enumeradores-data_access_request_status)** | --- ## **data_access_request_status 枚举** | 枚举值 | 描述 | |-------------|------------------------------------------------------| | `in_analysis` | 申请正在由投资人审核中。 | | `approved` | 访问已获批准，客户可以查看投资人数据。 | | `reproved` | 申请已被拒绝，客户将无法访问投资人数据。 | --- # 查询交易凭证 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao 此端点用于获取 QI Tech 为某次认缴执行的某笔 BaaS TED 的凭证（PDF 与元数据）。一次认缴流程（投资者付款 → 费用 → 拨付）可能产生多笔 TED，您通过 `transaction_type` 查询参数选择需要的那一笔。 如果同一次认缴中存在多笔同类型的 TED（例如多笔 `extraordinary_event_payment`），此端点仅返回最新的一笔。如需列出全部，请使用 **[查询认缴交易列表](./consulta-transacoes-integralizacao.md)**。 --- ## 查询交易凭证 (GET) ### Request ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transaction_receipt MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------------|--------|--------------------------------------------|--------| | `INTEGRALIZATION-KEY` | string | 认缴的唯一键（UUID v4）。 | 36 | ### Query Params | 字段 | 类型 | 描述 | 是否必填 | |--------------------|--------|-------------------------------------------------------------------------------------------------------|----------| | `transaction_type` | string | 要查询的 TED 类型。**[transaction_type 枚举值](#transaction_type-枚举值)** | 是 | --- ### 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 | 字段 | 类型 | 描述 | |----------------------|--------|---------------------------------------------------------------------------------------------------| | `transaction_key` | string | BaaS 侧 TED 的唯一键 — 与 `consulta-transacoes-integralizacao` 返回的值相同。 | | `transaction_amount` | number | QI Tech 记录的 TED 金额。 | | `transaction_status` | string | TED 在 BaaS 侧的状态（如 `settled`、`paid`）。 | | `pdf_encoded_string` | string | base64 编码的银行凭证字符串，解码后即可获取 PDF。 | --- ### transaction_type 枚举值 | 枚举 | 描述 | |-------------------------------|-------------------------------------------------------------------| | `disbursement` | 将发行人净额拨付到发行人银行账户的 TED。 | | `bookkeeping_fee_internal` | 支付给 QI CTVM 的内部簿记费 TED。 | | `bookkeeping_fee_external` | 支付给客户外部簿记账户的 TED。 | | `structuring_fee` | 支付给客户结构化账户的 TED。 | | `extraordinary_event_payment` | 因特殊清算事件支付给投资者的 TED。 | --- ### 错误 | HTTP | 代码 | 触发条件 | |------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------| | 400 | `HTTPMissingParam` | 未提供 `transaction_type` 查询参数。 | | 400 | `HTTPInvalidParam` | `transaction_type` 不在允许的取值范围内。 | | 404 | `ACL000004` (`IntegralizationTransactionNotFound`) | 不存在所请求类型的 TED，或该认缴从未完成清算（无任何 TED 记录）。 | :::note 404 与 `ACL000004` 在所有场景下（未知键、从未清算的认缴、缺失的 TED 类型）的返回相同 — 这是设计意图，不区分具体场景。如果需要确认认缴是否存在，请先查询其交易列表。 ::: --- # 清算账户查询 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao 本端点用于查询某个发行人清算账户的详细信息 — 银行数据（分行、账号、校验位）、状态，以及在账户已开立时的持有人信息与余额。 在账户尚未在 BaaS 中开立之前，本端点仅返回基础数据，且 `account_status: "pending"`。账户开立之后，响应中会包含额外的持有人字段与余额字段。 --- ## 清算账户查询（GET） ### Request ENDPOINT /account_liquidation/issuer/ ISSUER-KEY 方法 GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------|---------|-----------------------------|-------| | `ISSUER-KEY` | string | 发行人的唯一键值（UUID v4）。 | 36 | --- ### Response STATUS 200 Response Body — 账户已开立 ```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 — 账户待开立 ```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 | 字段 | 类型 | 描述 | |-------------------------|----------|---------------------------------------------------------| | `issuer_key` | string | 发行人的唯一键值。 | | `tenant_key` | string | 持有该账户的客户的唯一键值。 | | `bank_account_key` | string | 该银行账户在 BaaS 中的唯一键值。 | | `request_account_key` | string | 开户申请的唯一键值。 | | `account_key` | string | 该账户在 BaaS 中的唯一键值。仅在账户已开立时出现。 | | `account_branch` | string | 账户所属分行。 | | `account_number` | string | 账号。 | | `account_digit` | string | 账号校验位。 | | `account_status` | string | 账户状态。开户尚未完成时为 `pending`。 | | `account_type` | string | 该账户在 BaaS 中的类型。仅在账户已开立时出现。 | | `account_documents` | array | 与该账户关联的文件。仅在账户已开立时出现。 | | `balance` | number | 账户可用余额。仅在账户已开立时出现。 | | `blocked_balance` | number | 账户冻结余额。仅在账户已开立时出现。 | | `owner_document_number` | string | 账户持有人的 CPF/CNPJ。仅在账户已开立时出现。 | | `owner_name` | string | 账户持有人姓名/名称。仅在账户已开立时出现。 | | `owner_person_key` | string | 持有人在 BaaS 中的唯一键值。仅在账户已开立时出现。 | | `created_at` | string | 账户创建日期。仅在账户已开立时出现。 | --- ### 错误 | HTTP | 错误码 | 触发场景 | |------|----------------------------------------------------------|-------------------------------------------------| | 404 | `ACL000002`（`IssuerAccountLiquidationNotFound`） | 所提供的发行人不存在清算账户。 | | 400 | `ACL000003`（`IssuerAccountLiquidationNotBelongToTenant`） | 该发行人的清算账户不属于发起请求的客户。 | --- # 按键查询认缴 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao 此端点允许使用唯一键查询认缴流程的详情。 --- ## 查询认缴流程 (GET) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------------|--------|------------------------------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | 认缴的唯一键（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 | 字段 | 类型 | 描述 | |------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------| | `tenant_key` | string | 与认缴关联的租户唯一键。 | | `integralization_key` | string | 认缴的唯一键。 | | `operation_key` | string | 关联操作的唯一键。 | | `operation_type` | string | 操作类型。可能的值：`commercial_paper`。 | | `contract_number` | string | 与认缴关联的合同编号。 | | `issue_number` | integer | 与认缴关联的发行编号。 | | `issue_series` | integer | 与认缴关联的发行系列。 | | `issuer_key` | string | 关联发行人的唯一键。 | | `issuer_name` | string | 与认缴关联的发行人名称。 | | `issuer_document_number` | string | 发行人证件号码。 | | `issuer_bank_account` | object | 发行人银行账户数据。 | | `issuer_bank_account.account_type` | string | 银行账户类型（`checking` 等）。 | | `issuer_bank_account.account_digit` | string | 银行账户校验位。 | | `issuer_bank_account.account_branch` | string | 银行支行。 | | `issuer_bank_account.account_number` | string | 银行账户号码。 | | `issuer_bank_account.financial_institution_ispb` | string | 金融机构 ISPB。 | | `issuer_bank_account.financial_institution_code_number` | string | 金融机构代码。 | | `subscripted_quantity` | integer | 已认购的总股份数量。 | | `subscripted_total_amount` | number | 已认购股份的总价值。 | | `integralized_quantity` | integer | 已认缴的总股份数量。 | | `issue_quantity` | integer | 操作中发行的总股份数量。 | | `integralization_status` | string | **[integralization_status 枚举](#enumeradores-integralization_status)** | | `subscription_list` | array | 与认缴关联的认购列表。**[subscription 对象](#objeto-subscription)** | ### subscription 对象 | 字段 | 类型 | 描述 | |------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------------------------------------| | `subscription_key` | string | 认购的唯一键。 | | `investor_key` | string | 与认购关联的投资人唯一键。 | | `investor_name` | string | 投资人名称。 | | `investor_document_number` | string | 投资人证件号码（CPF 或 CNPJ）。 | | `investor_bank_account` | object | 投资人银行数据。 | | `subscription_date` | string | 认购日期（格式：YYYY-MM-DD）。 | | `financial_base_date` | string | 认购财务基准日期（格式：YYYY-MM-DD）。 | | `subscripted_quantity` | integer | 已认购的股份数量。 | | `unit_price` | number | 每股单价。 | | `expected_amount` | number | 认购预期总金额。 | | `paid_amount` | number | 已确认支付的认购金额。 | | `subscription_note_template_key` | string | 认购公告模板键。 | | `subscription_note_document_key` | string | 认购公告文件键。 | | `subscription_note_signature_status` | string | 认购公告签名状态。 | | `subscription_payment_list` | array | 与认购关联的付款列表。**[subscription_payment 对象](#objeto-subscription_payment)** | ### subscription_payment 对象 | 字段 | 类型 | 描述 | |------------------------------------------------------------------------|------------|----------------------------------------------------------------------------------------| | `subscription_payment_key` | string | 认购付款的唯一键。 | | `payment_receipt_document_key` | string | 付款凭证文件键。 | | `description` | string | 付款凭证说明。 | | `amount` | number | 已登记的付款金额。 | | `subscription_payment_status` | string | 付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 | | `updated_at` | string | 付款最后更新日期和时间（格式：ISO 8601）。 | ### integralization_status 枚举 | 枚举值 | 描述 | | ------------------------------- | ---------------------------------- | | `pending` | 认购待处理。 | | `finished` | 认缴已完成。 | | `canceled` | 认缴已取消。 | --- # 查询认缴交易列表 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao 此端点返回 QI Tech 为某次认缴执行的所有 BaaS TED 元数据 — 不包含 PDF。适用于了解凭证数量、执行顺序及对应的 `transaction_key`。如需获取某笔 TED 的 PDF，请使用 **[查询交易凭证](./consulta-comprovante-transacao.md)**。 响应按时间顺序排列（`created_at` 升序），包含本周期内的所有 TED（拨付、费用与特殊事件）。当存在多笔同类型 TED（如多笔 `extraordinary_event_payment`）时，全部都会出现在此处 — 与凭证端点不同（凭证端点仅返回最新一笔）。 --- ## 查询交易列表 (GET) ### Request ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transactions MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------------|--------|--------------------------------------------|--------| | `INTEGRALIZATION-KEY` | string | 认缴的唯一键（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 | 字段 | 类型 | 描述 | |----------------------|--------|-----------------------------------------------------------------------------------------------| | `transaction_key` | string | BaaS 侧 TED 的唯一键。 | | `external_id` | string | 该 TED 所属的 `integralization_key`。 | | `transaction_amount` | number | QI Tech 记录的 TED 金额。请勿用作会计对账的权威值。 | | `transaction_type` | string | TED 类型。**[transaction_type 枚举值](./consulta-comprovante-transacao.md#transaction_type-枚举值)** | | `transaction_status` | string | 当前 TED 状态（如 `paid`、`settled`）。 | | `created_at` | string | 记录创建时间（ISO 8601）。 | --- # 股份认缴介绍 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/inicio 商业票据发行流程完成后，操作将处于已发行（issued）状态。 默认情况下，签署组建条款后，股份认购认缴流程将自动进行。 查询处于已发行状态的操作时，将有一个名为 `integralization_key` 的字段，可通过该字段跟踪认缴流程。 认缴流程包括： - 股份认购 - 签署认购公告 - 付款登记 - 付款确认 --- # 登记认购 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao 此端点允许登记投资人认购某一认缴操作中特定数量股份的意向。 --- ## 登记认购 (POST) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | ----------------------- | ------ | ------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | 认缴的唯一键（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 | 字段 | 类型 | 描述 | | ------------------------------------------------------------ | ------- | ------------------------------------------------------- | | `investor_key`* | string | 投资人的唯一键（UUID v4）。 | | `investor_bank_account`* | object | 投资人银行账户数据。 | | `investor_bank_account.account_number`* | string | 投资人银行账户号码。 | | `investor_bank_account.account_digit`* | string | 投资人银行账户校验位。 | | `investor_bank_account.account_branch`* | string | 投资人银行支行。 | | `investor_bank_account.financial_institution_code_number`* | string | 投资人金融机构代码。 | | `investor_bank_account.financial_institution_ispb`* | string | 投资人金融机构 ISPB。 | | `subscripted_quantity`* | integer | 投资人希望认购的股份数量。 | | `financial_base_date`* | string | 财务基准日期。 | | `subscription_date`* | string | 认购日期。 | | `subscription_note_template_key`* | string | 认购公告模板。 | --- ### 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": [] } ``` ### **Response Body Params** | 字段 | 类型 | 描述 | | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | `subscription_key` | string | 认购的唯一键（UUID v4）。 | | `investor_key` | string | 与认购关联的投资人唯一键（UUID v4）。 | | `investor_name` | string | 投资人名称。 | | `investor_document_number` | string | 投资人证件号码（CPF 或 CNPJ）。 | | `investor_bank_account` | object | **[investor_bank_account 对象](#objeto-investor_bank_account)**。 | | `subscription_date` | string | 认购日期（格式：YYYY-MM-DD）。 | | `financial_base_date` | string | 认购财务基准日期（格式：YYYY-MM-DD）。 | | `subscripted_quantity` | integer | 已认购的股份数量。 | | `unit_price` | number | 已认购股份的单价。 | | `expected_amount` | number | 认购预期总金额。 | | `paid_amount` | number | 认购已支付总金额。 | | `subscription_note_template_key` | string | 认购公告模板的唯一键（UUID v4）。 | | `subscription_note_document_key` | string | 认购公告文件的唯一键。 | | `envelope_signature_status` | string | 认购公告签名状态。 | | `envelope_signature_url` | string | 认购公告签名 URL。 | | `envelope_key` | string | 签名信封键。 | | `subscription_payment_list` | array | 与认购关联的付款列表。**[subscription_payment_list 对象](#objeto-subscription_payment_list)**。 | --- ### investor_bank_account 对象 | 字段 | 类型 | 描述 | | ------------------------------------- | ------ | ----------------------------------------------------- | | `account_number` | string | 投资人银行账户号码。 | | `account_digit` | string | 投资人银行账户校验位。 | | `account_branch` | string | 投资人银行支行。 | | `financial_institution_code_number` | string | 投资人金融机构代码。 | | `financial_institution_ispb` | string | 投资人金融机构 ISPB。 | ### subscription_payment_list 对象 | 字段 | 类型 | 描述 | | -------------------------------- | ------ | -------------------------------------------------------------------------------------------- | | `subscription_payment_key` | string | 认购付款的唯一键（UUID v4）。 | | `payment_receipt_document_key` | string | 付款凭证文件键。 | | `description` | string | 付款凭证说明。 | | `amount` | number | 已登记的付款金额。 | | `subscription_payment_status` | string | 付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 | | `updated_at` | string | 付款最后更新日期和时间（格式：ISO 8601）。 | --- # 取消认购 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao --- ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY MÉTODO PATCH ### Path Params | 字段 | 类型 | 描述 | 字符数 | |------------------|--------|------------------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | 认缴流程的唯一键（UUID v4）。 | 36 | | `SUBSCRIPTION-KEY` | string | 认购的唯一键（UUID v4）。 | 36 | --- ### Request Body ```json { "subscription_status": "canceled" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 必填 | |-------------------|----------|-----------------------------------------|-------------| | `subscription_status` | string | 接受值：`canceled`。 | 是 | --- ### Response STATUS 200 将返回已更新的认购实例。 --- --- # 确认或拒绝认购付款 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento 此端点允许确认或拒绝与认缴认购关联的付款。付款状态将根据请求体中提供的值进行更新。 --- ## 更新付款状态 (PATCH) ### Request ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment/ SUBSCRIPTION-PAYMENT-KEY MÉTODO PATCH ### Path Params | 字段 | 类型 | 描述 | 字符数 | | ---------------------------- | ------ | ---------------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | 认缴的唯一键（UUID v4）。 | 36 | | `SUBSCRIPTION-KEY` | string | 关联认购的唯一键（UUID v4）。 | 36 | | `SUBSCRIPTION-PAYMENT-KEY` | string | 认购付款的唯一键（UUID v4）。 | 36 | --- ### Request Body ```json { "subscription_payment_status": "confirmed" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 必填 | | -------------------------------- | ------ | ------------------------------------------------------------------------- | ------------ | | `subscription_payment_status`* | string | 新付款状态。可能的值：`confirmed` 或 `denied`。 | 是 | --- ### 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 | 字段 | 类型 | 描述 | | ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | | `subscription_payment_key` | string | 认购付款的唯一键（UUID v4）。 | | `amount` | number | 已登记付款的申报金额。 | | `description` | number | 收据内容说明。 | | `subscription_payment_status` | string | 已更新的付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 | | `updated_at` | string | 付款状态更新日期和时间（格式：ISO 8601）。 | --- # 查询认购 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas 此端点允许查询进行中的认购。 --- ## 查询认购 (GET) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |-----------------------|--------|------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | 认缴的唯一键（UUID v4）。 | 36 | | `SUBSCRIPTION-KEY` | string | 认购的唯一键（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": [] } ``` --- ### **Response Body Params** | 字段 | 类型 | 描述 | |-----------------------------------------------------------|------------|---------------------------------------------------------------------------| | `subscription_key` | string | 认购的唯一键（UUID v4）。 | | `investor_key` | string | 与认购关联的投资人唯一键（UUID v4）。 | | `investor_name` | string | 投资人名称。 | | `investor_document_number` | string | 投资人证件号码（CPF 或 CNPJ）。 | | `investor_bank_account` | object | **[investor_bank_account 对象](#objeto-investor_bank_account)**。 | | `subscription_date` | string | 认购日期（格式：YYYY-MM-DD）。 | | `financial_base_date` | string | 认购财务基准日期（格式：YYYY-MM-DD）。 | | `subscripted_quantity` | integer | 已认购的股份数量。 | | `unit_price` | number | 已认购股份的单价。 | | `expected_amount` | number | 认购预期总金额。 | | `paid_amount` | number | 认购已支付总金额。 | | `subscription_note_template_key` | string | 认购公告模板的唯一键（UUID v4）。 | | `subscription_note_document_key` | string | 认购公告文件的唯一键。 | | `envelope_signature_status` | string | 认购公告签名状态。 | | `envelope_signature_url` | string | 认购公告签名 URL。 | | `envelope_key` | string | 签名信封键。 | | `subscription_payment_list` | array | 与认购关联的付款列表。**[subscription_payment_list 对象](#objeto-subscription_payment_list)**。 | --- ### investor_bank_account 对象 | 字段 | 类型 | 描述 | |--------------------------------|------------|---------------------------------------------------------| | `account_number` | string | 投资人银行账户号码。 | | `account_digit` | string | 投资人银行账户校验位。 | | `account_branch` | string | 投资人银行支行。 | | `financial_institution_code_number` | string | 投资人金融机构代码。 | | `financial_institution_ispb` | string | 投资人金融机构 ISPB。 | ### subscription_payment_list 对象 | 字段 | 类型 | 描述 | |-----------------------------------------------------------|------------|---------------------------------------------------------------------------| | `subscription_payment_key` | string | 认购付款的唯一键（UUID v4）。 | | `payment_receipt_document_key` | string | 付款凭证文件键。 | | `description` | string | 付款凭证说明。 | | `amount` | number | 已登记的付款金额。 | | `subscription_payment_status` | string | 付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 | | `updated_at` | string | 付款最后更新日期和时间（格式：ISO 8601）。 | --- # 登记认购付款 URL: /zh-Hans/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento 此端点允许登记与认缴认购关联的付款。付款包括申报金额和 Base64 格式的凭证。 --- ## 登记付款 (POST) ### Request ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment MÉTODO POST ### Path Params | 字段 | 类型 | 描述 | 字符数 | | ----------------------- | ------ | ------------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | 认缴的唯一键（UUID v4）。 | 36 | | `SUBSCRIPTION-KEY` | string | 关联认购的唯一键（UUID v4）。 | 36 | --- ### Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "amount": 100000.00, "description": "Comprovante de pagamento Itau R$100.000,00" } ``` ### Request Body Params | 字段 | 类型 | 描述 | 必填 | | -------------------- | ------- | ---------------------------------------------- | ------------ | | `document_base64`* | string | Base64 编码的付款凭证。 | 是 | | `amount`* | number | 已付款的申报金额。 | 是 | | `description` | *number | 凭证内容说明。 | 是 | --- ### 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 | 字段 | 类型 | 描述 | | ------------------------------- | ------ | ----------------------------------------------------------------------------------------------- | | `subscription_payment_key` | string | 认购付款的唯一键（UUID v4）。 | | `amount` | number | 已登记付款的申报金额。 | | `subscription_payment_status` | string | 当前付款状态。可能的值：`waiting_confirmation`、`confirmed`、`denied`。 | | `description` | number | 凭证内容说明。 | --- --- # 接收 Webhooks URL: /zh-Hans/documentation/escrituracao/introducao/autenticacao_webhooks Webhooks 的签名采用对称密钥加密策略，即 QI CTVM 和集成合作伙伴共享同一密钥。 配置 Webhooks 时，我们将生成一个 Signature Key 并提供给您。QI 系统发出的每个请求都将携带一个 SIGNATURE header，该 header 是用此密钥签名的 JWT。编码使用 HS256 算法。 以下是使用 Python 对签名进行解码的示例： ```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) ``` 我们建议集成合作伙伴除了验证签名外，还应验证我们的 IP 地址，因为我们所有请求都来自同一 IP，具体 IP 根据环境而定： |环境| IP | |--------|----| |生产| - | |沙盒 | - | :::danger 注意！ QI CTVM 的 webhooks 不应以严格方式映射。 我们的 API 返回的 webhook 载荷中可能会包含额外字段。 ::: --- # 商业票据书写 URL: /zh-Hans/documentation/escrituracao/introducao/ 本文档旨在描述操作**商业票据**发行所需的流程、端点和数据结构。 注意：如有任何流程疑问，请联系 [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br) 并详细说明您的问题/疑问，我们将为您提供协助。 ## 环境（Hosts） QI CTVM 拥有两个环境：沙盒和生产。两个环境具有完全相同的代码和行为，但沙盒环境的货币金额完全为虚构数据，而生产环境则进行有效的金融交易。 沙盒环境专为开发人员进行集成测试而创建，准备好上线生产时，只需更新生产环境变量参数即可。 | 环境 | Host | |----------|----------------------------------------------| | 沙盒 | https://api.sandbox.securities.qidtvm.com.br | | 生产 | https://api.securities.qidtvm.com.br | --- # 测试端点 URL: /zh-Hans/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste ## GET 方法 ### Request ENDPOINT /authentication_test MÉTODO GET ### Response STATUS 200 Response Body ```json { "success": "Congrats!" } ``` ## 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!" } ``` --- # 认证测试 URL: /zh-Hans/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao ### 1. 介绍 本节将说明请求应如何构建才能被我们的系统接受。 首先，在 header 中 API-CLIENT-KEY 字段填入 QI CTVM 团队提供的 Api Key。 然后，需要使用集成合作伙伴的私钥创建一个 AUTHORIZATION header 进行签名； 以下将使用 Python 逐步演示 AUTHORIZATION 的创建过程。 ### 2. 导入库 此 Python 示例使用 5 个库来完成认证过程。 ```python from datetime import datetime import json from jose import jwt from hashlib import md5 import requests ``` ### 3. 插入私钥和集成密钥 ```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. 定义变量 定义每个请求特有的方法、端点和内容变量（本示例使用 "POST" 方法访问端点 "/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. 构建签名基础字典 ```python title="Dicionário base" dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint} ``` #### 5.1. 如有必要，添加内容 对于有 _body_ 的请求，需要添加该内容的 md5 字节值。由于我们系统中所有请求均通过 JSON 格式传输， 可以使用以下方式： ```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. 对 header 进行加密 使用 JWT 库进行加密（此代码示例中，我们在 javascript 中使用 jsonwebtoken 作为 jwt） ```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. 组装最终 header ```python headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token} ``` ```python title="Definindo url final" url = f"{base_url}{endpoint}" ``` ### 发起请求 ```python resp = requests.post(url=url, headers=headers, json=body) print(resp.json()) ``` --- # 密钥交换 URL: /zh-Hans/documentation/escrituracao/introducao/troca_de_chaves ## 1. 签名请求 我们 API 的所有请求必须使用 **HTTPs** 协议，采用 **TLS 1.2 或 1.3**，并包含两个 Header： 1. API-CLIENT-KEY：由我们的集成团队提供的密钥，用于标识特定集成； 2. AUTHORIZATION：请求签名，按本手册说明的方式执行； QI CTVM 标准采用非对称密钥，包含两个不同的密钥：用于签名的 私钥 和用于读取的 公钥 。集成合作伙伴需使用 JWT 标准通过私钥进行签名。 集成合作伙伴负责生成密钥对，并将公钥提供给 QI CTVM 团队，以便我们验证您的请求。 :::caution **注意** 私钥专供集成合作伙伴使用，必须妥善保管。QI CTVM 在任何情况下都不会要求您与我们共享私钥。 ::: ## 2. 生成密钥对 要在 UNIX 计算机上生成私钥，执行以下命令： ```bash $ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key ``` 并从此私钥生成公钥。 ```bash $ openssl ec -in private.key -pubout -outform PEM -out public.key.pub ``` 生成的公钥文件（public.key.pub）需发送给 QI Tech 团队，并等待集成配置完成。 --- # 查询资产 URL: /zh-Hans/documentation/escrituracao/operacoes-ativas/consulta-security 此端点允许使用唯一键查询资产的详情。 --- ## **Request** ENDPOINT /security/security/ SECURITY-KEY MÉTODO GET ### **Path Params** | 字段 | 类型 | 描述 | 字符数 | |--------------|--------|-----------------------------------------------|------------| | `SECURITY-KEY` | string | 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": {}, "investment_list": [] } ``` ## **Response Body Params** | 字段 | 类型 | 描述 | |------------------------------|----------|--------------------------------------------------------------| | `tenant_key` | string | 与 security 关联的租户唯一键。 | | `security_key` | string | security 的唯一键。 | | `operation_key` | string | 与 security 关联的操作唯一键。 | | `operation_type` | string | 操作类型。可能的值：`commercial_paper`。 | | `contract_number` | string | 与 security 关联的合同编号。 | | `issuer_key` | string | 关联发行人的唯一键。 | | `issuer_name` | string | security 发行人名称。 | | `issuer_document_number` | string | 发行人证件号码（CPF/CNPJ）。 | | `issuer_bank_account` | object | **[issuer_bank_account 对象](#objeto-bank_account)**。 | | `financial_base_date` | string | security 的财务基准日期。 | | `current_unit_price` | number | security 的当前单价。 | | `latest_accrual_date` | string | 最后一次计息日期。 | | `integralized_quantity` | integer | 已认缴的总股份数量。 | | `issue_quantity` | integer | 操作中发行的总股份数量。 | | `security_status` | string | security 状态。可能的值：`active`、`inactive`。 | | `is_defaulted` | boolean | 指示 security 是否违约（`true` 或 `false`）。 | | `financial` | object | **[financial 对象](#objeto-financial)**。 | | `investment_list` | array | 投资列表。**[investment 对象](#objeto-investment)**。 | --- ### **bank_account 对象** | 字段 | 类型 | 描述 | |--------------------------------|----------|-------------------------------------------------| | `account_number` | string | 发行人银行账户号码。 | | `account_digit` | string | 发行人银行账户校验位。 | | `account_branch` | string | 发行人银行支行。 | | `financial_institution_ispb` | string | 发行人金融机构 ISPB。 | | `financial_institution_code_number` | string | 发行人金融机构代码。 | --- ### **financial 对象** | 字段 | 类型 | 描述 | |--------------------------------|----------|-------------------------------------------------| | `financial_base_date` | string | 财务基准日期。 | | `issue_quantity` | integer | 已发行股份数量。 | | `unit_price` | number | 每股单价。 | | `issue_amount` | number | 发行总金额。 | | `released_amount` | number | 已释放总金额。 | | `cet` | number | 总有效成本（CET）。 | | `annual_cet` | number | 年化总有效成本。 | | `number_of_installments` | integer | 总分期数。 | | `prefixed_interest_rate` | object | **[prefixed_interest_rate 对象](#objeto-prefixed_interest_rate)**。 | | `post_fixed_interest_rate` | object | **[post_fixed_interest_rate 对象](#objeto-post_fixed_interest_rate)**。 | | `financial_index` | object | **[financial_index 对象](#objeto-financial_index)**。 | | `fine_delay_rate` | object | **[fine_delay_rate 对象](#objeto-fine_delay_rate)**。 | | `contract_fine_rate` | number | 违约罚款。 | | `fees` | array | 费用列表。**[fees 对象](#objeto-fees)**。 | | `installment_list` | array | 分期列表。**[installment 对象](#objeto-installment)**。 | --- ### **investment 对象** | 字段 | 类型 | 描述 | |--------------------------------|----------|-------------------------------------------------| | `investment_key` | string | 投资的唯一键。 | | `acquisition_date` | string | 投资获取日期。 | | `acquisition_unit_price` | number | 获取时的单价。 | | `acquisition_amount` | number | 获取总金额。 | | `acquisition_quantity` | integer | 已获取股份数量。 | | `investor_key` | string | 投资人的唯一键。 | | `investor_name` | string | 投资人名称。 | | `investor_document_number` | string | 投资人证件（CPF/CNPJ）。 | | `investor_bank_account` | object | **[investor_bank_account 对象](#objeto-bank_account)**。 | | `total_sell_amount` | number | 已实现销售总金额。 | | `total_yield_amount` | number | 总收益金额。 | | `total_amortization_amount` | number | 总摊销金额。 | | `current_quantity` | integer | 当前股份数量。 | | `investment_transaction_list` | array | 交易列表。**[investment_transaction 对象](#objeto-investment_transaction)**。 | --- ### **investment_transaction 对象** | 字段 | 类型 | 描述 | |--------------------------------|----------|-------------------------------------------------| | `transaction_type` | string | 交易类型（`integralization`、`maturity`）。 | | `transaction_date` | string | 交易日期。 | | `transaction_unit_price` | number | 交易时的单价。 | | `transaction_amount` | number | 交易总金额。 | | `transaction_quantity` | integer | 已交易股份数量。 | | `amortization_amount` | number | 交易中的摊销金额。 | | `yield_amount` | number | 交易中的收益金额。 | | `old_quantity` | integer | 交易前的股份数量。 | | `new_quantity` | integer | 交易后的股份数量。 | | `investment_transaction_origin`| string | 交易来源（`subscription`、`settlement_process_payment`）。 | | `investment_transaction_origin_key` | string | 交易来源键。 | ### **prefixed_interest_rate 对象** | 字段 | 类型 | 描述 | |---------------------|--------|--------------------------------------------------| | `daily_rate` | number | 固定日利率。 | | `annual_rate` | number | 固定年利率。 | | `monthly_rate` | number | 固定月利率。 | | `interest_base` | string | 利息计算基础（`calendar_days_365`）。 | --- ### **post_fixed_interest_rate 对象** | 字段 | 类型 | 描述 | |---------------------|--------|---------------------------------------------------| | `daily_rate` | number | 浮动日利率。 | | `annual_rate` | number | 浮动年利率。 | | `monthly_rate` | number | 浮动月利率。 | | `interest_base` | string | 利息计算基础（`calendar_days_365`）。 | --- ### **financial_index 对象** | 字段 | 类型 | 描述 | |------------------|--------|-------------------------------------------------| | `index_type` | string | 金融指数类型（`CDI`、`IPCA` 等）。 | | `index_value` | number | 金融指数值。 | --- ### **fine_delay_rate 对象** | 字段 | 类型 | 描述 | |---------------------|--------|------------------------------------------------| | `daily_rate` | number | 逾期付款日利率。 | | `annual_rate` | number | 逾期付款年利率。 | | `monthly_rate` | number | 逾期付款月利率。 | | `interest_base` | string | 利息计算基础（`calendar_days_365`）。 | --- ### **fees 对象** | 字段 | 类型 | 描述 | |-------------|---------|--------------------------------------------| | `type` | string | 费用类型（`internal`、`external`）。 | | `amount` | number | 费率的百分比或绝对值。 | | `fee_type` | string | 费用类型。 | | `fee_amount`| number | 已应用费用的货币金额。 | | `amount_type` | string | 金额类型（`percentage`、`absolute`）。 | --- ### **installment 对象** | 字段 | 类型 | 描述 | |----------------------------------------|---------|-----------------------------------------------------------| | `installment_key` | string | 分期的唯一键。 | | `installment_status` | string | 分期状态。 | | `installment_number` | integer | 计划中的分期序号。 | | `workdays` | integer | 到期前的工作日数量。 | | `calendar_days` | integer | 到期前的日历日数量。 | | `principal_amortization_unit_price` | number | 本金摊销单价。 | | `principal_amortization_amount` | number | 本金摊销总金额。 | | `interest_amount` | number | 分期利息总金额。 | | `interest_amount_unit_price` | number | 分期利息单价。 | | `post_fixed_interest_amount` | number | 分期浮动利息总金额。 | | `post_fixed_interest_amount_unit_price` | number | 分期浮动利息单价。 | | `amount` | number | 分期总金额。 | | `due_principal` | number | 分期前未偿还本金金额。 | | `due_interest` | number | 分期前未偿还利息金额。 | | `due_date` | string | 分期到期日。 | | `has_interest` | boolean | 指示分期是否含有利息（`true` 或 `false`）。 | | `current_unit_price` | number | 分期更新的单价。 | | `latest_accrual_date` | string | 分期最后计息日期。 | | `paid_at` | string | 分期付款日期（如适用）。 | | `paid_amount` | number | 分期已支付总金额（如适用）。 | | `settlement_process_list` | array | 清算流程列表。**[settlement_process 对象](#objeto-settlement_process)** | ### **settlement_process 对象** | 字段 | 类型 | 描述 | |-----------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------| | `settlement_process_key` | string | 清算流程的唯一键。 | | `installment_key` | string | 与清算关联的分期唯一键。 | | `due_date` | string | 关联分期的到期日。 | | `reference_date` | string | 清算参考日期。 | | `current_integralized_quantity` | integer | 清算时已认缴的股份数量。 | | `principal_amortization_amount` | number | 本金摊销金额。 | | `interest_amount` | number | 清算中支付的利息总金额。 | | `post_fixed_interest_amount` | number | 清算中支付的浮动利息金额。 | | `fine_amount` | number | 已应用罚款金额（如有）。 | | `total_amount` | number | 清算总金额。 | | `expected_total_amount` | number | 清算预期总金额。 | | `paid_amount` | number | 清算中已支付总金额。 | | `settlement_process_status` | string | 清算状态（`waiting_payment`、`paid`、`canceled`）。 | | `paid_at` | string | 清算付款日期（如适用）。 | | `settlement_process_payment_list` | array | 与清算关联的付款列表。**[settlement_process_payment 对象](#objeto-settlement_process_payment)** | ### **settlement_process_payment 对象** | 字段 | 类型 | 描述 | |---------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------| | `settlement_process_payment_key` | string | 清算流程付款的唯一键。 | | `investment` | object | 投资信息。**[investment 对象](#objeto-investment)**。 | | `investment_quantity` | integer | 付款中涉及的投资股份数量。 | | `amount` | number | 已付款金额。 | | `paid_at` | string | 付款日期和时间（ISO 8601 格式）。 | | `settlement_process_payment_status` | string | 付款状态（`waiting_payment`、`paid`、`canceled`）。 | | `settlement_process_payment_type` | string | 付款类型（`manual`）。 | | `settlement_process_payment_receipt_list` | array | 付款收据列表。**[settlement_process_payment_receipt 对象](#objeto-settlement_process_payment_receipt)**。 | ### **settlement_process_payment_receipt 对象** | 字段 | 类型 | 描述 | |---------------------------------------------|--------|-------------------------------------------------------------------| | `settlement_process_payment_receipt_key` | string | 清算流程付款收据的唯一键。 | | `settlement_process_payment_receipt_status` | string | 收据状态（`waiting_confirmation`、`confirmed`、`denied`）。 | | `amount` | number | 收据金额。 | | `updated_at` | string | 收据最后更新日期和时间（ISO 8601 格式）。 | ### **security_status 枚举** | 枚举值 | 描述 | |-----------|------------------------------------------------------| | `issued` | security 已发行，但尚未激活。 | | `active` | security 已激活且进行中。 | | `matured` | security 已到期。 | | `canceled` | security 已取消。 | ### **installment_status 枚举** | 枚举值 | 描述 | |-----------------------------|-----------------------------------------------------------------------| | `created` | 分期已创建，但尚未开放付款。 | | `opened` | 分期已开放。 | | `waiting_payment` | 分期等待投资人付款。 | | `paid_partial` | 分期已部分支付。 | | `paid` | 分期已全额支付。 | | `paid_early` | 分期已提前支付。 | | `overdue` | 分期已到期且未支付。 | | `paid_partial_overdue` | 分期在到期后已部分支付。 | | `paid_overdue` | 分期在到期后已支付。 | | `canceled` | 分期已取消，无需支付。 | | `unmonitored` | 分期未被监控付款。 | --- # 查询投资人持仓 URL: /zh-Hans/documentation/escrituracao/operacoes-ativas/posicao-investidor 此端点允许查询投资人的综合持仓，返回其 security 持有信息。 --- ## Request ENDPOINT /security/investor/ INVESTOR-KEY MÉTODO GET ### Path Params | 字段 | 类型 | 描述 | 字符数 | |--------------|--------|-----------------------------------------------|------------| | `INVESTOR-KEY` | string | 投资人的唯一键（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 | 字段 | 类型 | 描述 | |----------------------------|----------|--------------------------------------------------------------------| | `investor_key` | string | 投资人的唯一键。 | | `investor_name` | string | 投资人名称。 | | `investor_document_number` | string | 投资人证件号码（CNPJ）。 | | `total_current_amount` | number | 投资人综合总金额。 | | `investment_list` | array | 投资人持有的 security 列表。**[investment 对象](#objeto-investment)** | ### investment 对象 | 字段 | 类型 | 描述 | |-----------------------|----------|--------------------------------------------------| | `current_unit_price` | number | security 的当前单价。 | | `current_quantity` | integer | 投资人当前持有的 security 数量。 | | `security_key` | string | 关联 security 的唯一键。 | | `contract_number` | string | security 的合同编号。 | | `investment_key` | string | 投资人投资的唯一键。 | | `current_amount` | number | 投资人持仓的当前金额。 | --- # 书写 Webhooks URL: /zh-Hans/documentation/escrituracao/webhooks-escrituracao ## 概述 书写 webhooks 允许您实时接收有关商业票据发行流程中状态变更和重要事件的通知。当事件发生时，QI Tech 会自动向您系统中配置的 URL 发送 HTTP POST 载荷。 ## Webhooks 配置 要接收 webhooks，您需要在系统中配置端点 URL。请参阅 [webhooks 配置文档](./introducao/autenticacao_webhooks.md) 了解如何注册和管理您的 webhook URL 的更多详情。 ### 认证和安全 QI Tech 发送的所有 webhooks 在 `Signature` header 中包含 HMAC-SHA256 签名。您的系统必须验证此签名，以确保接收数据的真实性和完整性。有关验证流程的更多信息，请参阅 [webhooks 认证文档](./introducao/autenticacao_webhooks.md)。 ## 可用事件 ### 发行人管理 #### 发行人登记已批准 当发行人的登记被合规团队批准时发送。 **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" } } ``` #### 发行人登记未批准 当发行人的登记被合规团队拒绝时发送。 **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" } } ``` ### 投资人管理 #### 投资人登记已批准 当投资人的登记被合规团队批准时发送。 **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" } } ``` #### 投资人登记未批准 当投资人的登记被合规团队拒绝时发送。 **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" } } ``` ### 操作管理 #### 操作已批准 当操作被合规团队批准并准备好发送签名时发送。 **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" } } ``` #### 操作未批准 当操作在审核中被拒绝时发送（自动预审或合规团队的人工审核）。该操作不会进入签署流程。 **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "compliance_reproved", "reproval_reason": { "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue." } } } ``` `reproval_reason` 字段以「键—说明」对象的形式提供拒绝原因。在自动预审中，每个键为导致该操作被拒绝的合格性规则。当拒绝未记录任何原因时，该字段可能为 `null`。 #### 操作已发送签名 当操作被发送给相关方签名时发送。 **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" } } ``` #### 操作已签名并发行 当操作被所有各方签署时发送。此事件确认商业票据已成功发行。 **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "issued", "signed_files_url": "https://storage.googleapis.com/commercial-paper-bucket/89c7f73a-c184-400c-bb2a-dd4424075a4f/signed_files?X-Goog-Algorithm=..." } } ``` `signed_files_url` 字段提供一个下载链接，其中包含该操作所有已签署合同的压缩包，适用于所有签署方式。该链接自 Webhook 发送起 7 天内有效。 #### 操作已取消 当操作被取消时发送。 **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" } } ``` ### 认购管理 #### 认购已发送签名 当认购被创建并发送给投资人签名时发送。 **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" } } ``` #### 认购已签名 当认购被所有各方签署并等待付款时发送。 **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" } } ``` #### 认购已完成 当认购在付款确认后完全完成时发送。 **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" } } ``` #### 认购已取消 当认购因整合在合格性审核中被拒绝而取消时发送。对应的整合认购单和签署信封会一并取消。 **Event Type:** `subscription.subscription_status_change` **Payload:** ```json { "event_type": "subscription.subscription_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "status": "canceled", "cancellation_reason": "ineligible", "ineligible_reasons": { "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue." } } } ``` `cancellation_reason` 字段以稳定的取值标识取消原因。当取值为 `ineligible` 时，`ineligible_reasons` 字段以「键—说明」对象的形式列出导致该整合被拒绝的合格性规则及对应说明。 ### 认购付款管理 #### 付款凭证已添加 当付款凭证被添加并等待确认时发送。 **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" } } ``` #### 付款凭证已批准 当付款凭证被批准和确认时发送。 **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" } } ``` ## 事件流程 ### 商业票据发行流程 1. **发行人登记** → `issuer_status_change`（approved/reproved） 2. **投资人登记** → `investor_status_change`（approved/reproved） 3. **创建操作** → `operation_status_change`（pending_signature_submission） 4. **发送签名** → `operation_status_change`（waiting_signature） 5. **操作发行** → `operation_status_change`（issued） ### 认购流程 1. **创建认购** → `subscription_status_change`（waiting_signature） 2. **签名完成** → `subscription_status_change`（waiting_payment） 3. **添加凭证** → `subscription_payment_status_change`（waiting_confirmation） 4. **付款确认** → `subscription_payment_status_change`（confirmed） 5. **认购完成** → `subscription_status_change`（finished） ## 最佳实践 1. **快速响应**：尽快返回 HTTP 2xx 状态以确认收到 webhook。 2. **异步处理**：对于耗时操作，立即确认接收并异步处理事件。 3. **幂等性**：实现幂等逻辑，因为网络故障时 webhooks 可能会重新发送。 4. **签名验证**：处理 webhook 前务必验证 HMAC 签名。 5. **日志和监控**：保留所有收到的 webhooks 的详细日志，用于审计和调试。 ## 参考 - [Webhooks 配置](./introducao/autenticacao_webhooks.md)