# 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 396 página(s). Índice: - Aditamento (/documentation/escrituracao/aditamento/conceito) - Baixar Documento (/documentation/escrituracao/aditamento/endpoints/baixar-documento) - Cancelar Aditamento (/documentation/escrituracao/aditamento/endpoints/cancelar-aditamento) - Consultar Aditamento (/documentation/escrituracao/aditamento/endpoints/consultar-aditamento) - Consultar Signatários (/documentation/escrituracao/aditamento/endpoints/consultar-signatarios) - Criar Aditamento (/documentation/escrituracao/aditamento/endpoints/criar-aditamento) - Simular Aditamento (/documentation/escrituracao/aditamento/endpoints/simular-aditamento) - Validar Aditamento (/documentation/escrituracao/aditamento/endpoints/validar-aditamento) - Exemplos (/documentation/escrituracao/aditamento/exemplos) - Regras de Negócio — Aditamento (/documentation/escrituracao/aditamento/regras-de-negocio) - Tipos de Alteração (/documentation/escrituracao/aditamento/tipos-de-alteracao) - Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/conceito) - Consultar Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao) - Criar Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao) - Simular Valor Presente da Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente) - Exemplos — Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/exemplos) - Amortização com Recompra (/documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao) - Regras de Negócio — Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio) - Catálogo de Erros (/documentation/escrituracao/catalogo-erros/catalogo-erros) - Configuração de Webhooks (/documentation/escrituracao/configuracao-webhooks) - Cadastro de Lastro (Ativo Subjacente) (/documentation/escrituracao/emissao-cr/cadastro-lastro) - Cadastro de Operação de CR (/documentation/escrituracao/emissao-cr/cadastro-operacao) - Envio de Documento (/documentation/escrituracao/emissao-cr/envio-documento) - Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-cr/envio-documento-externo) - Cadastro de Lastro (Ativo Subjacente) (/documentation/escrituracao/emissao-cra/cadastro-lastro) - Cadastro de Operação de CRA (/documentation/escrituracao/emissao-cra/cadastro-operacao) - Envio de Documento (/documentation/escrituracao/emissao-cra/envio-documento) - Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-cra/envio-documento-externo) - Cadastro de Lastro (Ativo Subjacente) (/documentation/escrituracao/emissao-cri/cadastro-lastro) - Cadastro de Operação de CRI (/documentation/escrituracao/emissao-cri/cadastro-operacao) - Envio de Documento (/documentation/escrituracao/emissao-cri/envio-documento) - Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-cri/envio-documento-externo) - Atualização da conta de desembolso da operação. (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso) - Atualização de dados financeiros na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros) - Atualização do método de assinatura na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura) - Envio de Garantia na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) - Remoção de Garantia na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia) - Envio de documentos (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento) - Cadastro e Remoção de Metadata na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao) - Envio e Remoção de Documentos de Representantes de Partes Relacionadas (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento) - Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) - Cadastro e Remoção de Partes Relacionadas de um documento específico (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento) - Cadastro e Remoção de Partes Relacionadas (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) - Cadastro de Operação de Nota Comercial (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) - Desembolso para terceiro na operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro) - Campos Extras (Extra Fields) (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields) - Envio do log de aceite do cliente (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite) - Cancelar Operação (/documentation/escrituracao/emissao-de-notas/cancelar-operacao) - Consulta do Link dos contratos assinados via QI SIGN da Operação (/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) - Consulta dos Links para assinatura via QI SIGN da Operação (/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) - Consulta dos Documentos da Operação (/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao) - Consulta de Operação por Chave (/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) - Consulta de Operações por Filtros (/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) - Consulta do Próximo Número de Emissão por Emissor (/documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao) - Enviar Atas de Aprovação Assinadas (/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) - Enviar Documentos Assinados da Operação (/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados) - Enviar Operação para Análise (/documentation/escrituracao/emissao-de-notas/envio-para-analise) - Enviar Operação para Assinatura (/documentation/escrituracao/emissao-de-notas/envio-para-assinatura) - Alterar Template do Termo de Adesão (/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta) - Alterar Template do Termo Constitutivo (/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) - Pré-visualizar Termo de Adesão (/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao) - Pré-visualizar Termo Constitutivo (/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) - Introdução à Emissão de Notas Comerciais (/documentation/escrituracao/emissao-de-notas/inicio) - Simulação de condições financeiras (/documentation/escrituracao/emissao-de-notas/simulacao) - Cadastro de Operação de Debênture (/documentation/escrituracao/emissao-debentures/cadastro-operacao) - Envio de Documento (/documentation/escrituracao/emissao-debentures/envio-documento) - Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-debentures/envio-documento-externo) - Envio de Garantia na Operação (/documentation/escrituracao/emissao-debentures/envio-garantia) - Alteração de Cadastro do Emissor (/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) - Consulta da Auto-assinatura (/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) - Consulta dos Links de Assinatura do Termo de Adesão (/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) - Auto-assinatura do Emissor (/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) - Solicitação da Auto-assinatura (/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) - Cadastro de Grupos de Assinantes do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) - Remoção de Grupos de Assinantes do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) - Cadastro Básico do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) - Cadastro de Conta Bancária do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor) - Definição de Conta Bancária Principal do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal) - Remoção de Conta Bancária do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) - Envio de Documentos do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor) - Remoção de Documentos do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) - Envio de Documentos do Representante do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor) - Remoção de Documentos do Representante do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) - Cadastro de Informações de Contato do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor) - Definição de Contato Principal do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal) - Remoção de Informações de Contato do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) - Cadastro de Representantes do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor) - Remoção de Representante do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) - Consulta de Emissor (/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) - Consulta de Emissores por filtros (/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) - Envio para Análise do Emissor (/documentation/escrituracao/homologacao-emissor/envio-analise/) - Introdução (/documentation/escrituracao/homologacao-emissor/inicio) - Solicitação de Acesso aos Dados do Emissor (/documentation/escrituracao/homologacao-emissor/solicitacao-acesso) - Alteraçao de Cadastro do Investidor (/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/) - Cadastro de Grupos de Assinantes do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor) - Remoção de Grupos de Assinantes do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) - Cadastro Básico do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico) - Cadastro de Conta Bancária do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor) - Remoção de Conta Bancária do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) - Envio de Documentos do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor) - Remoção de Documentos do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) - Envio de Documentos do Representante do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor) - Remoção de Documentos do Representante do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) - Cadastro de Informações de Contato do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor) - Remoção de Informações de Contato do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao) - Cadastro de Representantes do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor) - Remoção de Representante do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) - Consulta de Investidor (/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) - Consulta de Investidores por filtros (/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) - Envio para Análise do Investidor (/documentation/escrituracao/homologacao-investidor/envio-analise/) - Introdução (/documentation/escrituracao/homologacao-investidor/inicio) - **Solicitação de Acesso aos Dados do Investidor** (/documentation/escrituracao/homologacao-investidor/solicitacao-acesso) - Consulta de Comprovante de Transação (/documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao) - Consulta de Conta de Liquidação (/documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao) - Consulta de Integralização por Chave (/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) - Consulta de Transações da Integralização (/documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao) - Introdução à Integralização de Cotas (/documentation/escrituracao/integralizacao-cotas/inicio) - Cadastro de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao) - Cancelar subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao) - Confirmação ou Rejeição do Pagamento de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento) - Consulta de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas) - Registro de Pagamento de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento) - Recebimento de Webhooks (/documentation/escrituracao/introducao/autenticacao_webhooks) - Escrituração de Notas Comerciais (/documentation/escrituracao/introducao/) - Endpoints de teste (/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) - Teste de autenticação (/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao) - Troca de Chaves (/documentation/escrituracao/introducao/troca_de_chaves) - Consulta de Ativo (/documentation/escrituracao/operacoes-ativas/consulta-security) - Consulta de Posição do Investidor (/documentation/escrituracao/operacoes-ativas/posicao-investidor) - Webhooks de Escrituração (/documentation/escrituracao/webhooks-escrituracao) - Inserção de Documentos (/documentation/iaas/aditamento_recebiveis/envio_documento) - Introdução (/documentation/iaas/aditamento_recebiveis/inicio) - Criação de pedido de aditamento (/documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato) - Boletador de Títulos Públicos (/documentation/iaas/boletador/boletador_titulos_publicos) - Listagem de Títulos Públicos (/documentation/iaas/boletador/listagem_titulos_publicos) - Introdução (/documentation/iaas/boletos/inicio) - Instruções de Boleto (/documentation/iaas/boletos/instrucoes_boleto) - Recuperação de Arquivos CNAB (/documentation/iaas/boletos/recuperar_arquivo_retorno) - Recuperação de Boleto e Segunda via (/documentation/iaas/boletos/recuperar_boleto) - Recuperação de Boletos (/documentation/iaas/boletos/recuperar_boletos) - Recuperação de Carteiras de Cobrança (/documentation/iaas/boletos/recuperar_carteiras_cobranca) - Recuperação de Configurações de Boleto (/documentation/iaas/boletos/recuperar_configuracoes_boleto) - Webhooks (/documentation/iaas/boletos/webhook) - Carteira - Aprovação (/documentation/iaas/composicao_carteira/aprovar_carteira) - Carteira - Baixar a Carteira (/documentation/iaas/composicao_carteira/baixar_carteira) - Introdução (/documentation/iaas/composicao_carteira/inicio) - Carteira - Recuperação da Carteira (/documentation/iaas/composicao_carteira/recuperar_carteira) - Consulta de Aplicações Financeiras por Classe de Fundo (/documentation/iaas/cotas_de_fundo/consulta_paginada_aplicacoes_financeiras) - Consulta de Resgates por Classe de Fundo (/documentation/iaas/cotas_de_fundo/consulta_paginada_resgates) - Consulta de Séries de Emissão (/documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao) - Consulta de Posições em Cotas de Fundo (/documentation/iaas/cotas_de_fundo/consulta_posicoes_cotas_de_fundo) - Introdução (/documentation/iaas/cotas_de_fundo/inicio) - Criar Aplicação Financeira (/documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras) - Criar Pedido de Resgate (/documentation/iaas/cotas_de_fundo/operacao_resgates) - Consulta de despesas consolidadas (/documentation/iaas/despesas/despesa_consolidada/consulta_despesas) - Atualização do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao) - Cancelamento do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/cancelamento) - Criação do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/criacao) - Listagem de Contratos (/documentation/iaas/despesas/submissao_despesa/contrato/listagem) - Consulta de Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao) - Submissão do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/submissao) - Atualização da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/atualizacao) - Cancelamento da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/cancelamento) - Criação da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/criacao) - Listagem de Despesas (/documentation/iaas/despesas/submissao_despesa/despesa/listagem) - Consulta de Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao) - Submissão da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/submissao) - Listagem de Documentos (/documentation/iaas/despesas/submissao_despesa/documentos/listagem) - Upload de Documentos (/documentation/iaas/despesas/submissao_despesa/documentos/upload) - Fluxo de submissão de despesas (/documentation/iaas/despesas/submissao_despesa/fluxo_despesas) - Anotações da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes) - Atualização de Dados da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao) - Cancelamento da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento) - Cadastro de Fornecedor (/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao) - Documentos da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos) - Consulta de Fornecedores e Análises (/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem) - Submissão para Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao) - Submissão de Despesas (/documentation/iaas/despesas/submissao_despesa/inicio) - Emissões - Integralização (/documentation/iaas/emissoes/cadastrar_boleta) - Cadastro de Ativos - Emissões (/documentation/iaas/emissoes/cadastro_ativo) - Confirmação de Emissão (/documentation/iaas/emissoes/confirmacao_emissao) - Introdução (/documentation/iaas/emissoes/inicio) - Apontamentos de Compliance (/documentation/iaas/homologacao_cedente/cadastro/apontamentos) - Atualização de Cadastro (/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro) - Definição de Assinantes (/documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes) - Envio para Análise (/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise) - Envio de Cadastro (/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro) - Envio de Documentos (/documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos) - Cadastro de Filiais (/documentation/iaas/homologacao_cedente/cadastro/filiais) - Contas do cedente (/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas) - Webhooks (/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise) - Consulta de Análise (/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise) - Consulta de Assinantes (/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes) - Consulta de Cedente (/documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente) - Ativação do Produto (/documentation/iaas/homologacao_cedente/contrato_de_cessao/ativacao_da_esteira) - Consultar Documentos (/documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos) - Manipulação de contrato (/documentation/iaas/homologacao_cedente/contrato_de_cessao/manutencao_do_contrato) - Contrato de Cessão (/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato) - Recuperação do Contrato (/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato) - Webhooks do Contrato (/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato) - Webhooks do Produto (/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_produto) - Introdução (/documentation/iaas/homologacao_cedente/inicio) - Integração via SFTP (/documentation/iaas/integracao_sftp/inicio) - Recebimento de Webhooks (/documentation/iaas/introducao/autenticacao_webhooks) - Introdução (/documentation/iaas/introducao/inicio) - Integração pelo portal (/documentation/iaas/introducao/integracao_via_portal) - Pacote de Endpoints (/documentation/iaas/introducao/pacote_endpoints) - Endpoints de teste (/documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste) - Teste de autenticação (/documentation/iaas/introducao/teste_de_autenticacao/) - Troca de Chaves (/documentation/iaas/introducao/troca_de_chaves) - Início (/documentation/iaas/investidor/cadastro_investidor/inicio) - atualizacao_cadastral (/documentation/iaas/investidor/cadastro/atualizacao_cadastral) - atualizar_status_grupo_assinantes (/documentation/iaas/investidor/cadastro/atualizar_status_grupo_assinantes) - busca_informacoes_de_uma_analise_cadastral_do_investidor (/documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor) - busca_informacoes_do_investidor (/documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor) - buscar_documentos_para_assinatura (/documentation/iaas/investidor/cadastro/buscar_documentos_para_assinatura) - Buscar Dados de investidores paginado (/documentation/iaas/investidor/cadastro/buscar_investidores_paginado) - ciclo_de_vida_da_analise (/documentation/iaas/investidor/cadastro/ciclo_de_vida_da_analise) - consultar_analise_em_andamento (/documentation/iaas/investidor/cadastro/consultar_analise_em_andamento) - atualizar_status_conta_bancaria (/documentation/iaas/investidor/cadastro/contas_bancarias/atualizar_status_conta_bancaria) - definir_conta_principal (/documentation/iaas/investidor/cadastro/contas_bancarias/definir_conta_principal) - enviar_contas_bancarias (/documentation/iaas/investidor/cadastro/contas_bancarias/enviar_contas_bancarias) - Criar investidor (/documentation/iaas/investidor/cadastro/criar_investidor) - definir_grupo_assinantes_padrao (/documentation/iaas/investidor/cadastro/definir_grupo_assinantes_padrao) - enviar_cadastro_para_analise (/documentation/iaas/investidor/cadastro/enviar_cadastro_para_analise) - enviar_dados_cadastrais (/documentation/iaas/investidor/cadastro/enviar_dados_cadastrais) - enviar_endereco (/documentation/iaas/investidor/cadastro/enviar_endereco) - enviar_grupos_assinantes (/documentation/iaas/investidor/cadastro/enviar_grupos_assinantes) - enviar_investor_document (/documentation/iaas/investidor/cadastro/enviar_investor_document) - enviar_patrimonio (/documentation/iaas/investidor/cadastro/enviar_patrimonio) - consultar_feedback (/documentation/iaas/investidor/cadastro/feedback/consultar_feedback) - enviar_mensagem_feedback (/documentation/iaas/investidor/cadastro/feedback/enviar_mensagem_feedback) - listar_feedbacks (/documentation/iaas/investidor/cadastro/feedback/listar_feedbacks) - Introdução (/documentation/iaas/investidor/cadastro/introducao) - atualizar_parte_relacionada (/documentation/iaas/investidor/cadastro/related_party/atualizar_parte_relacionada) - atualizar_status_parte_relacionada (/documentation/iaas/investidor/cadastro/related_party/atualizar_status_parte_relacionada) - criar_parte_relacionada (/documentation/iaas/investidor/cadastro/related_party/criar_parte_relacionada) - enviar_documento_parte_relacionada (/documentation/iaas/investidor/cadastro/related_party/enviar_documento_parte_relacionada) - consultar_formulario_suitability (/documentation/iaas/investidor/cadastro/suitability/consultar_formulario_suitability) - enviar_suitability (/documentation/iaas/investidor/cadastro/suitability/enviar_suitability) - atualizacao_cadastral (/documentation/iaas/investidor/carteira_administrada/atualizacao_cadastral) - atualizar_status_grupo_assinantes (/documentation/iaas/investidor/carteira_administrada/atualizar_status_grupo_assinantes) - busca_informacoes_de_uma_analise_cadastral_do_investidor (/documentation/iaas/investidor/carteira_administrada/busca_informacoes_de_uma_analise_cadastral_do_investidor) - busca_informacoes_do_investidor (/documentation/iaas/investidor/carteira_administrada/busca_informacoes_do_investidor) - buscar_documentos_para_assinatura (/documentation/iaas/investidor/carteira_administrada/buscar_documentos_para_assinatura) - ciclo_de_vida_da_analise (/documentation/iaas/investidor/carteira_administrada/ciclo_de_vida_da_analise) - consultar_analise_em_andamento (/documentation/iaas/investidor/carteira_administrada/consultar_analise_em_andamento) - atualizar_status_conta_bancaria (/documentation/iaas/investidor/carteira_administrada/contas_bancarias/atualizar_status_conta_bancaria) - definir_conta_principal (/documentation/iaas/investidor/carteira_administrada/contas_bancarias/definir_conta_principal) - enviar_contas_bancarias (/documentation/iaas/investidor/carteira_administrada/contas_bancarias/enviar_contas_bancarias) - Criar investidor (/documentation/iaas/investidor/carteira_administrada/criar_investidor) - definir_grupo_assinantes_padrao (/documentation/iaas/investidor/carteira_administrada/definir_grupo_assinantes_padrao) - enviar_cadastro_para_analise (/documentation/iaas/investidor/carteira_administrada/enviar_cadastro_para_analise) - enviar_dados_cadastrais (/documentation/iaas/investidor/carteira_administrada/enviar_dados_cadastrais) - enviar_endereco (/documentation/iaas/investidor/carteira_administrada/enviar_endereco) - enviar_grupos_assinantes (/documentation/iaas/investidor/carteira_administrada/enviar_grupos_assinantes) - enviar_investor_document (/documentation/iaas/investidor/carteira_administrada/enviar_investor_document) - enviar_patrimonio (/documentation/iaas/investidor/carteira_administrada/enviar_patrimonio) - consultar_feedback (/documentation/iaas/investidor/carteira_administrada/feedback/consultar_feedback) - enviar_mensagem_feedback (/documentation/iaas/investidor/carteira_administrada/feedback/enviar_mensagem_feedback) - listar_feedbacks (/documentation/iaas/investidor/carteira_administrada/feedback/listar_feedbacks) - Introdução (/documentation/iaas/investidor/carteira_administrada/introducao) - enviar_documento_investor_owner (/documentation/iaas/investidor/carteira_administrada/investor_owner/enviar_documento_investor_owner) - atualizar_parte_relacionada (/documentation/iaas/investidor/carteira_administrada/related_party/atualizar_parte_relacionada) - atualizar_status_parte_relacionada (/documentation/iaas/investidor/carteira_administrada/related_party/atualizar_status_parte_relacionada) - criar_parte_relacionada (/documentation/iaas/investidor/carteira_administrada/related_party/criar_parte_relacionada) - enviar_documento_parte_relacionada (/documentation/iaas/investidor/carteira_administrada/related_party/enviar_documento_parte_relacionada) - consultar_formulario_suitability (/documentation/iaas/investidor/carteira_administrada/suitability/consultar_formulario_suitability) - enviar_suitability (/documentation/iaas/investidor/carteira_administrada/suitability/enviar_suitability) - Adicionar Conta Bancária (/documentation/iaas/investidor/compartilhado/contas_bancarias/adicionar_contas_bancarias) - Atualizar Conta Bancária (/documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_conta_bancaria) - Consultar Contas Bancárias (/documentation/iaas/investidor/compartilhado/contas_bancarias/buscar_contas_bancarias) - assinar_documento (/documentation/iaas/investidor/distribuicao_externa/assinar_documento) - atualizacao_cadastral (/documentation/iaas/investidor/distribuicao_externa/atualizacao_cadastral) - atualizar_status_grupo_assinantes (/documentation/iaas/investidor/distribuicao_externa/atualizar_status_grupo_assinantes) - busca_informacoes_de_uma_analise_cadastral_do_investidor (/documentation/iaas/investidor/distribuicao_externa/busca_informacoes_de_uma_analise_cadastral_do_investidor) - busca_informacoes_do_investidor (/documentation/iaas/investidor/distribuicao_externa/busca_informacoes_do_investidor) - buscar_documentos_para_assinatura (/documentation/iaas/investidor/distribuicao_externa/buscar_documentos_para_assinatura) - ciclo_de_vida_da_analise (/documentation/iaas/investidor/distribuicao_externa/ciclo_de_vida_da_analise) - consultar_analise_em_andamento (/documentation/iaas/investidor/distribuicao_externa/consultar_analise_em_andamento) - atualizar_status_conta_bancaria (/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/atualizar_status_conta_bancaria) - definir_conta_principal (/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/definir_conta_principal) - enviar_contas_bancarias (/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/enviar_contas_bancarias) - Criar investidor (/documentation/iaas/investidor/distribuicao_externa/criar_investidor) - definir_grupo_assinantes_padrao (/documentation/iaas/investidor/distribuicao_externa/definir_grupo_assinantes_padrao) - enviar_cadastro_para_analise (/documentation/iaas/investidor/distribuicao_externa/enviar_cadastro_para_analise) - Enviar Dados Cadastrais do Investidor (/documentation/iaas/investidor/distribuicao_externa/enviar_dados_cadastrais) - enviar_documento_assinado (/documentation/iaas/investidor/distribuicao_externa/enviar_documento_assinado) - enviar_endereco (/documentation/iaas/investidor/distribuicao_externa/enviar_endereco) - enviar_grupos_assinantes (/documentation/iaas/investidor/distribuicao_externa/enviar_grupos_assinantes) - Enviar Documento do Investidor (/documentation/iaas/investidor/distribuicao_externa/enviar_investor_document) - enviar_patrimonio (/documentation/iaas/investidor/distribuicao_externa/enviar_patrimonio) - Enviar Suitability (/documentation/iaas/investidor/distribuicao_externa/enviar_suitability) - consultar_feedback (/documentation/iaas/investidor/distribuicao_externa/feedback/consultar_feedback) - enviar_mensagem_feedback (/documentation/iaas/investidor/distribuicao_externa/feedback/enviar_mensagem_feedback) - listar_feedbacks (/documentation/iaas/investidor/distribuicao_externa/feedback/listar_feedbacks) - Introdução (/documentation/iaas/investidor/distribuicao_externa/introducao) - criar_investor_owner (/documentation/iaas/investidor/distribuicao_externa/investor_owner/criar_investor_owner) - enviar_documento_investor_owner (/documentation/iaas/investidor/distribuicao_externa/investor_owner/enviar_documento_investor_owner) - atualizar_parte_relacionada (/documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_parte_relacionada) - atualizar_status_parte_relacionada (/documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_status_parte_relacionada) - criar_parte_relacionada (/documentation/iaas/investidor/distribuicao_externa/related_party/criar_parte_relacionada) - enviar_documento_parte_relacionada (/documentation/iaas/investidor/distribuicao_externa/related_party/enviar_documento_parte_relacionada) - Recuperando Informações da Posição do Investidor (/documentation/iaas/investidor/informacoes_posicao_investidor) - Layout CNAB 444 — Baixa (/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa) - Baixa por Arquivo (/documentation/iaas/liquidacao_ativos/arquivo/inicio) - Inserção de Liquidações (/documentation/iaas/liquidacao_ativos/ativos/) - Remoção de Liquidações (/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes) - Webhooks de Liquidação (/documentation/iaas/liquidacao_ativos/ativos/webhook) - Fluxo de liquidação de ativos (/documentation/iaas/liquidacao_ativos/fluxo_liquidacao) - Liquidação de Ativos (/documentation/iaas/liquidacao_ativos/inicio) - Criação do Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) - Encerrar Inserção no Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) - Listagem de Lotes de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/listagem) - Webhooks do Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) - Layout CNAB 444 — Cessão (/documentation/iaas/negociacao_recebiveis/arquivo/cnab444) - Layout CSV — Contratos Parcelados (/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado) - Cessão por Arquivo (/documentation/iaas/negociacao_recebiveis/arquivo/inicio) - Criação de Ativo — CCB (/documentation/iaas/negociacao_recebiveis/asset/criacao_co) - Criação de Ativo — Contrato Parcelado (/documentation/iaas/negociacao_recebiveis/asset/criacao_contract) - Criação de Ativo — CTE (/documentation/iaas/negociacao_recebiveis/asset/criacao_cte) - Criação de Ativo — Contrato Descontado (/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract) - Criação de Ativo — Duplicata (/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata) - Inserção de Ativo para Recompra (/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset) - Inserção de Documentos do Ativo (/documentation/iaas/negociacao_recebiveis/asset/documents) - Consulta de Ativos do Lote (/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos) - Remoção de Ativos do Lote (/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) - Webhooks do Ativo (/documentation/iaas/negociacao_recebiveis/asset/webhooks) - Aprovação do Gestor (/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) - Criação do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/criacao) - Documentos da Cessão (/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao) - Encerrar Inserção de Ativos (/documentation/iaas/negociacao_recebiveis/assignment/fechamento) - Listagem de Lotes de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/listagem) - Recuperação do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/recuperacao) - Como criar uma cessão? (/documentation/iaas/negociacao_recebiveis/assignment/video_cessao) - Webhooks do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/webhooks) - Fluxo de Cessão (/documentation/iaas/negociacao_recebiveis/fluxo_cessao) - Cessão de Direitos Creditórios (/documentation/iaas/negociacao_recebiveis/inicio) - Listagem de Configurações de Cessão (/documentation/iaas/negociacao_recebiveis/listagem) - Listagem de Solicitações de Amortização (/documentation/iaas/passivo/amortizacao/listagem) - Consulta paginada de Aplicação Financeira (/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras) - Consulta paginada de Fechamento das Aplicações Financeiras (/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_fechamento_das_aplicacoes_financeiras) - Consultar Aplicação Financeira por chave (/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave) - Criar Aplicação Financeira (/documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira) - Aprovação manual de bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/aprovar_bloqueio_pendente_aprovacao) - Consultar bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas) - Consultar bloqueio de cotas de um investidor (/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas_de_um_investidor) - Enviar Documento da Garantia (/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_da_garantia) - Enviar Documento do Ativo (/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_do_ativo) - Execução de garantia (/documentation/iaas/passivo/bloqueio_de_cotas/execucao_de_garantia) - Reduzir bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/reduzir_bloqueio_de_cotas) - Solicitar bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas) - Webhook de bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota) - Consulta paginada de investidores por classe de fundo (/documentation/iaas/passivo/consultas/consulta_investidores_classe_fundo) - Consulta paginada de posições de cotistas por classe de fundo (/documentation/iaas/passivo/consultas/consulta_posicoes_cotistas_classe_fundo) - Consulta paginada do Mapa de Evolução de Cotas (/documentation/iaas/passivo/consultas/consultar_mapa_de_evolucao_de_cotas) - Consulta paginada de Séries de Emissão (/documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao) - Consulta paginada de Fundos (/documentation/iaas/passivo/consultas/consultar_todos_fundos) - Enviar Boletim de Subscrição Assinado (/documentation/iaas/passivo/controle_de_oferta/enviar_boletim_de_subscricao_assinado) - Recuperando Informações sobre Boletim de Subscrição (/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao) - Recuperando Informações sobre as Ofertas (/documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas) - Solicitar Boletim de Subscrição (/documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao) - Recuperando Cotas Públicas (/documentation/iaas/passivo/fundos/cotas_publicas) - Introdução (/documentation/iaas/passivo/inicio) - Consulta paginada de negociações em mercado secundário (/documentation/iaas/passivo/mercado_secundario/consulta_negociacoes_mercado_secundario) - Consultar Pedido de Resgate por chave (/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave) - Consulta paginada de pedidos de resgate por classe de fundo (/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo) - Consulta paginada de pedidos de resgate por investidor (/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor) - Criar Pedido de Resgate (/documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate) - Enviar Termo de Adesão Assinado (/documentation/iaas/passivo/termo_de_adesao/enviar_termo_de_adesao_assinado) - Solicitar Termo de Adesão (/documentation/iaas/passivo/termo_de_adesao/solicitar_termo_de_adesao) - Razão Contábil (/documentation/iaas/relatorios_dtvm/accounting_ledger) - Composição de Carteira de Ativos (/documentation/iaas/relatorios_dtvm/assets_wallet_composition) - Composição de Ativos da Cessão (/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) - Lastros da Cessão (/documentation/iaas/relatorios_dtvm/assignment_documents) - Relatório de Balanço (/documentation/iaas/relatorios_dtvm/balance_report) - Demonstrativo de Caixa (/documentation/iaas/relatorios_dtvm/cash_account_demonstrative) - Movimentações de Caixa (/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements) - Aquisição Consolidada de Direitos Creditórios (/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) - Conciliação Consolidada de Direitos Creditórios (/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets) - Relatórios DTVM (/documentation/iaas/relatorios_dtvm/) - Cotas MEC (/documentation/iaas/relatorios_dtvm/quota_mec) - Testando a Captura de Lastro (/documentation/iaas/relatorios_dtvm/testar_captura_lastro) - Composição da Carteira (/documentation/iaas/relatorios_dtvm/wallet_composition) - Webhook de Entrega (/documentation/iaas/relatorios_dtvm/webhook_de_entrega) - XML ANBIMA (tipos 5 e 401) (/documentation/iaas/relatorios_dtvm/xml_anbima) - Criação de um ativo a ser recomprado/vendido (/documentation/iaas/venda_ativos/asset/criacao_recompra) - Criação de um lote de recompra (/documentation/iaas/venda_ativos/assignment/criacao_recompra) - Encerrar Inserção de Ativos (/documentation/iaas/venda_ativos/assignment/fechamento_recompra) - Recompra e Venda de Ativos (/documentation/iaas/venda_ativos/inicio) - Recuperando Informações da Conta (/documentation/iaas/visibildade_de_caixa/get_accounts) - Recuperando Transações de uma Conta (/documentation/iaas/visibildade_de_caixa/get_transactions) - Introdução (/documentation/iaas/visibildade_de_caixa/inicio) - Transferência entre contas do fundo (/documentation/iaas/visibildade_de_caixa/post_internal_transfer) - Criando Pedido de Estorno (/documentation/iaas/visibildade_de_caixa/post_transaction_reversal) - Webhooks (/documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal) --- # Aditamento URL: /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: /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: /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: /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: /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: /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: /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: /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: /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: /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: /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) --- # Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/conceito ## Visão geral Amortização extraordinária é o processo de reduzir o saldo devedor de uma emissão fora do cronograma ordinário — quando o emissor antecipa um pagamento, quita parcelas adiante do vencimento ou refinancia parte da dívida. O QI Tech recebe esse pedido via API, valida os valores e registra o evento para liquidação posterior, sem interferir nas amortizações ordinárias geradas em cada `due_date` (data de vencimento). Os cenários típicos envolvem quitação antecipada pelo emissor, pagamento antecipado de uma ou mais parcelas e operações de refinanciamento parcial. Em todos esses casos o integrador inicia o fluxo sob demanda, informando qual parcela (ou conjunto de parcelas) está sendo amortizada e qual o valor. Você recorre a esta API sempre que precisa alterar o saldo devedor fora da agenda ordinária de pagamentos. O resultado é sempre um evento rastreável, com `status` próprio e registro financeiro. A criação é fire-and-forget: a QI Tech orquestra liquidação, finalização e cancelamento internamente, sem que o integrador precise chamar endpoints adicionais. ## Amortização ordinária vs extraordinária A amortização ordinária é gerada automaticamente pela QI Tech: em cada `due_date` (data de vencimento), o processo de liquidação da parcela é criado internamente sem ação do integrador. Já a amortização extraordinária é sempre iniciada sob demanda, por chamada explícita à API. As duas coexistem — registrar uma amortização extraordinária não cancela nem substitui as ordinárias que ainda vão vencer; apenas adiciona um novo evento de liquidação sobre o ativo. ## Tipos de amortização Os sete tipos suportados ficam no campo `amortization_type`. Em todos eles `installment_list` define as parcelas-alvo; o tipo define como o `amount` é distribuído entre elas: - `equal_amount` (valores proporcionais) — distribui proporcionalmente o valor informado entre as parcelas selecionadas, vencidas primeiro e depois as futuras. - `first_installments` (primeiras parcelas) — aplica o valor sequencialmente às N primeiras parcelas selecionadas (por vencimento) até esgotá-lo. - `present_amount` (valor presente) — o integrador escolhe as parcelas e pode informar `total_discount`; a ordem de distribuição é juros → multa → principal. - `matured_installments` (parcelas vencidas) — aplica o valor exclusivamente a parcelas já vencidas. - `early_amortization` (amortização antecipada) — antecipa o pagamento de uma parcela futura. - `nominal_amount` (valor nominal) — quita parcelas futuras pelo valor nominal (principal + juros no vencimento), sem trazê-las ao Valor Presente; não aceita parcelas vencidas. - `full_amortization` (quitação integral) — rateia o `amount` proporcionalmente ao Valor Presente entre **todas** as parcelas selecionadas, sem cascata, e quita cada uma integralmente na liquidação, mesmo que a cota recebida seja menor que o Valor Presente; a diferença fica registrada como `discount_amount` de cada parcela. Apenas `early_amortization` e `nominal_amount` permitem pagamento parcial — os outros cinco exigem cobertura integral do valor declarado dentro da tolerância. ## Conceitos-chave - **`event_conciliation`** — corresponde ao evento de conciliação de uma parcela específica. Responsável pelo ato de conciliação de pagamentos e/ou amortizações extraordinárias de parcelas de um valor mobiliário. - **`reference_date`** — data de referência fornecida pelo chamador em toda criação (deve corresponder à data de quitação). O QI Tech nunca usa `date.today()`: toda lógica relativa a datas (classificação de vencimento, projeção do Valor Presente, discriminação de parcelas vencidas vs a vencer) parte desse campo. - **Valor Presente** — calculado internamente e consumido durante a criação do evento. O integrador não precisa calcular Valor Presente no seu lado. - **Tolerância (`tolerance_amount`)** — diferença máxima aceita entre o valor de liquidação e o valor esperado da parcela. Default de R$ 0,01. Diferenças acima da tolerância fazem a liquidação ser rejeitada. - **Estado parcial derivado** — quando `paid_amount > 0` e `paid_amount < expected_amount`, a parcela é considerada parcialmente paga. Não há novo status: o estado é DERIVADO das colunas `paid_amount` e `expected_amount`. O status `pending_conciliation` cobre tanto o "ainda não pago" quanto o "parcialmente pago"; `paid` só aparece quando o acumulado cobre o esperado dentro da tolerância. ## Próximos passos Siga para o [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md) para ver o fluxo passo a passo. Para o cenário em que uma nova operação recompra amortizações extraordinárias em aberto, veja [Amortização com Recompra](./recompra-de-operacao.md). --- # Consultar Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao Este endpoint retorna uma amortização extraordinária específica pela sua chave (`extraordinary_event_conciliation_key`). Use-o para acompanhar o status da conciliação do evento — desde `pending_conciliation` (ainda não pago ou parcialmente pago) até o estado terminal (`paid` ou `canceled`) definido pela orquestração interna da QI Tech. A consulta é agnóstica de data e não dispara nenhuma transição de status: apenas reflete o estado atual do evento e de cada parcela vinculada. --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event/ EXTRAORDINARY-EVENT-CONCILIATION-KEY MÉTODO GET ### **Path Params** | Campo | Tipo | Obrigatório | Descrição | |----------------------------------------|---------------|-------------|---------------------------------------------------------------------------| | `extraordinary_event_conciliation_key` | string (UUID) | Sim | Chave única do evento extraordinário de amortização a consultar. | Exemplo de chamada: ``` GET /event_conciliation/extraordinary_event/11111111-1111-4111-8111-111111111111 ``` --- ## **Response** STATUS 200 Response Body ```json { "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111", "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "44444444-4444-4444-8444-444444444444", "amortization_type": "early_amortization", "total_expected_amount": 1500.00, "total_discount_amount": 0, "total_paid_amount": 0.0, "status": "pending_conciliation", "reference_date": "2026-04-24", "due_date": "2026-04-24", "paid_at": null, "event_conciliation_list": [ { "event_conciliation_key": "22222222-2222-4222-8222-222222222222", "installment_key": "33333333-3333-4333-8333-333333333333", "event_conciliation_status": "pending_conciliation", "event_conciliation_type": "extraordinary_event" } ] } ``` ### **Response Body Params** | Campo | Tipo | Descrição | |----------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key` | string (UUID) | Chave do evento extraordinário de amortização consultado. | | `security_key` | string (UUID) | Chave do ativo (`security`) ao qual o evento pertence. | | `investment_key` | string (UUID) | Chave do investimento alvo do evento. | | `amortization_type` | string | Tipo de amortização do evento — ecoa o valor usado na criação. | | `total_expected_amount` | number | Valor total esperado do evento (soma distribuída entre as parcelas) em BRL. | | `total_discount_amount` | number | Desconto total aplicado. Diferente de zero apenas para `present_amount`. | | `total_paid_amount` | number | Valor já conciliado para o evento (em BRL). `0` enquanto nenhum pagamento foi confirmado; `> 0` em pagamento parcial. | | `status` | string | Status atual do evento: `pending_conciliation`, `paid` ou `canceled`. | | `reference_date` | string (date) | Data de referência informada na criação. | | `due_date` | string (date) | Data alvo de liquidação informada na criação. | | `paid_at` | string (date) | Data em que o evento foi liquidado. `null` enquanto não estiver `paid`. | | `event_conciliation_list` | array | Lista de `event_conciliation` (evento de conciliação de cada parcela) do evento. **[Objeto event_conciliation_list](#objeto-event_conciliation_list)**. | ### **Objeto event_conciliation_list** | Campo | Tipo | Descrição | |-----------------------------|-----------------|-------------------------------------------------------------------------------------------| | `event_conciliation_key` | string (UUID) | Chave do evento de conciliação da parcela (`event_conciliation`). | | `installment_key` | string (UUID) | Chave da parcela afetada por este evento de conciliação. | | `event_conciliation_status` | string | Status atual do evento de conciliação da parcela (`pending_conciliation`, `paid`, `canceled`). | | `event_conciliation_type` | string | Tipo do `event_conciliation`. Sempre `extraordinary_event` para eventos criados por este fluxo. | :::info O `status` (e o `event_conciliation_status` de cada parcela) reflete o estado atual no momento da consulta. A transição para `paid` ou `canceled` é feita pela orquestração interna da QI Tech — o integrador não precisa acionar nenhum endpoint para isso. ::: --- ## **Erros** | Código | HTTP | Significado | |------------|------|--------------------------------------------------------------------------------------------------------| | EVC100011 | 404 | Nenhuma amortização extraordinária encontrada para a `extraordinary_event_conciliation_key` informada. | Consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) para resolução completa. --- ## **Veja também** - [Criar Amortização Extraordinária](./criar-amortizacao.md) - [Simular Valor Presente da Amortização Extraordinária](./simular-valor-presente.md) - [Conceito](../conceito.md) - [Roteiro de Integração](../../roteiro-integracao/roteiro-integracao-padrao.md) - [Regras de Negócio](../regras-de-negocio.md) - [Exemplos](../exemplos.md) --- # Criar Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao Este endpoint cria uma amortização extraordinária sobre um ou mais `installment` de uma emissão. O event-conciliation-service agrupa as parcelas em um evento extraordinário de amortização único, distribui o `amount` declarado conforme o `amortization_type` informado e obtém o Valor Presente via security-service — o integrador não calcula Valor Presente no seu lado. A `reference_date` é fornecida pelo chamador na requisição da amortização extraordinária e é a única referência temporal usada pelo serviço na classificação de vencidos e no desconto pro-rata. --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event MÉTODO POST ### **Request Body** `installment_list` (array de `installment_number`, inteiros ≥ 1) é obrigatório para todos os tipos: ele define as parcelas-alvo e o `amortization_type` define como o `amount` é distribuído entre elas. Os números enviados em `installment_list` são resolvidos pelo serviço contra `installment_number` da `security` correspondente. Exemplo — `early_amortization` (uma parcela futura): ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "early_amortization", "amount": 1500.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [1] } ``` Exemplo — `equal_amount` (proporcional entre as parcelas selecionadas): ```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] } ``` Exemplo — `nominal_amount` (parcelas futuras pelo valor nominal): ```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** | Campo | Tipo | Obrigatório | Descrição | |---------------------------|-----------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | Sim | Chave única do ativo (`security`) sobre o qual a amortização será aplicada. | | `investment_key` | string (UUID) | Sim | Chave do investimento alvo. Usado pelo security-service como base proporcional no cálculo de Valor Presente. | | `amortization_type` | string | Sim | Estratégia de distribuição. Valores: `equal_amount`, `first_installments`, `present_amount`, `matured_installments`, `early_amortization`, `nominal_amount`, `full_amortization`. | | `amount` | number | Sim | Valor total a ser amortizado (em BRL). Distribuído entre as parcelas selecionadas conforme o `amortization_type`. | | `reference_date` | string (date) | Sim | Data de referência em formato `YYYY-MM-DD`. **Fornecida pelo chamador** — o serviço a usa como "hoje" para classificar parcelas vencidas e aplicar o desconto pro-rata do Valor Presente. | | `due_date` | string (date) | Sim | Data alvo de liquidação (tipicamente igual à `reference_date`). | | `installment_list` | array de inteiros (≥ 1) | Sim | Lista de `installment_number` (não UUIDs) das parcelas-alvo, com `minItems: 1`. Obrigatório para todos os tipos — omitir retorna `EVC100002`. O serviço resolve cada número contra `installment_number` da `security`; números inexistentes retornam `EVC000007`. O legado `installment_key_list` foi removido — clientes que ainda enviarem o campo recebem `QIT000001` (400). | | `total_discount` | number | Não | Utilizado apenas com `present_amount` — distribui o desconto na ordem juros → multa → principal. | | `number_of_installments` | integer | Condicional | Obrigatório com `first_installments`: quantas das parcelas selecionadas, em ordem de vencimento, recebem o valor. | --- ## **Response** STATUS 201 Response Body ```json { "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111", "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "amortization_type": "early_amortization", "total_expected_amount": 1500.00, "total_discount_amount": 0, "status": "pending_conciliation", "reference_date": "2026-04-24", "due_date": "2026-04-24", "event_conciliation_list": [ { "event_conciliation_key": "22222222-2222-4222-8222-222222222222", "installment_key": "33333333-3333-4333-8333-333333333333", "expected_amount": 1500.00, "discount_amount": 0, "due_date": "2026-04-24", "status": "pending_conciliation", "event_conciliation_type": "extraordinary" } ] } ``` ### **Response Body Params** | Campo | Tipo | Descrição | |---------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key`| string (UUID) | Chave do evento geral de amortização extraordinário criado. | | `security_key` | string (UUID) | Chave do ativo — ecoa o valor enviado. | | `amortization_type` | string | Tipo de amortização escolhido — ecoa o valor enviado. | | `total_expected_amount` | number | Soma distribuída entre os `event_conciliation` (eventos de conciliação da parcela) pelo engine do tipo escolhido. | | `total_discount_amount` | number | Desconto total aplicado. Diferente de zero apenas para `present_amount`. | | `status` | string | Status inicial do evento extraordinário. Sempre `pending_conciliation` ao criar. | | `reference_date` | string (date) | Data de referência enviada na requisição (deve corresponder a data de quitação). | | `due_date` | string (date) | Data alvo de liquidação enviada na requisição. | | `event_conciliation_list` | array | Lista de `event_conciliation` (evento de conciliação da parcela) gerado. **[Objeto event_conciliation_list](#objeto-event_conciliation_list)**. | ### **Objeto event_conciliation_list** | Campo | Tipo | Descrição | |--------------------------|-----------------|-------------------------------------------------------------------------------------------| | `event_conciliation_key` | string (UUID) | Chave do evento de conciliação da parcela (`event_conciliation`). | | `installment_key` | string (UUID) | Chave da parcela afetada por este evento de conciliação. | | `expected_amount` | number | Valor atribuído a este evento de conciliação da parcela pela engine de distribuição. | | `discount_amount` | number | Parcela do `total_discount` alocada a este evento de conciliação da parcela (`present_amount`) ou diferença entre o Valor Presente da parcela e a cota recebida (`full_amortization`). | | `due_date` | string (date) | Data de vencimento da parcela associada. | | `status` | string | Status inicial do evento de conciliação da parcela. Sempre `pending_conciliation` ao criar. | | `event_conciliation_type`| string | Tipo do `event_conciliation`. Sempre `extraordinary` para eventos de conciliação da parcela criados por este fluxo. | --- ## **Erros** | Código | HTTP | Significado | |------------|------|--------------------------------------------------------------------------------------------------------| | EVC100001 | 400 | `amortization_type` inválido. Use um dos sete valores suportados. | | EVC100002 | 400 | `installment_list` é obrigatório (e não vazio) para todos os tipos de amortização. | | EVC100003 | 400 | `number_of_installments` é obrigatório para `first_installments`. | | EVC100004 | 400 | Alguma parcela informada não pertence à `security` alvo. | | EVC000007 | 404 | Algum inteiro em `installment_list` não corresponde a nenhum `installment_number` da `security` (`InstallmentNumberNotFound`). | | QIT000001 | 400 | Falha de schema — por exemplo, envio do legado `installment_key_list` (removido) ou item de `installment_list` que não é inteiro ≥ 1. | | EVC100005 | 400 | `amount` não cobre todas as parcelas selecionadas (não aplicável a `early_amortization`). | | EVC100006 | 400 | `total_discount` excede a soma do Valor Presente das parcelas selecionadas. | | EVC100007 | 400 | Para `matured_installments`, todas as parcelas selecionadas devem estar vencidas. | | EVC100008 | 400 | Já existe uma amortização extraordinária pendente para a parcela — cancele-a antes de criar outra. | | EVC100013 | 424 | Security API indisponível (Failed Dependency). Transitório — repita após o restabelecimento. | | EVC100015 | 400 | `early_amortization` requer exatamente 1 parcela em `installment_list`. | | EVC100016 | 400 | A parcela alvo de `early_amortization` não pode estar vencida. | | EVC100017 | 400 | Em `early_amortization`, `amount` deve ser menor ou igual ao Valor Presente da parcela. | | EVC100030 | 400 | Em `nominal_amount`, todas as parcelas selecionadas devem ser futuras (não vencidas na `reference_date`). | | EVC100031 | 400 | Em `nominal_amount`, `amount` deve ser menor ou igual à soma dos valores nominais das parcelas selecionadas. | | EVC100032 | 400 | Nenhuma parcela selecionada receberia `expected_amount` positivo — o evento não é criado. | | EVC100033 | 400 | A soma dos `expected_amount` distribuídos difere do `amount` informado em mais de R$ 0,01. | | EVC100034 | 400 | Alguma parcela selecionada ficaria com `expected_amount` zero — selecione apenas parcelas que o `amount` cubra. | | EVC100035 | 400 | `amount` excede a soma dos Valores Presentes das parcelas selecionadas (tipos precificados a Valor Presente). | Consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) para resolução completa. --- ## **Veja também** - [Simular Valor Presente da Amortização Extraordinária](./simular-valor-presente.md) - [Consultar Amortização Extraordinária](./consultar-amortizacao.md) - [Conceito](../conceito.md) - [Roteiro de Integração](../../roteiro-integracao/roteiro-integracao-padrao.md) - [Regras de Negócio](../regras-de-negocio.md) - [Exemplos](../exemplos.md) --- # Simular Valor Presente da Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente Este endpoint simula uma amortização extraordinária do tipo `present_amount` sem criar nenhum evento — é um cálculo puro, sem efeitos colaterais. A partir das parcelas informadas em `installment_list`, o serviço calcula e devolve o `amount` total (Valor Presente) do evento extraordinário que seria criado, além do Valor Presente de cada `event_conciliation` (tipo `extraordinary`) por parcela — o integrador não calcula Valor Presente no seu lado. O `amortization_type` não é enviado na requisição: por se tratar de uma simulação de Valor Presente, o tipo é sempre `present_amount`. O `amount` também não é enviado — ele é o resultado do cálculo. A `reference_date` é fornecida pelo chamador e é a única referência temporal usada pelo serviço na classificação de vencidos e no desconto pro-rata; na simulação, a `due_date` é assumida igual à `reference_date`. O response é o payload de criação pronto para uso: basta remover o campo `event_conciliation_list` — que é apenas informativo — e enviá-lo como body do [Criar Amortização Extraordinária](./criar-amortizacao.md) para efetivar a amortização simulada. --- ## **Request** ENDPOINT /event_conciliation/extraordinary_event/present_value_simulation MÉTODO POST ### **Request Body** ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "reference_date": "2026-04-24", "installment_list": [1, 2] } ``` ### **Request Body Params** | Campo | Tipo | Obrigatório | Descrição | |--------------------|-------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | Sim | Chave única do ativo (`security`) sobre o qual a amortização será simulada. | | `investment_key` | string (UUID) | Sim | Chave do investimento alvo. Usada como base proporcional no cálculo do Valor Presente. | | `reference_date` | string (date) | Sim | Data de referência em formato `YYYY-MM-DD`. **Fornecida pelo chamador** — o serviço a usa como "hoje" para classificar parcelas vencidas e aplicar o desconto pro-rata do Valor Presente. Na simulação, também é usada como `due_date`. | | `installment_list` | array de inteiros (≥ 1) | Sim | Lista de `installment_number` (não UUIDs) das parcelas-alvo, com `minItems: 1`. O serviço resolve cada número contra `installment_number` da `security`; números inexistentes retornam `EVC000007`. | Diferente da criação, `amortization_type`, `amount` e `due_date` **não são enviados**: o tipo é sempre `present_amount`, o `amount` é calculado pelo serviço e a `due_date` é assumida igual à `reference_date`. --- ## **Response** STATUS 200 Response Body ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "present_amount", "amount": 4750.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [1, 2], "event_conciliation_list": [ { "installment_number": 1, "amount": 2400.00 }, { "installment_number": 2, "amount": 2350.00 } ] } ``` ### **Response Body Params** | Campo | Tipo | Descrição | |---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `security_key` | string (UUID) | Chave do ativo — ecoa o valor enviado. | | `investment_key` | string (UUID) | Chave do investimento alvo — ecoa o valor enviado. | | `amortization_type` | string | Sempre `present_amount` — preenchido pelo serviço para compor o payload de criação. | | `amount` | number | Valor Presente total calculado para o evento extraordinário (soma dos `amount` de `event_conciliation_list`). | | `reference_date` | string (date) | Data de referência — ecoa o valor enviado. | | `due_date` | string (date) | Data alvo de liquidação — igual à `reference_date` enviada. | | `installment_list` | array de inteiros | Parcelas-alvo — ecoa o valor enviado. | | `event_conciliation_list` | array | Valor Presente por parcela dos `event_conciliation` (tipo `extraordinary`) que seriam gerados. **Apenas para visualização — não entra no payload de criação.** **[Objeto event_conciliation_list](#objeto-event_conciliation_list)**. | :::info O campo `event_conciliation_list` é **apenas para visualização** da simulação de cada parcela — ele **não deve ser incluído** no payload de criação do evento extraordinário. Para efetivar a amortização simulada, envie o response **sem** `event_conciliation_list` como body do [Criar Amortização Extraordinária](./criar-amortizacao.md). ::: ### **Objeto event_conciliation_list** | Campo | Tipo | Descrição | |----------------------|---------|----------------------------------------------------------------------------------------------------------| | `installment_number` | integer | Número da parcela (`installment_number`) a que este evento de conciliação se refere. | | `amount` | number | Valor Presente calculado para o `event_conciliation` (tipo `extraordinary`) desta parcela. | --- ## **Erros** | Código | HTTP | Significado | |------------|------|----------------------------------------------------------------------------------------------------------------------------------------| | EVC100002 | 400 | `installment_list` é obrigatório e não pode ser vazio. | | EVC100004 | 400 | Alguma parcela informada não pertence à `security` alvo. | | EVC000007 | 404 | Algum inteiro em `installment_list` não corresponde a nenhum `installment_number` da `security` (`InstallmentNumberNotFound`). | | QIT000001 | 400 | Falha de schema — por exemplo, item de `installment_list` que não é inteiro ≥ 1. | | EVC100008 | 400 | Já existe uma amortização extraordinária pendente para a parcela — cancele-a antes de simular/criar outra. | | EVC100013 | 424 | Dependência temporariamente indisponível (Failed Dependency). Transitório — repita após o restabelecimento. | O `EVC100005` (`amount` insuficiente) não se aplica à simulação — o `amount` é calculado pelo serviço, não enviado. Consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) para resolução completa. --- ## **Veja também** - [Criar Amortização Extraordinária](./criar-amortizacao.md) - [Consultar Amortização Extraordinária](./consultar-amortizacao.md) - [Conceito](../conceito.md) - [Roteiro de Integração](../../roteiro-integracao/roteiro-integracao-padrao.md) - [Regras de Negócio](../regras-de-negocio.md) - [Exemplos](../exemplos.md) --- # Exemplos — Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/exemplos Esta página apresenta dois cenários de criação. A interação do integrador é **fire-and-forget**: realiza apenas a chamada de criação e a QI Tech orquestra liquidação, finalização e cancelamento internamente. Não há webhook tenant-facing dedicado às transições de status do `event_conciliation` extraordinário; a confirmação do efeito da operação é observada via os relatórios e webhooks já existentes para a operação subjacente (ex.: `commercial_paper.operation_status_change`). ## Cenário 1: quitação antecipada parcial de uma parcela (early_amortization) Cobre uma única parcela futura, com pagamento parcial permitido. `POST /event_conciliation/extraordinary_event` ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "early_amortization", "amount": 1500.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [3] } ``` Resposta: `201 Created` ```json { "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111", "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "amortization_type": "early_amortization", "total_expected_amount": 1500.00, "total_discount_amount": 0, "status": "pending_conciliation", "reference_date": "2026-04-24", "due_date": "2026-04-24", "event_conciliation_list": [ { "event_conciliation_key": "22222222-2222-4222-8222-222222222222", "installment_key": "33333333-3333-4333-8333-333333333333", "expected_amount": 1500.00, "discount_amount": 0, "due_date": "2026-04-24", "status": "pending_conciliation", "event_conciliation_type": "extraordinary" } ] } ``` A partir desse 201 a integração está concluída do lado do integrador. Quando o pagamento de R$ 1.500,00 atingir a conta de liquidação correspondente, a QI Tech (account-liquidation-api) liquida o evento de conciliação da parcela internamente e atualiza o `paid_amount`; quando a soma cobre `total_expected_amount - tolerance_amount`, o parent transita para `paid`. Se o pagamento não entrar, o evento é cancelado ou finalizado pela rotina diária de settlement do security-service. ## Cenário 2: quitação total com desconto (present_amount com 2 installments) Cria uma amortização com desconto consolidado cobrindo duas parcelas. `POST /event_conciliation/extraordinary_event` ```json { "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e", "investment_key": "", "amortization_type": "present_amount", "amount": 5000.00, "reference_date": "2026-04-24", "due_date": "2026-04-24", "installment_list": [1, 2], "total_discount": 100.00 } ``` Resposta `201 Created` — dois eventos de conciliação da parcela são gerados com os valores distribuídos conforme o engine de `present_amount` (juros → multa → principal). Veja [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md) para o shape completo da resposta. A partir do 201 a interação do integrador é a mesma do Cenário 1: a QI Tech liquida cada evento de conciliação da parcela quando os pagamentos correspondentes entram, e finaliza ou cancela o evento internamente caso os valores não cheguem dentro da janela de settlement. ## Cenário 3: quitação de parcelas futuras pelo valor nominal (nominal_amount) Emissor quer quitar as parcelas 3 e 4 antes do vencimento pagando o valor nominal de cada uma (principal + juros no vencimento), sem desconto a Valor Presente. A `reference_date` é anterior ao vencimento de ambas. ```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] } ``` Resposta `201 Created` — um evento de conciliação da parcela por parcela, com `expected_amount` igual ao valor nominal de cada uma (`9360.00` e `9310.00` neste exemplo). Se o `amount` fosse menor que a soma, a parcela 3 seria coberta primeiro e a parcela 4 receberia o restante. Parcelas vencidas retornam `EVC100030`; `amount` acima da soma dos valores nominais retorna `EVC100031`. A liquidação aceita pagamento parcial, como em `early_amortization`. ## Cenário 4: quitação integral com valor negociado (full_amortization) Emissor e investidor acordam quitar as parcelas 1 e 2 por R$ 10.000,00, embora os Valores Presentes na `reference_date` sejam R$ 9.460,00 e R$ 9.410,00. O `amount` é rateado proporcionalmente ao Valor Presente e cada parcela é quitada integralmente na liquidação. ```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] } ``` Resposta `201 Created` — dois eventos de conciliação da parcela com `expected_amount` `5013.25` e `4986.75` (a soma é igual ao `amount`) e `discount_amount` `4446.75` e `4423.25`. Um `amount` acima da soma dos Valores Presentes retorna `EVC100035`; um `amount` pequeno demais para dar cota positiva a todas as parcelas retorna `EVC100034`. ## Troubleshooting Códigos de erro mais comuns ao chamar a criação. Para a lista completa, consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). - **`EVC100015`** (400, EarlyAmortizationRequiresSingleInstallment) — `early_amortization` aceita exatamente uma parcela em `installment_list`. Reduza para 1. - **`EVC000007`** (404, InstallmentNumberNotFound) — algum `installment_number` enviado em `installment_list` não existe na `security` alvo. Confira os números retornados em `GET /security/security/{security_key}` antes de chamar. - **`QIT000001`** (400) — schema rejeitado. Causa típica: enviar o campo legado `installment_key_list` (removido) ou itens não inteiros em `installment_list`. - **`EVC100016`** (400, EarlyAmortizationInstallmentOverdue) — a parcela alvo de `early_amortization` está vencida e não é elegível. Selecione uma parcela futura. - **`EVC100017`** (400, EarlyAmortizationAmountExceedsPresentValue) — em `early_amortization`, o `amount` excedeu o Valor Presente da parcela. Confirme o PV antes de chamar. - **`EVC100030`** (400, InstallmentNotEligibleForNominalAmortization) — em `nominal_amount`, alguma parcela de `installment_list` já está vencida na `reference_date`. Selecione apenas parcelas futuras. - **`EVC100031`** (400, NominalAmountExceedsInstallmentsNominalValue) — em `nominal_amount`, o `amount` excedeu a soma dos valores nominais (principal + juros) das parcelas selecionadas. Reduza o `amount`. - **`EVC100033`** (400, DistributionDoesNotMatchAmount) — a soma dos `expected_amount` distribuídos difere do `amount` informado em mais de R$ 0,01. Em `present_amount`, envie `amount` igual à soma dos Valores Presentes menos o `total_discount`. - **`EVC100034`** (400, DistributionWithZeroInstallment) — alguma parcela selecionada ficaria com `expected_amount` zero (por exemplo, `total_discount` igual ao Valor Presente, ou `amount` que se esgota antes da última parcela). Selecione apenas parcelas que o `amount` cubra. - **`EVC100035`** (400, AmountExceedsInstallmentsPresentValue) — o `amount` excede a soma dos Valores Presentes das parcelas selecionadas. Reduza o `amount`. - **`EVC100013`** (424, SecurityApiUnavailable) — Security API temporariamente indisponível ao buscar o Valor Presente; é transitório. Aguarde e repita a chamada. - **`SEC000031`** (400, PostFixedSecurityNotSupported) — ativos pós-fixados (CDI, IPCA, IGPM) não são suportados na V1. Use ativos `pre_price` ou `pre_sac`. ## Veja também - [Conceito](./conceito.md) - [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md) - [Regras de Negócio](./regras-de-negocio.md) - [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md) - [Consultar Amortização Extraordinária](./endpoints/consultar-amortizacao.md) - [Recompra de Operação](./recompra-de-operacao.md) - [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Amortização com Recompra URL: /documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao ## Visão geral A **recompra** é o fluxo em que uma **nova operação** de nota comercial é emitida para "recomprar" uma ou mais amortizações extraordinárias em aberto de uma operação existente. O cenário típico: o devedor tem uma operação em aberto e, junto com o investidor, decide recomprá-la — por refinanciamento ou por qualquer outro motivo negociado. Em vez de quitar a dívida com recursos próprios, eles estruturam uma nova operação cujo desembolso liquida automaticamente as amortizações extraordinárias escolhidas. A nova operação é emitida pelo **mesmo devedor** (`issuer`) dos eventos que estão sendo recomprados. A recompra pode abranger: - **Uma única amortização extraordinária** — o caso mais comum, recomprando uma operação. - **Múltiplos ativos** — passando várias `extraordinary_event_conciliation_key`, inclusive de `security` diferentes, quando o devedor quer recomprar mais de um ativo na mesma nova operação. A recompra não é uma chamada de API separada: ela é declarada **no momento da criação da nova operação**, informando a lista de chaves dos eventos extraordinários a recomprar. ## Pré-requisito Cada amortização extraordinária a ser recomprada precisa **já existir** — criada previamente pelo fluxo de [amortização extraordinária](./endpoints/criar-amortizacao.md) — e estar em `pending_conciliation` no momento em que a nova operação é criada. São essas chaves (`extraordinary_event_conciliation_key`) que você referencia na recompra. :::warning Datas precisam casar com o desembolso A `reference_date` e a `due_date` informadas **na criação do evento extraordinário** precisam corresponder à **data de desembolso** da nova operação de recompra. Se essas datas não baterem com o desembolso, os eventos **não são desembolsados corretamente e são cancelados automaticamente** — a recompra não se efetiva. Planeje a `reference_date`/`due_date` do evento extraordinário já considerando quando a nova operação será desembolsada. ::: ## Como acionar A recompra é declarada no [Cadastro de Operação de Nota Comercial](../emissao-de-notas/cadastro-operacao/criar-operacao.md) (`POST /commercial_paper/operation`): basta enviar, junto com os campos normais de criação da operação, o campo `extraordinary_event_conciliation_key_list` com as chaves dos eventos extraordinários que deseja recomprar. ```json { "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_bank_account": { "account_number": "4464541", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" }, "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "issue_date": "2025-01-23", "financial": { "interest_type": "pre_price_days", "financial_base_date": "2025-01-23", "released_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee" } ] }, "extraordinary_event_conciliation_key_list": [ "11111111-1111-4111-8111-111111111111" ] } ``` O `extraordinary_event_conciliation_key_list` é o **único** acréscimo em relação ao cadastro de operação comum — todos os demais campos seguem o [contrato de criação de operação](../emissao-de-notas/cadastro-operacao/criar-operacao.md). Consulte aquela página para a referência completa de cada campo (`issuer_key`, `issuer_bank_account`, `investors`, `issue_date`, `financial`). ### Campo | Campo | Tipo | Obrigatório | Descrição | |--------------------------------------------|-------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| | `extraordinary_event_conciliation_key_list`| array de string (UUID) | Não | Lista de chaves das amortizações extraordinárias a recomprar. Itens únicos; uma chave por ativo recomprado. Pode abranger múltiplos `security`. Omita o campo em operações sem recompra. | ## Regra de valor O valor da nova operação precisa ser suficiente para cobrir o que está sendo recomprado. A regra aplicada na **criação da operação** é: > A soma do `expected_amount` de todos os eventos referenciados em `extraordinary_event_conciliation_key_list` deve ser **menor ou igual** ao `released_amount` da nova operação. Caso contrário, a criação é rejeitada com **`COM000050`** (400). :::info `released_amount` e fees `released_amount` é o **valor de emissão líquido de fees financiados**. Por isso, na prática, o valor de emissão da nova operação precisa cobrir no mínimo o valor dos eventos recomprados **+ fees** — só assim o `released_amount` resultante alcança a soma dos `expected_amount`. ::: ## Desembolso > **Orquestração interna.** A recompra propriamente dita acontece no desembolso da nova operação e é executada internamente pela QI Tech — o integrador **não chama** nenhum endpoint adicional nesta etapa. Ao desembolsar a nova operação: 1. As amortizações extraordinárias referenciadas são **liquidadas automaticamente**, transitando de `pending_conciliation` para `paid`. 2. O **restante** — `released_amount − Σ expected_amount`, quando positivo — é **repassado ao devedor**. Ou seja, parte do desembolso quita os eventos recomprados e o que sobra vai para o devedor, em uma única operação. ## Veja também - [Conceito](./conceito.md) - [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md) - [Consultar Amortização Extraordinária](./endpoints/consultar-amortizacao.md) - [Regras de Negócio](./regras-de-negocio.md) - [Exemplos](./exemplos.md) - [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md) - [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Regras de Negócio — Amortização Extraordinária URL: /documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio Esta página consolida as invariantes que governam a criação, a liquidação e o cancelamento de uma amortização extraordinária. Consulte-a sempre que as páginas de endpoints citarem um código de erro, um campo ou uma condição que precise de contexto adicional. ## Data de referência (`reference_date`) A `reference_date` é **fornecida pelo chamador** na requisição de criação e é a única referência temporal usada pelo serviço — o sistema **nunca usa** `date.today()`. Toda lógica dependente de data (classificação de parcelas vencidas, desconto pro-rata do Valor Presente, seleção de parcelas elegíveis para `early_amortization` e `nominal_amount`) parte desse campo. A consulta de Valor Presente ao security-service recebe essa mesma `reference_date`. ## Tipos de amortização Os 7 tipos suportados e como cada um distribui o `amount` entre as parcelas de `installment_list`: | Tipo | Regra de distribuição entre as parcelas selecionadas | Permite pagamento parcial | |------------------------|----------------------------------------------------------------------------------------------------|---------------------------| | `equal_amount` | Proporcional ao Valor Presente, vencidas primeiro e depois futuras | Não | | `first_installments` | Sequencial nas N primeiras parcelas selecionadas (por vencimento), N = `number_of_installments` | Não | | `present_amount` | Explícita por parcela; desconto ordena juros → multa → principal | Não | | `matured_installments` | Apenas parcelas já vencidas, em ordem de vencimento | Não | | `early_amortization` | Uma única parcela futura, até o Valor Presente | **Sim** | | `nominal_amount` | Parcelas futuras pelo valor nominal (principal + juros), em ordem de vencimento, sem Valor Presente | **Sim** | | `full_amortization` | Proporcional ao Valor Presente entre todas as parcelas selecionadas, sem cascata; cada parcela é quitada integralmente | Não | `installment_list` (array de `installment_number` inteiros) é **obrigatório para todos os tipos** — omiti-lo retorna `EVC100002`. O serviço resolve cada `installment_number` para a parcela correspondente da `security` e consulta o Valor Presente por parcela selecionada; o `amortization_type` define apenas como o `amount` é distribuído entre essas parcelas. ## Amortização antecipada (`early_amortization`) `early_amortization` permite pagamento parcial (assim como `nominal_amount`). Todas as seguintes condições se aplicam: - Exatamente **1** parcela em `installment_list` — caso contrário, `EVC100015`. - A parcela-alvo **não pode estar vencida** — caso contrário, `EVC100016`. - O `amount` deve ser **≤ Valor Presente** da parcela — caso contrário, `EVC100017`. - **Pagamento parcial é permitido.** O estado `paid_amount > 0 AND paid_amount = total_expected_amount - tolerance_amount`. ## Amortização pelo valor nominal (`nominal_amount`) `nominal_amount` quita parcelas futuras pelo valor nominal — principal mais juros no vencimento — sem trazê-las ao Valor Presente da `reference_date`. Todas as seguintes condições se aplicam: - Todas as parcelas em `installment_list` devem ter `due_date` maior ou igual à `reference_date` — parcela vencida retorna `EVC100030`. - O `amount` é distribuído em ordem de vencimento, cobrindo cada parcela pelo valor nominal até se esgotar; a última parcela alcançada pode receber valor parcial. - O `amount` deve ser **≤ soma dos valores nominais** das parcelas selecionadas — caso contrário, `EVC100031`. - **Pagamento parcial é permitido** na liquidação, com o mesmo estado derivado descrito para `early_amortization`. ## Amortização integral (`full_amortization`) `full_amortization` usa o `amount` informado para quitar **todas** as parcelas de `installment_list`, independentemente do Valor Presente de cada uma: - O `amount` é rateado entre as parcelas proporcionalmente ao Valor Presente na `reference_date`, sem cascata — nenhuma parcela fica sem cota. - Cada `event_conciliation` nasce com `expected_amount` igual à sua cota e `discount_amount` igual à diferença entre o Valor Presente e a cota. - O `amount` não pode exceder a soma dos Valores Presentes das parcelas selecionadas — caso contrário, `EVC100035`. - Na liquidação, o pagamento da cota dá baixa **integral** na parcela no security-service: o valor pago é registrado como pago e a diferença como desconto da parcela. O mesmo vale para `present_amount`. ## Consistência entre `amount` e a distribuição Após distribuir o `amount`, o serviço valida o resultado para **todos** os tipos, nesta ordem: 1. `amount` maior que a soma dos Valores Presentes das parcelas distribuídas → `EVC100035` (tipos precificados a Valor Presente; `early_amortization` e `nominal_amount` mantêm `EVC100017` e `EVC100031`). 2. Alguma parcela selecionada ficaria com `expected_amount` igual a zero → `EVC100034`. Nenhum evento é criado com filhos zerados; selecione apenas parcelas que o `amount` cubra. 3. A soma dos `expected_amount` distribuídos difere do `amount` em mais de R$ 0,01 → `EVC100033`. Em `present_amount`, o `amount` precisa ser igual à soma dos Valores Presentes menos o `total_discount`. Os `expected_amount` são gravados em centavos, com o resíduo de arredondamento na última parcela, de modo que `total_expected_amount` do evento seja sempre igual à soma dos filhos. ## Fluxo de liquidação > **Orquestração interna.** A liquidação dos eventos extraordinários é executada pela QI Tech (account-liquidation-api) ao detectar o pagamento — o integrador **não chama** nenhum endpoint nesta etapa, nem recebe webhook dedicado às transições de status. As regras abaixo descrevem o comportamento interno para você entender o que ocorre após a criação. **Liquidação ordinária emite o total completo (regra 4).** A liquidação ordinária na `due_date` continua emitindo o `total_amount` completo da parcela via SQS; não há subtração do `paid_amount`. O evento reconcilia o estado parcial-pago no seu próprio engine de `early_amortization`. ## Cancelamento e finalização > **Orquestração interna.** Cancelamento e finalização são disparados por uma rotina diária e — o integrador **não chama** nenhum endpoint para cancelar ou finalizar uma amortização extraordinária, e não há webhook tenant-facing dedicado a essas transições. A descrição abaixo é informativa. ## Veja também - [Conceito](./conceito.md) - [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md) - [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md) - [Consultar Amortização Extraordinária](./endpoints/consultar-amortizacao.md) - [Recompra de Operação](./recompra-de-operacao.md) - [Exemplos](./exemplos.md) - [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) --- # Catálogo de Erros URL: /documentation/escrituracao/catalogo-erros/catalogo-erros ## Formatação dos erros Todas APIs da integração de escrituração retornam os erros de API formatados segundo a descrição a seguir: Error Response Body ```json { "title": "HTTP Status code name", "description": "An english description of the error", "translation": "Uma descrição em português do erro", "code": "ERROR_UNIQUE_CODE" } ``` --- ## Tabela de erros possíveis no processo de homologação do emissor | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | ISS000003 | Bad Request | Issuer already exists in database. | Emissor já existe na base de dados. | | 404 | ISS000004 | Not Found | Issuer representative not found. | Representante do emissor não encontrado. | | 404 | ISS000005 | Not Found | Bank account not found. | Conta bancária não encontrada. | | 404 | ISS000006 | Not Found | Issuer document not found. | Documento do emissor não encontrado. | | 404 | ISS000007 | Not Found | Issuer representative document not found. | Documento do representante do emissor não encontrado. | | 404 | ISS000008 | Not Found | Issuer contact information not found. | Contato do emissor não encontrado. | | 404 | ISS000009 | Not Found | Issuer not found. | Emissor não encontrado. | | 404 | ISS0000010 | Not Found | Signer Group not found. | Grupo de assinantes não encontrado. | | 400 | ISS0000011 | Bad Request | Issuer must be in status in_filling to allow this action. | Emissor deve estar no estado in_filling para permitir esta ação. | | 400 | ISS0000018 | Bad Request | Document sent is invalid or quality is low. | Documento enviado é inválido ou de baixa qualidade. | | 400 | ISS0000012 | Bad Request | Deleting the main account is not allowed, please set a new main account first. | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. | | 400 | ISS0000013 | Bad Request | Deleting the main contact is not allowed, please set a new main contact first. | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. | | 400 | ISS0000014 | Bad Request | Issuer must have at least one contact information. | Emissor precisa ter ao menos uma informação de contato. | | 400 | ISS0000015 | Bad Request | Tenant already has access to this issuer. | Acesso aos dados do emissor já foi concedido. | | 400 | ISS0000016 | Bad Request | Failed trying to contact issuer, please retry. | Falha ao enviar mensagem ao emissor, tente novamente. | | 400 | ISS0000017 | Bad Request | Invalid link. | Link inválido. | | 400 | ISS0000025 | Bad Request | The file of the following documents is no longer stored and must be sent again: `{documents}`. | O arquivo dos seguintes documentos não está mais armazenado e precisa ser reenviado: `{documents}`. | | 404 | ISS0000028 | Not Found | Issuer auto signature not found. | Autoassinatura do emissor não encontrada. | | 409 | ISS0000029 | Conflict | Issuer already has an active auto signature. | Emissor já possui uma autoassinatura ativa. | | 400 | ISS0000030 | Bad Request | Issuer auto signature is not in a status that allows this operation. | A autoassinatura do emissor não está em um status que permite esta operação. | | 400 | ISS0000032 | Bad Request | Issuer must be approved to allow this action. | Emissor deve estar aprovado para permitir esta ação. | | 400 | ISS0000033 | Bad Request | Tenant is not enabled for auto signature. | Tenant não está habilitado para autoassinatura. | ## Tabela de erros possíveis no processo de homologação do investidor | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | INV000003 | Bad Request | Investor already exists in database. | Emissor já existe na base de dados. | | 404 | INV000004 | Not Found | Investor representative not found. | Representante do emissor não encontrado. | | 404 | INV000005 | Not Found | Bank account not found. | Conta bancária não encontrada. | | 404 | INV000006 | Not Found | Investor document not found. | Documento do emissor não encontrado. | | 404 | INV000007 | Not Found | Investor representative document not found. | Documento do representante do emissor não encontrado. | | 404 | INV000008 | Not Found | Investor contact information not found. | Contato do emissor não encontrado. | | 404 | INV000009 | Not Found | Investor not found. | Emissor não encontrado. | | 404 | INV0000010 | Not Found | Signer Group not found. | Grupo de assinantes não encontrado. | | 400 | INV0000011 | Bad Request | Investor must be in status in_filling to allow this action. | Emissor deve estar no estado in_filling para permitir esta ação. | | 400 | INV0000018 | Bad Request | Document sent is invalid or quality is low. | Documento enviado é inválido ou de baixa qualidade. | | 400 | INV0000012 | Bad Request | Deleting the main account is not allowed, please set a new main account first. | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. | | 400 | INV0000013 | Bad Request | Deleting the main contact is not allowed, please set a new main contact first. | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. | | 400 | INV0000014 | Bad Request | Investor must have at least one contact information. | Emissor precisa ter ao menos uma informação de contato. | | 400 | INV0000015 | Bad Request | Tenant already has access to this investor. | Acesso aos dados do emissor já foi concedido. | | 400 | INV0000016 | Bad Request | Failed trying to contact investor, please retry. | Falha ao enviar mensagem ao emissor, tente novamente. | | 400 | INV0000017 | Bad Request | Invalid link. | Link inválido. | ## Tabela de erros possíveis no processo de emissão da nota comercial | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | COM000001 | Bad Request | Document is not valid. | Documento fornecido não é válido. | | 400 | COM000002 | Bad Request | Tenant must be configured before use this endpoint. | Tenant precisa ser configurado antes de utilizar este endpoint. | | 409 | COM000003 | Conflict | Tenant configuration already exists. | Configuração para este tenant já existe. | | 400 | COM000004 | Bad Request | Investor with key (investor_key) is not allowed. Please check. | Investidor com a chave (investor_key) não permitido. Cheque o cadastro. | | 400 | COM000005 | Bad Request | Issuer with key (issuer_key) is not allowed. Please check. | Emissor com a chave (issuer_key) não permitido. Cheque o cadastro. | | 400 | COM000006 | Bad Request | Operation with more than one investor functionality not available yet. | Operação com mais de um investidor não disponível ainda. | | 404 | COM000007 | Not Found | Operation (operation_key) not found. | Operação (operation_key) não encontrada. | | 403 | COM000008 | Forbidden | Operation (operation_key) does not belong to tenant. | Operação (operation_key) não pertence ao tenant. | | 400 | COM000010 | Bad Request | Operations cannot be updated outside of in_filling status. | Operação não pode ser atualizada fora do status in_filling. | | 404 | COM000011 | Not Found | Related party not found. | Parte relacionada não encontrada. | | 400 | COM000012 | Bad Request | Related party (related_party_key) is not associated with operation (operation_key). | A parte relacionada (related_party_key) não está associada com a operação (operation_key). | | 404 | COM000013 | Not Found | Signer Group not found. | Grupo de assinantes não encontrado. | | 400 | COM000014 | Bad Request | Signer group (signer_group_key) is not associated with related party (related_party_key). | O grupo de assinantes (signer_group_key) não está associado com a parte relacionada (related_party_key). | | 400 | COM000015 | Bad Request | Signer list does not match minimum required signers field. | Lista de assinantes não é compatível com o mínimo de assinantes enviado. | | 404 | COM000016 | Not Found | Document not found. | Documento não encontrado. | | 400 | COM000017 | Bad Request | Document (document_key) is not associated with related party (related_party_key). | O documento (document_key) não está associado com a parte relacionada (related_party_key). | | 400 | COM000018 | Bad Request | Document sent is invalid or quality is low. | Documento enviado é inválido ou de baixa qualidade. | | 400 | COM000019 | Bad Request | Delete issuer or investor is not allowed. | Não é possível deletar o emissor ou investidor. | | 400 | COM000020 | Bad Request | Operation is in a final status and cannot be modified. | Operação já está em um estado final e não pode ser atualizada. | | 400 | COM000021 | Bad Request | Operation is not in analysis. | Operação não está em análise. | | 400 | COM000022 | Bad Request | Document not signed yet. | Documento ainda não foi assinado. | | 400 | COM000023 | Bad Request | Document not available yet. | Documento ainda não foi gerado. | | 400 | COM000024 | Bad Request | Failed to send document to signature, please retry. | Falha ao enviar documento para assinatura, tente novamente. | | 404 | COM000025 | Not Found | Collateral not found. | Garantia não encontrada. | | 400 | COM000026 | Bad Request | Collateral (collateral_key) is not associated with operation (operation_key). | A garantia (collateral_key) não está associada com a operação (operation_key). | | 400 | COM000027 | Bad Request | Metadata not found. | Metadado não encontrado. | | 400 | COM000028 | Bad Request | Operation is canceled and cannot be modified. | Operação está cancelada e não pode ser atualizada. | | 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 | Tenant is not enabled for third-party disbursement. | 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. | | 409 | COM000068 | Conflict | Vehicle with chassis (chassis) is already marked and cannot be used as vehicle_stock collateral. | O veículo com chassi (chassis) já está gravado e não pode ser utilizado como garantia de estoque de veículos. | | 422 | COM000069 | Unprocessable Entity | Vehicle with chassis (chassis) could not be marked. | O veículo com chassi (chassis) não pôde ser gravado. | | 422 | COM000070 | Unprocessable Entity | Vehicles with chassis (chassis_list) are not eligible for marking. | Os veículos com chassi (chassis_list) não são elegíveis para gravação. | | 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. | ## Tabela de erros possíveis no processo de integralização de cotas | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (pt-BR) | |------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------| | 400 | INT000001 | Bad Request | Document is not valid. | Documento fornecido não é válido. | | 404 | INT000002 | Not Found | Integralization process (integralizaion_key) not found. | Processo de integralização (integralizaion_key) não encontrado. | | 403 | INT000003 | Forbidden | Integralization process (integralizaion_key) does not belong to tenant. | Processo de integralização (integralizaion_key) não pertence ao tenant. | | 404 | INT000004 | Not Found | Subscription (subscription_key) not found. | Subscrição (subscription_key) não encontrada. | | 400 | INT000005 | Bad Request | Subscription (subscription_key) is not associated with integralization process (integralizaion_key). | A subscrição (subscription_key) não está associada com o processo de integralização (integralizaion_key). | | 404 | INT000006 | Not Found | Subscription payment not found. | Pagamento de subscrição não encontrado. | | 400 | INT000007 | Bad Request | Subscription payment (subscription_payment_key) is not associated with subscription (subscription_key). | O pagamento de subscrição (subscription_payment_key) não está associado com a subscrição (subscription_key). | | 400 | INT000008 | Bad Request | Subscription payment already analyzed. | Pagamento de subscrição já foi analisado. | | 409 | INT000009 | Conflict | Integralization process for (operation_key) already exists. | Já existe um processo de integralização para a operação (operation_key). | | 400 | INT000010 | Bad Request | Subscripted quantity (subscripted_quantity) is bigger than the available quantity (available_quantity). | A quantidade de cotas subscritas (subscripted_quantity) é maior do que a quantidade disponível (available_quantity). | | 400 | INT000011 | Bad Request | Subscription is not waiting payment yet. | Subscrição ainda não está aguardando pagamento. | | 400 | INT000012 | Bad Request | Subscription is in a final state and cannot be canceled. | Subscrição já está em um status final e não pode ser cancelada. | | 400 | INT000013 | Bad Request | Subscription is not waiting payment yet. | Subscrição não está aguardando pagamento ainda. | | 400 | INT000014 | Bad Request | Document not signed yet. | Documento ainda não foi assinado. | | 400 | INT000015 | Bad Request | Integralization canceled. | Integralização cancelada. | | 400 | INT000016 | Bad Request | Integralization cancellation denied. There are integralized quantities. | Cancelamento de integralização negado. Existem cotas integralizadas. | | 400 | INT000017 | Bad Request | Creation of subscriptions for an ongoing operation is not available yet. | Ainda não é possível criar subscrições para operações em andamento. | | 400 | INT000018 | Bad Request | To create a signature with data different from the original, you must define a recalculation method using the recalculation_method field. | Para criar uma subscrição com data diferente da original é preciso definir um método de recálculo através do campo recalculation_method. | ## Tabela de erros possíveis no processo de amortização extraordinária | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (pt-BR) | |------------|----------------|--------------------|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------| | 404 | EVC000007 | Not Found | An integer in `installment_list` does not match any `installment_number` in the target security (`InstallmentNumberNotFound`). | Um inteiro de `installment_list` não corresponde a nenhum `installment_number` da `security` alvo. | | 400 | EVC100001 | Bad Request | The provided `amortization_type` is not one of the supported values. | O valor de `amortization_type` fornecido não é um dos tipos suportados. | | 400 | EVC100002 | Bad Request | `installment_list` is required for every `amortization_type`. | `installment_list` é obrigatório para todos os tipos de amortização. | | 400 | EVC100003 | Bad Request | `number_of_installments` is required for `first_installments`. | `number_of_installments` é obrigatório para `first_installments`. | | 400 | EVC100004 | Bad Request | One or more installments do not belong to the target security. | Uma ou mais parcelas informadas não pertencem ao ativo informado. | | 400 | EVC100005 | Bad Request | The amount does not cover the sum of the selected installments. | O valor informado não cobre a soma das parcelas selecionadas. | | 400 | EVC100006 | Bad Request | `total_discount` exceeds the present value of the selected installments. | `total_discount` excede o Valor Presente das parcelas selecionadas. | | 400 | EVC100007 | Bad Request | For `matured_installments`, all selected installments must be overdue. | Para `matured_installments`, todas as parcelas selecionadas devem estar vencidas. | | 400 | EVC100008 | Bad Request | An extraordinary event already exists for the installment. | Já existe uma amortização extraordinária pendente para a parcela. | | 424 | EVC100013 | Failed Dependency | The Security API is temporarily unavailable. | A Security API está temporariamente indisponível. | | 400 | EVC100015 | Bad Request | `early_amortization` requires exactly one installment in `installment_list`. | `early_amortization` requer exatamente uma parcela em `installment_list`. | | 400 | EVC100016 | Bad Request | The target installment is not eligible for `early_amortization` (already overdue). | A parcela alvo de `early_amortization` está vencida e não é elegível. | | 400 | EVC100017 | Bad Request | The `early_amortization` amount exceeds the installment's present value. | O valor de `early_amortization` excede o Valor Presente da parcela. | | 400 | EVC100030 | Bad Request | For `nominal_amount`, all selected installments must be due on or after the `reference_date` (not overdue). | Para `nominal_amount`, todas as parcelas selecionadas devem vencer na `reference_date` ou depois (não vencidas). | | 400 | EVC100031 | Bad Request | The `nominal_amount` amount exceeds the sum of the selected installments' nominal values. | O valor de `nominal_amount` excede a soma dos valores nominais das parcelas selecionadas. | | 400 | EVC100032 | Bad Request | The amount does not allocate a positive `expected_amount` to any selected installment; no event is created. | O valor informado não atribui `expected_amount` positivo a nenhuma parcela selecionada; nenhum evento é criado. | | 400 | EVC100033 | Bad Request | The distributed `expected_amount` total differs from the requested `amount` by more than the tolerance. | A soma dos `expected_amount` distribuídos difere do `amount` informado além da tolerância. | | 400 | EVC100034 | Bad Request | The amount does not allocate a positive `expected_amount` to one of the selected installments; no event is created. | O valor informado não atribui `expected_amount` positivo a uma das parcelas selecionadas; nenhum evento é criado. | | 400 | EVC100035 | Bad Request | The amount exceeds the present value of the selected installments. | O valor informado excede o Valor Presente das parcelas selecionadas. | | 404 | EVC100011 | Not Found | No extraordinary event conciliation was found for the provided `extraordinary_event_conciliation_key`. | Nenhuma amortização extraordinária encontrada para a `extraordinary_event_conciliation_key` informada. | | 400 | COM000050 | Bad Request | On a repurchase operation, the sum of the referenced extraordinary events' `expected_amount` cannot exceed the operation's `released_amount`. | Em uma operação de recompra, a soma do `expected_amount` dos eventos extraordinários referenciados não pode exceder o `released_amount` da operação. | | 400 | SEC000001 | Bad Request | The referenced security was not found. | O ativo (`security`) informado não foi encontrado. | | 404 | SEC000027 | Not Found | The referenced investment was not found. | O investimento (`investment`) informado não foi encontrado. | | 404 | SEC000029 | Not Found | The referenced installment was not found. | A parcela (`installment`) informada não foi encontrada. | | 400 | SEC000030 | Bad Request | The present value request is invalid (missing `investment_key` or malformed `reference_date`). | A requisição de Valor Presente é inválida (falta `investment_key` ou `reference_date` mal formatada). | | 400 | SEC000031 | Bad Request | Post-fixed securities (CDI, IPCA, IGPM) are not supported in V1. | Ativos pós-fixados (CDI, IPCA, IGPM) não são suportados na V1. | ## Tabela de erros possíveis no processo de aditamento | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (pt-BR) | |------------|----------------|--------|-----------------|------------------| | 404 | AMD000001 | Not Found | Security `{security_key}` not found for this tenant. | Título `{security_key}` não encontrado para esse tenant. | | 422 | AMD000002 | Unprocessable Entity | Security `{security_key}` is `{security_status}`, only an active security can be amended. | Título `{security_key}` está `{security_status}`, apenas um título ativo pode ser aditado. | | 422 | AMD000003 | Unprocessable Entity | Operation `{operation_key}` is `{operation_status}`, only a finished operation can be amended. | Operação `{operation_key}` está `{operation_status}`, apenas uma operação com emissão concluída pode ser aditada. | | 422 | AMD000004 | Unprocessable Entity | Security `{security_key}` is already settled, there is nothing left to amend. | Título `{security_key}` já foi liquidado, não há o que aditar. | | 422 | AMD000005 | Unprocessable Entity | Financial base date `{financial_base_date}` is in the past. A retroactive amendment is only accepted with a migration origin. | A data base `{financial_base_date}` está no passado. Um aditamento retroativo só é aceito com origem de tombamento. | | 422 | AMD000006 | Unprocessable Entity | Operation `{change_operation}` is not allowed for change type `{change_type}`. | A operação `{change_operation}` não é permitida para a alteração do tipo `{change_type}`. | | 422 | AMD000007 | Unprocessable Entity | A target_key is required for a `{change_operation}` on change type `{change_type}`. | Um target_key é obrigatório para `{change_operation}` na alteração do tipo `{change_type}`. | | 422 | AMD000008 | Unprocessable Entity | Collateral is not supported for instrument `{operation_type}`. | Garantia não é suportada para o instrumento `{operation_type}`. | | 422 | AMD000009 | Unprocessable Entity | The flow calculation rejected the submitted combination of parameters. | A combinação de parâmetros enviada foi recusada pelo cálculo do fluxo. | | 409 | AMD000012 | Conflict | Amendment `{amendment_key}` is `{amendment_status}` and does not allow this transition. | O aditamento `{amendment_key}` está `{amendment_status}` e não permite essa transição. | | 422 | AMD000013 | Unprocessable Entity | Simulation accepts only a financial_flow change, `{change_type}` was sent. Use the validation endpoint for the full change set. | A simulação aceita apenas uma alteração de financial_flow, `{change_type}` foi enviado. Use o endpoint de validação para o conjunto completo. | | 422 | AMD000014 | Unprocessable Entity | A related party of role_type `{role_type}` cannot be amended. | Uma parte relacionada com role_type `{role_type}` não pode ser aditada. | | 422 | AMD000015 | Unprocessable Entity | Collateral of type `{collateral_type}` requires documents that were not sent. | A garantia do tipo `{collateral_type}` exige documentos que não foram enviados. | | 413 | AMD000016 | Payload Too Large | Document `{document_name}` exceeds the maximum accepted size of `{max_size_bytes}` bytes. | O documento `{document_name}` excede o tamanho máximo aceito de `{max_size_bytes}` bytes. | | 404 | AMD000017 | Not Found | Amendment `{amendment_key}` not found. | Aditamento `{amendment_key}` não encontrado. | | 403 | AMD000018 | Forbidden | Amendment `{amendment_key}` does not belong to tenant. | O aditamento `{amendment_key}` não pertence ao tenant. | | 502 | AMD000019 | External Api Call Failed | External api call `{base_response.method}` `{base_response.endpoint}` failed with status `{base_response.response_status}`. | A chamada externa `{base_response.method}` `{base_response.endpoint}` falhou com status `{base_response.response_status}`. | | 422 | AMD000020 | Unprocessable Entity | Installment `{installment_number}` is `{installment_status}`: an installment with a payment already applied cannot be renegotiated. | A parcela `{installment_number}` está `{installment_status}`: uma parcela com pagamento já aplicado não pode ser renegociada. | | 422 | AMD000021 | Unprocessable Entity | Operation type `{operation_type}` has no originator mapped. | O tipo de operação `{operation_type}` não tem originador mapeado. | | 422 | AMD000022 | Unprocessable Entity | Amendment `{amendment_key}` has no signer to dispatch: the operation carries no active signer group for the issuer. | O aditamento `{amendment_key}` não tem signatário para envio: a operação não tem grupo de assinatura ativo para o emissor. | | 422 | AMD000023 | Unprocessable Entity | Amendment `{amendment_key}` has no amendment_term document to send to signature. | O aditamento `{amendment_key}` não tem documento de termo para enviar à assinatura. | | 409 | AMD000024 | Conflict | Amendment `{amendment_key}` already exists. | O aditamento `{amendment_key}` já existe. | | 422 | AMD000025 | Unprocessable Entity | security-service refused to amend security `{security_key}` (`{refusal_code}`): `{refusal_description}` | O security-service recusou o aditamento do título `{security_key}` (`{refusal_code}`): `{refusal_description}` | | 422 | AMD000026 | Unprocessable Entity | The originator refused to amend operation `{operation_key}` (`{refusal_code}`): `{refusal_description}` | O originador recusou o aditamento da operação `{operation_key}` (`{refusal_code}`): `{refusal_description}` | | 404 | AMD000027 | Not Found | Tenant `{tenant_key}` has no active billing configuration. | O tenant `{tenant_key}` não tem configuração de cobrança ativa. | | 422 | AMD000028 | Unprocessable Entity | Pricing method `{pricing_method}` requires `{missing_term}`. | O método de precificação `{pricing_method}` exige `{missing_term}`. | | 500 | AMD000029 | Internal Server Error | Charge pricing method `{pricing_method}` is seeded but not implemented. | O método de precificação `{pricing_method}` está no banco mas não é implementado. | | 422 | AMD000030 | Unprocessable Entity | Change `{amendment_change_key}` of type `{change_type}` has no application implemented. | O change `{amendment_change_key}` do tipo `{change_type}` não tem aplicação implementada. | | 409 | AMD000031 | Conflict | Security `{security_key}` already has amendment `{amendment_key}` on `{amendment_status}`; one amendment at a time. | O título `{security_key}` já tem o aditamento `{amendment_key}` em `{amendment_status}`; um aditamento por vez. | | 422 | AMD000032 | Unprocessable Entity | Vehicle `{chassis}` is already marked on Geero and can not enter this collateral. | O veículo `{chassis}` já está marcado no Geero e não pode entrar nesta garantia. | | 422 | AMD000033 | Unprocessable Entity | Vehicle `{chassis}` is not marked on Geero and can not be released from this collateral. | O veículo `{chassis}` não está marcado no Geero e não pode sair desta garantia. | | 422 | AMD000034 | Unprocessable Entity | Geero refused vehicle `{chassis}` (`{refusal_code}`): `{refusal_description}` | O Geero recusou o veículo `{chassis}` (`{refusal_code}`): `{refusal_description}` | | 409 | AMD000035 | Conflict | Change `{amendment_change_key}` of amendment `{amendment_key}` waits for the vehicle additions to be applied first. | O change `{amendment_change_key}` do aditamento `{amendment_key}` espera as adições de veículo serem aplicadas primeiro. | | 422 | AMD000036 | Unprocessable Entity | Vehicle `{chassis}` stays marked: a vehicle addition of amendment `{amendment_key}` failed, so no vehicle is released. | O veículo `{chassis}` continua marcado: uma adição de veículo do aditamento `{amendment_key}` falhou, então nenhum veículo é liberado. | | 404 | AMD000037 | Not Found | Document `{document_key}` not found on amendment `{amendment_key}`. | O documento `{document_key}` não foi encontrado no aditamento `{amendment_key}`. | | 422 | AMD000038 | Unprocessable Entity | Document `{document_key}` of amendment `{amendment_key}` has no signed file yet. | O documento `{document_key}` do aditamento `{amendment_key}` ainda não tem arquivo assinado. | | 422 | AMD000039 | Unprocessable Entity | Amendment `{amendment_key}` has no signature envelope yet. | O aditamento `{amendment_key}` ainda não tem envelope de assinatura. | | 422 | AMD000040 | Unprocessable Entity | A change of type `{change_type}` cannot elect a term signer. | Uma alteração de `{change_type}` não elege signatário do termo. | | 422 | AMD000041 | Unprocessable Entity | The `{role_type}` elected as term signer carries no signer_group_list. | A parte relacionada de papel `{role_type}` foi eleita signatária do termo, mas não trouxe signer_group_list. | | 422 | AMD000042 | Unprocessable Entity | Signer `{signer_name}` has no email, and the signature provider requires one. | O signatário `{signer_name}` não tem e-mail, e a assinatura não é enviada sem ele. | | 422 | AMD000043 | Unprocessable Entity | Related party `{target_key}` has no signer group on the originator and cannot sign the term. | A parte relacionada `{target_key}` não tem grupo de assinatura no originador, então não pode assinar o termo. | | 409 | AMD000044 | Conflict | Issue number '`{issue_number}`' is already used by an active operation of this issuer. | O número de emissão '`{issue_number}`' já está em uso por uma operação ativa deste emissor. | --- # Configuração de Webhooks URL: /documentation/escrituracao/configuracao-webhooks A API de Configuração de Webhooks permite gerenciar endpoints de webhook para receber notificações em tempo real sobre eventos da escrituração. Cada tenant pode ter múltiplas configurações de webhook, permitindo que os eventos sejam enviados para diferentes destinos. --- ## Modelo de Dados ### Configuração de Webhook ```json { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "headers": { "Authorization": "Bearer token", "X-Custom-Header": "value" }, "hmac_signature_key": "secret-key" } ``` --- ## Criar Configuração de Webhook (POST) ### Request ENDPOINT /outgoing_webhook/webhook_configuration MÉTODO POST ### Request Body ```json { "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "hmac_signature_key": "your-secret-key", "headers": { "Authorization": "Bearer token", "X-Custom-Header": "value" } } ``` ### Request Body Params | Campo | Tipo | Descrição | | ---------------------- | ------ | --------------------------------------------------------- | | `tenant_key`* | string | UUID do tenant (UUID v4). | | `url`* | string | URL de destino para receber os webhooks. | | `hmac_signature_key`* | string | Chave secreta para assinatura HMAC dos webhooks. | | `headers` | object | Headers personalizados para incluir nas requisições. | --- ### Response STATUS 201 Response Body ```json { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "headers": { "Authorization": "Bearer token", "X-Custom-Header": "value" }, "hmac_signature_key": "your-secret-key" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ---------------------- | ------ | --------------------------------------------------------- | | `configuration_key` | string | Chave única da configuração de webhook (UUID v4). | | `tenant_key` | string | UUID do tenant. | | `url` | string | URL de destino configurada. | | `headers` | object | Headers personalizados configurados. | | `hmac_signature_key` | string | Chave secreta para assinatura HMAC. | --- ## Listar Configurações de Webhook (GET) ### Request ENDPOINT /outgoing_webhook/webhook_configuration MÉTODO GET ### Query Params | Campo | Tipo | Descrição | | ------------ | ------- | ---------------------------------------------- | | `tenant_key`* | string | UUID do tenant para filtrar as configurações. | | `page` | integer | Número da página (padrão: 1). | | `page_size` | integer | Itens por página (padrão: 100). | --- ### Response STATUS 200 Response Body ```json { "data": [ { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "headers": { "Authorization": "Bearer token" }, "hmac_signature_key": "your-secret-key" } ], "pagination": { "current_page": 1, "page_size": 100, "total_rows": 15, "total_pages": 1 } } ``` ### Response Body Params | Campo | Tipo | Descrição | | ---------------------- | ------- | --------------------------------------------------------- | | `data` | array | Lista de configurações de webhook. | | `pagination` | object | **[Objeto pagination](#objeto-pagination)**. | --- ## Obter Configuração de Webhook por Chave (GET) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | Chave única da configuração de webhook (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/webhook", "headers": { "Authorization": "Bearer token" }, "hmac_signature_key": "your-secret-key" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ---------------------- | ------- | --------------------------------------------------------- | | `configuration_key` | string | Chave única da configuração de webhook (UUID v4). | | `tenant_key` | string | UUID do tenant. | | `url` | string | URL de destino configurada. | | `headers` | object | Headers personalizados configurados. | | `hmac_signature_key` | string | Chave secreta para assinatura HMAC. | --- ## Atualizar Configuração de Webhook (PUT) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY MÉTODO PUT ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | Chave única da configuração de webhook (UUID v4). | 36 | --- ### Request Body ```json { "url": "https://new-url.com/webhook", "headers": { "New-Header": "new-value" }, "hmac_signature_key": "new-secret-key" } ``` ### Request Body Params | Campo | Tipo | Descrição | | --------------------- | ------ | --------------------------------------------------------- | | `url` | string | Nova URL de destino para receber os webhooks. | | `headers` | object | Novos headers personalizados para incluir nas requisições. | | `hmac_signature_key` | string | Nova chave secreta para assinatura HMAC dos webhooks. | --- ### Response STATUS 200 Response Body ```json { "configuration_key": "550e8400-e29b-41d4-a716-446655440000", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "url": "https://new-url.com/webhook", "headers": { "New-Header": "new-value" }, "hmac_signature_key": "new-secret-key" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ---------------------- | ------- | --------------------------------------------------------- | | `configuration_key` | string | Chave única da configuração de webhook (UUID v4). | | `tenant_key` | string | UUID do tenant. | | `url` | string | URL de destino configurada. | | `headers` | object | Headers personalizados configurados. | | `hmac_signature_key` | string | Chave secreta para assinatura HMAC. | --- ## Deletar Configuração de Webhook (DELETE) ### Request ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------------- | ------ | ------------------------------------------------ | ---------- | | `CONFIGURATION-KEY` | string | Chave única da configuração de webhook (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json {} ``` --- # Cadastro de Lastro (Ativo Subjacente) URL: /documentation/escrituracao/emissao-cr/cadastro-lastro Este endpoint cadastra o **lastro** (ativo subjacente) de uma operação de CR. O lastro representa os direitos creditórios que dão suporte à securitização. O documento do ativo é enviado em base64 e seus dados estruturados acompanham a requisição. :::info O lastro é enviado **após a criação da operação**, em uma requisição separada. Podem ser cadastrados múltiplos lastros para a mesma operação. ::: --- ## **Request** ENDPOINT /cr/operation/ OPERATION-KEY /underlying_asset MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|------------------------------------|------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "underlying_asset_type": "contract", "underlying_asset_base64": "image_b64", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------------|--------|------------------------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | Tipo do lastro. | **[Enumeradores underlying_asset_type](#enumeradores-underlying_asset_type)** | | `underlying_asset_base64` * | string | Documento do lastro em base64. | - | | `underlying_asset_data` * | object | Dados do lastro (estrutura livre). | - | ### Enumeradores underlying_asset_type | Enum | Descrição | |------------|-----------| | `contract` | Contrato. | ## **Response** STATUS 201 Response Body ```json { "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23", "underlying_asset_type": "contract", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------------|--------|------------------------------------| | `underlying_asset_key` * | string | Chave única do lastro cadastrado. | | `underlying_asset_type` * | string | Tipo do lastro. | | `underlying_asset_data` * | object | Dados do lastro. | --- --- # Cadastro de Operação de CR URL: /documentation/escrituracao/emissao-cr/cadastro-operacao Este endpoint cria uma operação de CR completa em uma única requisição. :::info O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados. ::: --- ## **Request** ENDPOINT /cr/create_operation MÉTODO POST O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo. Payload com os campos obrigatórios ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "issue_date": "2025-01-20", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] } } ``` Payload completo (com partes relacionadas) ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "contract_number": "CR-2025-0001", "issue_date": "2025-01-20", "signature_method": "certifiqi", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] }, "related_party_list": [ { "person_type": "legal", "name": "Garantidora S.A.", "document_number": "12.345.678/0001-90", "trading_name": "Garantidora", "cnae_code": "64.62-0-00", "company_type": "sa", "foundation_date": "2010-05-01", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "postal_code": "01310-100", "city": "São Paulo", "state": "SP", "role_type": "guarantor" }, { "person_type": "natural", "name": "João da Silva", "document_number": "123.456.789-00", "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "solidary_debtor", "is_pep": false } ] } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------- | ---------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Chave única do tenant. | - | | `issuer_key` * | string | Chave única do emissor (previamente cadastrado). | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `investors` * | array | Lista de investidores envolvidos. | **Objeto investors** | | `financial` * | object | Dados financeiros já calculados da operação. | **Objeto financial** | | `contract_number` | string | Número do contrato. | - | | `related_party_list` | array | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** | ### Objeto investors | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Chave única do investidor (previamente cadastrado). | | `bank_account` * | object | Conta bancária do investidor (**Objeto bank_account**). | | `subscription_percentage` | number | Percentual de subscrição. | | `subscription_quantity` | number | Quantidade subscrita. | ### Objeto bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`). | ### Objeto financial | Campo | Tipo | Descrição | | --------------------------- | ------- | -------------------------------------------------- | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `interest_type` * | string | Tipo de juros. | | `issue_amount` | number | Valor total emitido. | | `issue_quantity` | integer | Quantidade de unidades emitidas. | | `unit_price` | number | Preço unitário da emissão. | | `released_amount` | number | Valor líquido liberado. | | `cet` / `annual_cet` | number | Custo Efetivo Total (mensal e anual), em percentual. | | `number_of_installments` * | integer | Número de parcelas. | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | | `fine_delay_rate` | object | Taxa de multa por atraso. | | `contract_fine_rate` | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | | `installments` | array | Lista de parcelas já calculadas. | ### Objeto related_party Cada item de `related_party_list` representa uma parte envolvida na operação. | Campo | Tipo | Descrição | | ----------------- | ------- | ------------------------------------------------------------- | | `person_type` * | string | Tipo de pessoa (`natural` para PF, `legal` para PJ). | | `name` * | string | Nome da parte relacionada. | | `document_number` * | string | CPF (PF) ou CNPJ (PJ). | | `role_type` * | string | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** | | `street` * | string | Logradouro. | | `number` * | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `postal_code` * | string | CEP (formato "00000-000"). | | `city` * | string | Cidade. | | `state` * | string | UF (2 letras). | | `complement` | string | Complemento do endereço. | | `is_pep` | boolean | (PF) Indica se é Pessoa Politicamente Exposta. | | `marital_status` | string | (PF) Estado civil. | | `property_system` | string | (PF) Regime de bens. | | `birthdate` | string | (PF) Data de nascimento. | | `mother_name` | string | (PF) Nome da mãe. | | `occupation` | string | (PF) Ocupação. | | `trading_name` | string | (PJ) Nome fantasia. | | `cnae_code` | string | (PJ) Código CNAE (formato "00.00-0-00"). | | `company_type` | string | (PJ) Tipo de empresa. | | `foundation_date` | string | (PJ) Data de fundação. | :::warning Atenção Os campos obrigatórios variam conforme o `person_type`: - **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório. - **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios. ::: ### Enumeradores role_type | Enum | Descrição | |------|-----------| | `issuer` | Emissor. | | `investor` | Investidor. | | `cosigner` | Coobrigado. | | `fiduciary_debtor` | Devedor fiduciante. | | `solidary_debtor` | Devedor solidário. | | `guarantor` | Avalista. | | `bonafide_depositary` | Fiel depositário. | | `intervening_guarantor` | Interveniente garantidor. | | `intervening_consentor` | Interveniente anuente. | | `intervening_discharger` | Interveniente quitante. | | `assignor` | Cedente. | | `endorser` | Endossante. | | `consulting` | Consultoria. | | `fund_administrator` | Administrador do fundo. | | `fund_representative` | Representante do fundo. | | `company_representative` | Representante da empresa. | | `attestant` | Anuente / testemunha. | | `debtor` | Devedor. | | `bestowal` | Outorgante. | | `manager` | Gestor. | :::tip Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Cadastro de lastro** desta seção. ::: ### Enumeradores signature_method | Enum | Descrição | |------|-----------| | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "finished", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "issue_number": 10, "issue_series": 1, "related_party_list": [ ... ], "financial": { ... } } ``` A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado. --- # Envio de Documento URL: /documentation/escrituracao/emissao-cr/envio-documento Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints da operação sempre que for exigida a chave de um documento previamente enviado. --- ## **Request** ENDPOINT /cr/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |-------------------|--------|----------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | | `document_name` | string | Nome do documento. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|--------|-------------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento enviado (UUID v4). | 36 | --- --- # Enviar Documento Externo da Operação URL: /documentation/escrituracao/emissao-cr/envio-documento-externo Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador. :::warning Aviso Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal. ::: --- ## Enviar Documento Assinado (POST) ### Request ENDPOINT /cr/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|--------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|-----------------------------|-------------------------------------------------------------| | `contract_type` * | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Documento assinado em base64. | - | ### Enumeradores contract_type | Enum | Descrição | |---------------------|--------------------------------------------| | `securitization_term` | Termo de securitização do CR. | | `adhesion_term` | Termo de adesão do CR. | | `sa_minute` | Ata de aprovação de emissão do CR para empresa **SA**. | | `ltda_minute` | Ata de aprovação de emissão do CR para empresa **LTDA**. | | `cop_minute` | Ata de aprovação de emissão do CR para **Cooperativa**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Cadastro de Lastro (Ativo Subjacente) URL: /documentation/escrituracao/emissao-cra/cadastro-lastro Este endpoint cadastra o **lastro** (ativo subjacente) de uma operação de CRA. O lastro representa os direitos creditórios que dão suporte à securitização. O documento do ativo é enviado em base64 e seus dados estruturados acompanham a requisição. :::info O lastro é enviado **após a criação da operação**, em uma requisição separada. Podem ser cadastrados múltiplos lastros para a mesma operação. ::: --- ## **Request** ENDPOINT /cra/operation/ OPERATION-KEY /underlying_asset MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|------------------------------------|------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "underlying_asset_type": "contract", "underlying_asset_base64": "image_b64", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------------|--------|------------------------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | Tipo do lastro. | **[Enumeradores underlying_asset_type](#enumeradores-underlying_asset_type)** | | `underlying_asset_base64` * | string | Documento do lastro em base64. | - | | `underlying_asset_data` * | object | Dados do lastro (estrutura livre). | - | ### Enumeradores underlying_asset_type | Enum | Descrição | |------------|-----------| | `contract` | Contrato. | ## **Response** STATUS 201 Response Body ```json { "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23", "underlying_asset_type": "contract", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------------|--------|------------------------------------| | `underlying_asset_key` * | string | Chave única do lastro cadastrado. | | `underlying_asset_type` * | string | Tipo do lastro. | | `underlying_asset_data` * | object | Dados do lastro. | --- --- # Cadastro de Operação de CRA URL: /documentation/escrituracao/emissao-cra/cadastro-operacao Este endpoint cria uma operação de CRA completa em uma única requisição. :::info O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados. ::: --- ## **Request** ENDPOINT /cra/create_operation MÉTODO POST O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo. Payload com os campos obrigatórios ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "issue_date": "2025-01-20", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] } } ``` Payload completo (com partes relacionadas) ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "contract_number": "CRA-2025-0001", "issue_date": "2025-01-20", "signature_method": "certifiqi", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] }, "related_party_list": [ { "person_type": "legal", "name": "Garantidora S.A.", "document_number": "12.345.678/0001-90", "trading_name": "Garantidora", "cnae_code": "64.62-0-00", "company_type": "sa", "foundation_date": "2010-05-01", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "postal_code": "01310-100", "city": "São Paulo", "state": "SP", "role_type": "guarantor" }, { "person_type": "natural", "name": "João da Silva", "document_number": "123.456.789-00", "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "solidary_debtor", "is_pep": false } ] } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------- | ---------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Chave única do tenant. | - | | `issuer_key` * | string | Chave única do emissor (previamente cadastrado). | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `investors` * | array | Lista de investidores envolvidos. | **Objeto investors** | | `financial` * | object | Dados financeiros já calculados da operação. | **Objeto financial** | | `contract_number` | string | Número do contrato. | - | | `related_party_list` | array | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** | ### Objeto investors | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Chave única do investidor (previamente cadastrado). | | `bank_account` * | object | Conta bancária do investidor (**Objeto bank_account**). | | `subscription_percentage` | number | Percentual de subscrição. | | `subscription_quantity` | number | Quantidade subscrita. | ### Objeto bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`). | ### Objeto financial | Campo | Tipo | Descrição | | --------------------------- | ------- | -------------------------------------------------- | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `interest_type` * | string | Tipo de juros. | | `issue_amount` | number | Valor total emitido. | | `issue_quantity` | integer | Quantidade de unidades emitidas. | | `unit_price` | number | Preço unitário da emissão. | | `released_amount` | number | Valor líquido liberado. | | `cet` / `annual_cet` | number | Custo Efetivo Total (mensal e anual), em percentual. | | `number_of_installments` * | integer | Número de parcelas. | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | | `fine_delay_rate` | object | Taxa de multa por atraso. | | `contract_fine_rate` | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | | `installments` | array | Lista de parcelas já calculadas. | ### Objeto related_party Cada item de `related_party_list` representa uma parte envolvida na operação. | Campo | Tipo | Descrição | | ----------------- | ------- | ------------------------------------------------------------- | | `person_type` * | string | Tipo de pessoa (`natural` para PF, `legal` para PJ). | | `name` * | string | Nome da parte relacionada. | | `document_number` * | string | CPF (PF) ou CNPJ (PJ). | | `role_type` * | string | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** | | `street` * | string | Logradouro. | | `number` * | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `postal_code` * | string | CEP (formato "00000-000"). | | `city` * | string | Cidade. | | `state` * | string | UF (2 letras). | | `complement` | string | Complemento do endereço. | | `is_pep` | boolean | (PF) Indica se é Pessoa Politicamente Exposta. | | `marital_status` | string | (PF) Estado civil. | | `property_system` | string | (PF) Regime de bens. | | `birthdate` | string | (PF) Data de nascimento. | | `mother_name` | string | (PF) Nome da mãe. | | `occupation` | string | (PF) Ocupação. | | `trading_name` | string | (PJ) Nome fantasia. | | `cnae_code` | string | (PJ) Código CNAE (formato "00.00-0-00"). | | `company_type` | string | (PJ) Tipo de empresa. | | `foundation_date` | string | (PJ) Data de fundação. | :::warning Atenção Os campos obrigatórios variam conforme o `person_type`: - **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório. - **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios. ::: ### Enumeradores role_type | Enum | Descrição | |------|-----------| | `issuer` | Emissor. | | `investor` | Investidor. | | `cosigner` | Coobrigado. | | `fiduciary_debtor` | Devedor fiduciante. | | `solidary_debtor` | Devedor solidário. | | `guarantor` | Avalista. | | `bonafide_depositary` | Fiel depositário. | | `intervening_guarantor` | Interveniente garantidor. | | `intervening_consentor` | Interveniente anuente. | | `intervening_discharger` | Interveniente quitante. | | `assignor` | Cedente. | | `endorser` | Endossante. | | `consulting` | Consultoria. | | `fund_administrator` | Administrador do fundo. | | `fund_representative` | Representante do fundo. | | `company_representative` | Representante da empresa. | | `attestant` | Anuente / testemunha. | | `debtor` | Devedor. | | `bestowal` | Outorgante. | | `manager` | Gestor. | :::tip Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Cadastro de lastro** desta seção. ::: ### Enumeradores signature_method | Enum | Descrição | |------|-----------| | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "finished", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "issue_number": 10, "issue_series": 1, "related_party_list": [ ... ], "financial": { ... } } ``` A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado. --- # Envio de Documento URL: /documentation/escrituracao/emissao-cra/envio-documento Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints da operação sempre que for exigida a chave de um documento previamente enviado. --- ## **Request** ENDPOINT /cra/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |-------------------|--------|----------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | | `document_name` | string | Nome do documento. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|--------|-------------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento enviado (UUID v4). | 36 | --- --- # Enviar Documento Externo da Operação URL: /documentation/escrituracao/emissao-cra/envio-documento-externo Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador. :::warning Aviso Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal. ::: --- ## Enviar Documento Assinado (POST) ### Request ENDPOINT /cra/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|--------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|-----------------------------|-------------------------------------------------------------| | `contract_type` * | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Documento assinado em base64. | - | ### Enumeradores contract_type | Enum | Descrição | |---------------------|--------------------------------------------| | `securitization_term` | Termo de securitização do CRA. | | `adhesion_term` | Termo de adesão do CRA. | | `sa_minute` | Ata de aprovação de emissão do CRA para empresa **SA**. | | `ltda_minute` | Ata de aprovação de emissão do CRA para empresa **LTDA**. | | `cop_minute` | Ata de aprovação de emissão do CRA para **Cooperativa**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Cadastro de Lastro (Ativo Subjacente) URL: /documentation/escrituracao/emissao-cri/cadastro-lastro Este endpoint cadastra o **lastro** (ativo subjacente) de uma operação de CRI. O lastro representa os direitos creditórios que dão suporte à securitização. O documento do ativo é enviado em base64 e seus dados estruturados acompanham a requisição. :::info O lastro é enviado **após a criação da operação**, em uma requisição separada. Podem ser cadastrados múltiplos lastros para a mesma operação. ::: --- ## **Request** ENDPOINT /cri/operation/ OPERATION-KEY /underlying_asset MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|------------------------------------|------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "underlying_asset_type": "contract", "underlying_asset_base64": "image_b64", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------------|--------|------------------------------------------|----------------------------------------------------------------------| | `underlying_asset_type` * | string | Tipo do lastro. | **[Enumeradores underlying_asset_type](#enumeradores-underlying_asset_type)** | | `underlying_asset_base64` * | string | Documento do lastro em base64. | - | | `underlying_asset_data` * | object | Dados do lastro (estrutura livre). | - | ### Enumeradores underlying_asset_type | Enum | Descrição | |------------|-----------| | `contract` | Contrato. | ## **Response** STATUS 201 Response Body ```json { "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23", "underlying_asset_type": "contract", "underlying_asset_data": { "contract_number": "12345", "debtor_document_number": "12.345.678/0001-90", "amount": 1075268.82, "due_date": "2026-01-20" } } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------------|--------|------------------------------------| | `underlying_asset_key` * | string | Chave única do lastro cadastrado. | | `underlying_asset_type` * | string | Tipo do lastro. | | `underlying_asset_data` * | object | Dados do lastro. | --- --- # Cadastro de Operação de CRI URL: /documentation/escrituracao/emissao-cri/cadastro-operacao Este endpoint cria uma operação de CRI completa em uma única requisição. :::info O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados. ::: --- ## **Request** ENDPOINT /cri/create_operation MÉTODO POST O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo. Payload com os campos obrigatórios ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "issue_date": "2025-01-20", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] } } ``` Payload completo (com partes relacionadas) ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "contract_number": "CRI-2025-0001", "issue_date": "2025-01-20", "signature_method": "certifiqi", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] }, "related_party_list": [ { "person_type": "legal", "name": "Garantidora S.A.", "document_number": "12.345.678/0001-90", "trading_name": "Garantidora", "cnae_code": "64.62-0-00", "company_type": "sa", "foundation_date": "2010-05-01", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "postal_code": "01310-100", "city": "São Paulo", "state": "SP", "role_type": "guarantor" }, { "person_type": "natural", "name": "João da Silva", "document_number": "123.456.789-00", "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "solidary_debtor", "is_pep": false } ] } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------- | ---------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Chave única do tenant. | - | | `issuer_key` * | string | Chave única do emissor (previamente cadastrado). | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `investors` * | array | Lista de investidores envolvidos. | **Objeto investors** | | `financial` * | object | Dados financeiros já calculados da operação. | **Objeto financial** | | `contract_number` | string | Número do contrato. | - | | `related_party_list` | array | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** | ### Objeto investors | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Chave única do investidor (previamente cadastrado). | | `bank_account` * | object | Conta bancária do investidor (**Objeto bank_account**). | | `subscription_percentage` | number | Percentual de subscrição. | | `subscription_quantity` | number | Quantidade subscrita. | ### Objeto bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`). | ### Objeto financial | Campo | Tipo | Descrição | | --------------------------- | ------- | -------------------------------------------------- | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `interest_type` * | string | Tipo de juros. | | `issue_amount` | number | Valor total emitido. | | `issue_quantity` | integer | Quantidade de unidades emitidas. | | `unit_price` | number | Preço unitário da emissão. | | `released_amount` | number | Valor líquido liberado. | | `cet` / `annual_cet` | number | Custo Efetivo Total (mensal e anual), em percentual. | | `number_of_installments` * | integer | Número de parcelas. | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | | `fine_delay_rate` | object | Taxa de multa por atraso. | | `contract_fine_rate` | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | | `installments` | array | Lista de parcelas já calculadas. | ### Objeto related_party Cada item de `related_party_list` representa uma parte envolvida na operação. | Campo | Tipo | Descrição | | ----------------- | ------- | ------------------------------------------------------------- | | `person_type` * | string | Tipo de pessoa (`natural` para PF, `legal` para PJ). | | `name` * | string | Nome da parte relacionada. | | `document_number` * | string | CPF (PF) ou CNPJ (PJ). | | `role_type` * | string | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** | | `street` * | string | Logradouro. | | `number` * | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `postal_code` * | string | CEP (formato "00000-000"). | | `city` * | string | Cidade. | | `state` * | string | UF (2 letras). | | `complement` | string | Complemento do endereço. | | `is_pep` | boolean | (PF) Indica se é Pessoa Politicamente Exposta. | | `marital_status` | string | (PF) Estado civil. | | `property_system` | string | (PF) Regime de bens. | | `birthdate` | string | (PF) Data de nascimento. | | `mother_name` | string | (PF) Nome da mãe. | | `occupation` | string | (PF) Ocupação. | | `trading_name` | string | (PJ) Nome fantasia. | | `cnae_code` | string | (PJ) Código CNAE (formato "00.00-0-00"). | | `company_type` | string | (PJ) Tipo de empresa. | | `foundation_date` | string | (PJ) Data de fundação. | :::warning Atenção Os campos obrigatórios variam conforme o `person_type`: - **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório. - **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios. ::: ### Enumeradores role_type | Enum | Descrição | |------|-----------| | `issuer` | Emissor. | | `investor` | Investidor. | | `cosigner` | Coobrigado. | | `fiduciary_debtor` | Devedor fiduciante. | | `solidary_debtor` | Devedor solidário. | | `guarantor` | Avalista. | | `bonafide_depositary` | Fiel depositário. | | `intervening_guarantor` | Interveniente garantidor. | | `intervening_consentor` | Interveniente anuente. | | `intervening_discharger` | Interveniente quitante. | | `assignor` | Cedente. | | `endorser` | Endossante. | | `consulting` | Consultoria. | | `fund_administrator` | Administrador do fundo. | | `fund_representative` | Representante do fundo. | | `company_representative` | Representante da empresa. | | `attestant` | Anuente / testemunha. | | `debtor` | Devedor. | | `bestowal` | Outorgante. | | `manager` | Gestor. | :::tip Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Cadastro de lastro** desta seção. ::: ### Enumeradores signature_method | Enum | Descrição | |------|-----------| | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "finished", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "issue_number": 10, "issue_series": 1, "related_party_list": [ ... ], "financial": { ... } } ``` A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado. --- # Envio de Documento URL: /documentation/escrituracao/emissao-cri/envio-documento Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints da operação sempre que for exigida a chave de um documento previamente enviado. --- ## **Request** ENDPOINT /cri/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |-------------------|--------|----------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | | `document_name` | string | Nome do documento. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|--------|-------------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento enviado (UUID v4). | 36 | --- --- # Enviar Documento Externo da Operação URL: /documentation/escrituracao/emissao-cri/envio-documento-externo Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador. :::warning Aviso Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal. ::: --- ## Enviar Documento Assinado (POST) ### Request ENDPOINT /cri/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|--------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "securitization_term" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|-----------------------------|-------------------------------------------------------------| | `contract_type` * | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Documento assinado em base64. | - | ### Enumeradores contract_type | Enum | Descrição | |---------------------|--------------------------------------------| | `securitization_term` | Termo de securitização do CRI. | | `adhesion_term` | Termo de adesão do CRI. | | `sa_minute` | Ata de aprovação de emissão do CRI para empresa **SA**. | | `ltda_minute` | Ata de aprovação de emissão do CRI para empresa **LTDA**. | | `cop_minute` | Ata de aprovação de emissão do CRI para **Cooperativa**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Atualização da conta de desembolso da operação. URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso Este endpoint permite a atualização da conta de desembolso de uma operação. --- ## **Atualização da conta de desembolso da operação (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /issuer_bank_account MÉTODO PUT ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "issuer_bank_account": { "account_number": "4464541", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ``` ### Request Body Params ### **Objeto issuer_bank_account** | Campo | Tipo | Descrição | | --------------------------------------- | ------ | ------------------------------------------ | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` * | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`). | ## **Response** STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74", "operation_type": "commercial_paper", "operation_status": "issued", "backoffice_analysis_status": "approved", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "issuer_onboarding_approved": true, "issue_number": 1, "issue_series": 1, "contract_number": "0000000001", "issue_date": "2025-02-03", "financial_base_date": "2025-02-03", "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9", "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8", "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f", "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c", "envelope_signature_status": "signed", "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b", "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a", "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files", "financial": { "financial_base_date": "2025-02-03", "issue_quantity": 1000000, "unit_price": 1.0, "issue_amount": 1000000.0, "released_amount": 1000000.0, "cet": 5.0, "annual_cet": 79.59, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0016053474, "annual_rate": 0.795856326, "monthly_rate": 0.05, "interest_base": "calendar_days_365" }, "fine_delay_rate": { "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "financial_index": null, "post_fixed_interest_rate": null, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 20000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 50000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_number": 1, "workdays": 20, "calendar_days": 30, "principal_amortization_unit_price": 0.18122484, "principal_amortization_amount": 181224.84138231, "interest_amount": 49298.45861769, "amount": 230523.3, "due_principal": 1000000.0, "due_interest": 0.0, "due_date": "2025-03-05", "has_interest": true }, { "installment_number": 2, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.19153595, "principal_amortization_amount": 191535.95353305, "interest_amount": 38987.34646695, "amount": 230523.3, "due_principal": 818775.15861769, "due_interest": 0.0, "due_date": "2025-04-03", "has_interest": true }, { "installment_number": 3, "workdays": 19, "calendar_days": 32, "principal_amortization_unit_price": 0.19748652, "principal_amortization_amount": 197486.52331007, "interest_amount": 33036.77668993, "amount": 230523.3, "due_principal": 627239.20508464, "due_interest": 0.0, "due_date": "2025-05-05", "has_interest": true }, { "installment_number": 4, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.21005991, "principal_amortization_amount": 210059.90840452, "interest_amount": 20463.39159548, "amount": 230523.3, "due_principal": 429752.68177457, "due_interest": 0.0, "due_date": "2025-06-03", "has_interest": true }, { "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.21969277, "principal_amortization_amount": 219692.77337005, "interest_amount": 10830.52662995, "amount": 230523.3, "due_principal": 219692.77337005, "due_interest": 0.0, "due_date": "2025-07-03", "has_interest": true } ] }, "tags": [], "investor_list": [ { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "subscription_percentage": 100.0, "subscription_quantity": 1000000, "investor_onboarding_approved": true, "bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "updated_at": null } ], "related_party_list": [ { "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c", "name": "Blue Logic", "document_number": "97.923.586/0001-06", "role_type": "issuer", "is_active": true, "updated_at": null, "trading_name": "Blue Logic", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5511988887777", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5516982399722", "document_number": "123.456.789-00", "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414" } ] }, { "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30", "name": "Ultimate Cascade", "document_number": "31.424.651/0001-32", "role_type": "investor", "is_active": true, "updated_at": null, "trading_name": "Ultimate Cascade", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5516982399722", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5511988887777", "document_number": "123.456.789-00", "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ] } ], "collateral_list": [ { "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "collateral_type": "fiduciary_alienation_property" } ], "metadata_list": [ { "metadata_key": "convenio", "metadata_value": "12398129038" } ], "signature_method": "qi_sign" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Chave única do tenant. | | `operation_key` * | string | Chave única da operação. | | `operation_status` * | string | Status da operação. | | `issuer_key` * | string | Chave única do emissor. | | `issuer_name` * | string | Nome do emissor. | | `issuer_document_number` * | string | Documento do emissor. | | `financial` * | object | **[Objeto financial](#objeto-financial-response)** | ### Objeto financial response | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-installments)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | | `daily_rate` * | number | Taxa de juros diária aplicada. | - | | `annual_rate` * | number | Taxa de juros anual aplicada. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Valor percentual da taxa. | - | | `fee_amount` * | number | Valor monetário correspondente à taxa. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Objeto installments | Campo | Tipo | Descrição | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Atualização de dados financeiros na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros Este endpoint permite a atualização dos dados financeiros em uma operação, seguindo o padrão de objeto financial, também enviado no endpoint de simulação. --- ## **Atualização de dados financeiros na Operação (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /financial MÉTODO PUT ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-02-03", "released_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ] } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_type` * | string | Tipo de juros aplicado. | **[Enumeradores interest_type](#enumeradores-interest_type)** | | `financial_base_date` * | string | Data base da operação (formato "YYYY-MM-DD"). | - | | `released_amount` * | number | Valor total liberado na operação. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | ### Objeto fine_delay_rate | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Base para cálculo da multa. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de multa mensal. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `amount` * | number | Valor da taxa aplicada. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Enumeradores interest_type | Enum | Descrição | |--------------------|------------------------------------------| | `pre_price` | Juros pré-fixados no modelo Price. | | `pre_price_days` | Juros pré-fixados no modelo Price por dias corridos. | | `pre_sac` | Juros pré-fixados no modelo SAC. | | `post_sac` | Juros pós-fixados no modelo SAC. | ### Enumeradores interest_base | Enum | Descrição | |--------------------|------------------------------------------| | `calendar_days` | Base de dias corridos. | | `calendar_days_365`| Base de 365 dias corridos. | | `workdays` | Base de dias úteis. | ### Enumeradores amount_type | Enum | Descrição | |-------------|---------------------------| | `percentage` | Valor em percentual. | | `absolute` | Valor absoluto em moeda. | ### Enumeradores fee_type | Enum | Descrição | |-------------------------------------|-------------------------------------------| | `bookkeeping_fee` | Taxa de escrituração financiada. | | `structuring_fee` | Taxa de estruturação financiada. | ### Enumeradores fee_recipient | Enum | Descrição | |-----------|-------------------------------------------------------| | `internal` | Taxa paga ao escriturador. | | `external` | Rebate pago ao originador. | ## **Response** STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74", "operation_type": "commercial_paper", "operation_status": "issued", "backoffice_analysis_status": "approved", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "issuer_onboarding_approved": true, "issue_number": 1, "issue_series": 1, "contract_number": "0000000001", "issue_date": "2025-02-03", "financial_base_date": "2025-02-03", "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9", "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8", "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f", "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c", "envelope_signature_status": "signed", "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b", "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a", "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files", "financial": { "financial_base_date": "2025-02-03", "issue_quantity": 1000000, "unit_price": 1.0, "issue_amount": 1000000.0, "released_amount": 1000000.0, "cet": 5.0, "annual_cet": 79.59, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0016053474, "annual_rate": 0.795856326, "monthly_rate": 0.05, "interest_base": "calendar_days_365" }, "fine_delay_rate": { "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "financial_index": null, "post_fixed_interest_rate": null, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 20000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 50000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_number": 1, "workdays": 20, "calendar_days": 30, "principal_amortization_unit_price": 0.18122484, "principal_amortization_amount": 181224.84138231, "interest_amount": 49298.45861769, "amount": 230523.3, "due_principal": 1000000.0, "due_interest": 0.0, "due_date": "2025-03-05", "has_interest": true }, { "installment_number": 2, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.19153595, "principal_amortization_amount": 191535.95353305, "interest_amount": 38987.34646695, "amount": 230523.3, "due_principal": 818775.15861769, "due_interest": 0.0, "due_date": "2025-04-03", "has_interest": true }, { "installment_number": 3, "workdays": 19, "calendar_days": 32, "principal_amortization_unit_price": 0.19748652, "principal_amortization_amount": 197486.52331007, "interest_amount": 33036.77668993, "amount": 230523.3, "due_principal": 627239.20508464, "due_interest": 0.0, "due_date": "2025-05-05", "has_interest": true }, { "installment_number": 4, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.21005991, "principal_amortization_amount": 210059.90840452, "interest_amount": 20463.39159548, "amount": 230523.3, "due_principal": 429752.68177457, "due_interest": 0.0, "due_date": "2025-06-03", "has_interest": true }, { "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.21969277, "principal_amortization_amount": 219692.77337005, "interest_amount": 10830.52662995, "amount": 230523.3, "due_principal": 219692.77337005, "due_interest": 0.0, "due_date": "2025-07-03", "has_interest": true } ] }, "tags": [], "investor_list": [ { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "subscription_percentage": 100.0, "subscription_quantity": 1000000, "investor_onboarding_approved": true, "bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "updated_at": null } ], "related_party_list": [ { "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c", "name": "Blue Logic", "document_number": "97.923.586/0001-06", "role_type": "issuer", "is_active": true, "updated_at": null, "trading_name": "Blue Logic", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5511988887777", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5516982399722", "document_number": "123.456.789-00", "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414" } ] }, { "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30", "name": "Ultimate Cascade", "document_number": "31.424.651/0001-32", "role_type": "investor", "is_active": true, "updated_at": null, "trading_name": "Ultimate Cascade", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5516982399722", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5511988887777", "document_number": "123.456.789-00", "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ] } ], "collateral_list": [ { "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "collateral_type": "fiduciary_alienation_property" } ], "metadata_list": [ { "metadata_key": "convenio", "metadata_value": "12398129038" } ], } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Chave única do tenant. | | `operation_key` * | string | Chave única da operação. | | `operation_status` * | string | Status da operação. | | `issuer_key` * | string | Chave única do emissor. | | `issuer_name` * | string | Nome do emissor. | | `issuer_document_number` * | string | Documento do emissor. | | `financial` * | object | **[Objeto financial](#objeto-financial-response)** | ### Objeto financial response | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-installments)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | | `daily_rate` * | number | Taxa de juros diária aplicada. | - | | `annual_rate` * | number | Taxa de juros anual aplicada. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Valor percentual da taxa. | - | | `fee_amount` * | number | Valor monetário correspondente à taxa. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Objeto installments | Campo | Tipo | Descrição | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Atualização do método de assinatura na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura Este endpoint permite a atualização do método de assinatura em uma operação. --- ## **Atualização do método de assinatura na Operação (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signature_method MÉTODO PUT ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "signature_method": "qi_sign" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `signature_method` * | string | Tipo de sistema de assinatura. | certifiqi ou qi_sign | ## **Response** STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74", "operation_type": "commercial_paper", "operation_status": "issued", "backoffice_analysis_status": "approved", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "issuer_onboarding_approved": true, "issue_number": 1, "issue_series": 1, "contract_number": "0000000001", "issue_date": "2025-02-03", "financial_base_date": "2025-02-03", "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9", "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8", "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f", "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c", "envelope_signature_status": "signed", "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b", "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a", "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files", "financial": { "financial_base_date": "2025-02-03", "issue_quantity": 1000000, "unit_price": 1.0, "issue_amount": 1000000.0, "released_amount": 1000000.0, "cet": 5.0, "annual_cet": 79.59, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0016053474, "annual_rate": 0.795856326, "monthly_rate": 0.05, "interest_base": "calendar_days_365" }, "fine_delay_rate": { "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "financial_index": null, "post_fixed_interest_rate": null, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 20000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 50000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_number": 1, "workdays": 20, "calendar_days": 30, "principal_amortization_unit_price": 0.18122484, "principal_amortization_amount": 181224.84138231, "interest_amount": 49298.45861769, "amount": 230523.3, "due_principal": 1000000.0, "due_interest": 0.0, "due_date": "2025-03-05", "has_interest": true }, { "installment_number": 2, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.19153595, "principal_amortization_amount": 191535.95353305, "interest_amount": 38987.34646695, "amount": 230523.3, "due_principal": 818775.15861769, "due_interest": 0.0, "due_date": "2025-04-03", "has_interest": true }, { "installment_number": 3, "workdays": 19, "calendar_days": 32, "principal_amortization_unit_price": 0.19748652, "principal_amortization_amount": 197486.52331007, "interest_amount": 33036.77668993, "amount": 230523.3, "due_principal": 627239.20508464, "due_interest": 0.0, "due_date": "2025-05-05", "has_interest": true }, { "installment_number": 4, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.21005991, "principal_amortization_amount": 210059.90840452, "interest_amount": 20463.39159548, "amount": 230523.3, "due_principal": 429752.68177457, "due_interest": 0.0, "due_date": "2025-06-03", "has_interest": true }, { "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.21969277, "principal_amortization_amount": 219692.77337005, "interest_amount": 10830.52662995, "amount": 230523.3, "due_principal": 219692.77337005, "due_interest": 0.0, "due_date": "2025-07-03", "has_interest": true } ] }, "tags": [], "investor_list": [ { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "subscription_percentage": 100.0, "subscription_quantity": 1000000, "investor_onboarding_approved": true, "bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "updated_at": null } ], "related_party_list": [ { "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c", "name": "Blue Logic", "document_number": "97.923.586/0001-06", "role_type": "issuer", "is_active": true, "updated_at": null, "trading_name": "Blue Logic", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5511988887777", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5516982399722", "document_number": "123.456.789-00", "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414" } ] }, { "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30", "name": "Ultimate Cascade", "document_number": "31.424.651/0001-32", "role_type": "investor", "is_active": true, "updated_at": null, "trading_name": "Ultimate Cascade", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5516982399722", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5511988887777", "document_number": "123.456.789-00", "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ] } ], "collateral_list": [ { "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "collateral_type": "fiduciary_alienation_property" } ], "metadata_list": [ { "metadata_key": "convenio", "metadata_value": "12398129038" } ], "signature_method": "qi_sign" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Chave única do tenant. | | `operation_key` * | string | Chave única da operação. | | `operation_status` * | string | Status da operação. | | `issuer_key` * | string | Chave única do emissor. | | `issuer_name` * | string | Nome do emissor. | | `issuer_document_number` * | string | Documento do emissor. | | `financial` * | object | **[Objeto financial](#objeto-financial-response)** | ### Objeto financial response | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-installments)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- | | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | | `daily_rate` * | number | Taxa de juros diária aplicada. | - | | `annual_rate` * | number | Taxa de juros anual aplicada. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- | | `amount` * | number | Valor percentual da taxa. | - | | `fee_amount` * | number | Valor monetário correspondente à taxa. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Objeto installments | Campo | Tipo | Descrição | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Envio de Garantia na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia Este conjunto de endpoints permite a **adição de garantias** associadas a uma operação. O **collateral será submetido para assinatura junto com os documentos da operação**. Cada tipo de garantia contém as suas regras de documentos necessários e todos os tipos de garantias estão contemplados aqui nesta documentação. --- ## **Envio de Garantia (POST)** ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- O sistema de garantias possibilita a adição de diferentes tipos de instrumentos, cada um com sua própria configuração de documentos adicionais. Nesta sessão, tratamos todos os modelos de garantia disponíveis e seus respectivos payloads. ### **Tipos de Garantias** **[1 - Alienação fiduciária de imóvel](#alienação-fiduciária-de-imóvel)** **[2 - Alienação fiduciária de veículo](#alienação-fiduciária-de-veículo)** **[3 - Alienação fiduciária de aeronave](#alienação-fiduciária-de-aeronave)** **[4 - Alienação fiduciária de equipamentos/produtos/Estoque](#alienação-fiduciária-de-equipamentos-produtos-e-estoque)** **[5 - Alienação fiduciária de obras de arte](#alienação-fiduciária-de-obras-de-arte)** **[6 - Alienação fiduciária de títulos e valores mobiliários](#alienação-fiduciária-de-títulos-e-valores-mobiliários)** **[7 - Alienação fiduciária de Ações e Cotas](#alienação-fiduciária-de-ações-e-cotas)** **[8 - Alienação fiduciária de diretos creditórios](#alienação-fiduciária-de-direitos-creditórios)** **[9 - Hipoteca de imóveis](#hipoteca-de-imóveis)** **[10 - Hipoteca de embarcações](#hipoteca-de-embarcações)** **[11 - Aval](#aval)** **[12 - Fiador](#fiador)** **[13 - Fiança Bancária](#fiança-bancária)** **[14 - Recebiveis de cartão](#recebiveis-de-cartão)** **[15 - Garantia de estoque](#garantia-de-estoque)** **[16 - Monitoramento de garantias](#monitoramento-de-garantias)** **[17 - Garantia de estoque de veículos (Floor Plan)](#garantia-de-estoque-de-veículos-floor-plan)** **[18 - Outras garantias](#outras-garantias)** ## **Alienação fiduciária de imóvel** Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_property", "additional_documents": [ { "document_type": "property_appraisal_report", "document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff" }, { "document_type": "property_registration_updated", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_full_content_certificate", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "property_insurance_policy", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `property_appraisal_report`** | Laudo de Avaliação do Imóvel. | | `property_registration_updated`** | Matrícula atualizada. | | `property_full_content_certificate`** | Certidão de Inteiro Teor da Matrícula. | | `property_insurance_policy` | Apólice de Seguros (se exigível no contrato). | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de imóvel ::: ## **Alienação fiduciária de veículo** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_vehicle", "additional_documents": [ { "document_type": "vehicle_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "vehicle_inspection_report", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "vehicle_crv_certificate", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `vehicle_appraisal_report`** | Laudo de Avaliação do Veículo (defasagem máxima de 30 dias) ou Tabela FIPE. | | `vehicle_inspection_report`** | Laudo vistoria. | | `vehicle_crv_certificate`** | Certificado de Registro de Veículo (CRLV) Atualizado. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de veículo ::: ## **Alienação fiduciária de aeronave** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_aircraft", "additional_documents": [ { "document_type": "aircraft_certificate_anac", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "aircraft_rab_consult", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "aircraft_insurance_policy", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" }, { "document_type": "aircraft_appraisal_report", "document_key": "df608f78-5293-4f96-ab60-31185633b52c" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `aircraft_certificate_anac`** | Certificado de Matrícula - ANAC. | | `aircraft_rab_consult`** | Consulta de Aeronave no Registro Aeronáutico Brasileiro. | | `aircraft_insurance_policy`** | Apólice de Seguro - Beneficiário o Fundo. | | `aircraft_appraisal_report`** | Laudo de Avaliação de Aeronave. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de aeronave ::: ## **Alienação fiduciária de equipamentos produtos e estoque** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_equipment", "additional_documents": [ { "document_type": "equipment_purchase_invoice", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "fiduciary_depositary_declaration", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "equipment_appraisal_report", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" }, { "document_type": "equipment_insurance_policy", "document_key": "df608f78-5293-4f96-ab60-31185633b52c" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `equipment_purchase_invoice`** | Nota Fiscal - Registro de Compra. | | `equipment_appraisal_report`** | Laudo de Avaliação de Equipamentos (defasagem máxima de 30 dias). | | `equipment_insurance_policy` | Apólice de Seguro de Equipamentos (se exigível no contrato). | | `fiduciary_depositary_declaration` | Declaração de Fiel Depositário. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de equipamentos/produto/estoque ::: ## **Alienação fiduciária de obras de arte** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_artwork", "additional_documents": [ { "document_type": "artwork_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "artwork_storage_certificate", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `artwork_appraisal_report`** | Laudo de avaliação de Obras de Arte. | | `artwork_storage_certificate`** | Local de Armazenamento com Certificado de Adequação. | | `artwork_insurance_policy` | Apólice de Seguro (se exigível no contrato). | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de obras de arte ::: ## **Alienação fiduciária de títulos e valores mobiliários** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_alienation_securities", "additional_documents": [ { "document_type": "securities_negotiation_block", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `securities_negotiation_block`** | Bloqueio para Negociação junto ao Custodiante. | | `securities_registration_gravame` | Local de Armazenamento com Certificado de Adequação. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária de títulos valores mobiliários. ::: ## **Alienação fiduciária de Ações e Cotas** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_assignment_shares", "additional_documents": [ { "document_type": "share_registration_book", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `share_registration_book`** | Livro de Registro de Ações Nominativas com Anotação do Gravame. | | `others` | Outros documentos. | :::warning (**) Obrigatório para alienação fiduciária/Penhor de Ações/Cotas ::: ## **Alienação fiduciária de diretos creditórios** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "fiduciary_assignment_shares", } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `others` | Outros documentos. | ## **Hipoteca de imóveis** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "mortgage_property", "additional_documents": [ { "document_type": "property_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_registration", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "property_insurance_policy", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" }, { "document_type": "property_full_content_certificate", "document_key": "df608f78-5293-4f96-ab60-31185633b52c" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `property_appraisal_report`** | Laudo de Avaliação de Imóvel. | | `property_registration`** | Registro de Propriedade Atualizado. | | `property_full_content_certificate`** | Certidão de Inteiro Teor da Matrícula. | | `property_insurance_policy` | Apólice de Seguros (se exigível no contrato). | | `others` | Outros documentos. | :::warning (**) Obrigatório para Hipoteca de imóveis. ::: ## **Hipoteca de Embarcações** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "mortgage_ship", "additional_documents": [ { "document_type": "ship_registration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "ship_appraisal_report", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "ship_insurance_policy", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `ship_registration`** | Registro de Propriedade de Embarcação Atualizado. | | `ship_appraisal_report`** | Laudo de Avaliação de Embarcação (defasagem máxima de 3 meses). | | `ship_insurance_policy` | Apólice de Seguros de embarcação (se exigível no contrato). | | `others` | Outros documentos. | :::warning (**) Obrigatório para Hipoteca de embarcações. ::: ## **Aval** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "guarantor", "additional_documents": [ { "document_type": "guarantor_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "guarantor_personal_document", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `guarantor_civil_status_declaration`** | Declaração de Estado Civil do Avalista. | | `guarantor_personal_document`** | Documento pessoal do Avalista. | | `guarantor_income_tax_declaration` | Declaração de Imposto de Renda do Avalista. | | `others` | Outros documentos. | :::warning (**) Obrigatório para Aval. ::: ## **Fiador** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "surety", "additional_documents": [ { "document_type": "surety_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "surety_personal_document", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" }, { "document_type": "surety_income_tax_declaration", "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `surety_civil_status_declaration`** | Declaração de Estado Civil do Fiador. | | `surety_personal_document`** | Documento pessoal do Fiador. | | `surety_income_tax_declaration` | Declaração de Imposto de Renda do Fiador. | | `others` | Outros documentos. | :::warning (**) Obrigatório para Fiador. ::: ## **Fiança Bancária** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "bank_surety", "additional_documents": [ { "document_type": "others", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `others` | Outros documentos. | ## **Recebiveis de cartão** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "card_receivables", "additional_documents": [ { "document_type": "others", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `others` | Outros documentos. | ## **Garantia de estoque** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "stock_guarantee", "additional_documents": [ { "document_type": "others", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `others` | Outros documentos. | ## **Monitoramento de garantias** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "monitoring_guarantee", "additional_documents": [ { "document_type": "guarantee_contract", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "guarantee_agent_contract", "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `guarantee_contract`** | Contrato de Garantia. | | `guarantee_agent_contract`** | Contrato de agente de Garantia. | | `others` | Outros documentos. | :::warning (**) Obrigatório para Monitoramento de Garantias.` ::: ## **Garantia de estoque de veículos (Floor Plan)** Modelo de garantia utilizado em operações de **Floor Plan**, no qual o emissor disponibiliza um estoque de veículos como garantia da operação. Diferente dos demais tipos, este modelo **não utiliza `collateral_document_key` nem `additional_documents`** — a garantia é composta por uma lista de veículos, enviada no campo `vehicles`. Ao ser cadastrada, cada veículo da lista é **consultado** (não gravado) junto à base de estoque da B3 (Geero). O cadastro segue a regra **tudo ou nada**: se qualquer veículo da lista já estiver gravado (ou a consulta falhar), a garantia inteira é rejeitada e nenhum veículo é persistido. Request Body ```json { "collateral_type": "vehicle_stock", "vehicles": [ { "chassis": "9BWZZZ377VT004251", "plate": "ABC1D23", "plate_state": "SP", "renavam": "12345678901" }, { "chassis": "9BWZZZ377VT004252" } ] } ``` ### **vehicles list** | Campo | Tipo | Descrição | Obrigatório | |----------------------|--------|----------------------------------------------------------------------------------------------------------------|-------------| | `chassis` * | string | Chassi do veículo. 17 caracteres alfanuméricos maiúsculos. | Sim | | `plate` | string | Placa do veículo, no padrão Mercosul ou antigo. | Não** | | `plate_state` | string | UF de emplacamento do veículo (sigla). | Não** | | `renavam` | string | RENAVAM do veículo. 9 a 11 dígitos numéricos. | Não** | :::warning (**) `plate`, `plate_state` e `renavam` formam um grupo **tudo ou nada**: o veículo deve enviar os três campos juntos (veículo emplacado/usado) ou nenhum dos três (veículo 0km, ainda sem emplacamento). O envio de apenas parte do grupo é rejeitado com erro de validação (400). ::: ### **Status de gravação por veículo (`marking_status`)** Cada veículo dentro do collateral carrega um `marking_status`, retornado através dos endpoints de consulta de operação/garantia: | Status | Descrição | |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------| | `pending_signature` | Estado inicial. Nenhuma tentativa de gravação foi feita ainda — a garantia foi apenas consultada e aceita no cadastro. | | `ineligible_for_marking` | Na re-consulta feita imediatamente antes da gravação (aprovação do compliance, antes do envio para assinatura), o veículo foi encontrado já gravado/indisponível. | | `marked` | O veículo foi gravado com sucesso junto à B3 (Geero). O campo `reserved_at` é preenchido com a data/hora da gravação. | | `unmarked` | O veículo havia sido gravado com sucesso, mas foi desfeito (rollback) porque outro veículo do mesmo lote falhou na gravação. | | `marking_failed` | A tentativa de gravação deste veículo falhou — é o veículo que disparou o cancelamento/rollback do lote. | ### **Fluxo de gravação** - **No cadastro (`in_filling`):** cada veículo é apenas **consultado**. Se algum já estiver gravado, a garantia inteira é rejeitada — nada é persistido. - **Na aprovação do compliance (transição para `pending_signature_submission`, imediatamente antes do envio para assinatura):** **todos** os veículos de **todas** as garantias `vehicle_stock` ativas da operação são re-consultados em uma única varredura. Se qualquer veículo estiver inelegível, nenhum veículo do lote é gravado, a operação é cancelada e um alerta é disparado. - Se a re-consulta passar para todos, cada veículo é gravado junto à B3 (Geero). Se a gravação de um veículo falhar, todos os veículos já gravados no mesmo lote são desfeitos (`unmarked`) e a operação é cancelada. ## **Outras garantias** Request Body ```json { "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff", "collateral_type": "others", "additional_documents": [ { "document_type": "others", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` ### **Tipos de Documentos** | Enum | Descrição | |-----------------|-----------------------------------| | `others` | Outros documentos. | --- ## **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `collateral_document_key` * | string | Chave do instrumento de Garantia. | Sim | | `collateral_type` * | string | Tipo do collateral. | **[Enumeradores collateral_type](#enumeradores-collateral_type)** | | `collateral_data` | object | Estrutura de metadados relacionados ao collateral. | Sim | | `additional_documents` | list | Documentos relacionados ao collateral. | - | ### **additional_documents list** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `document_key` * | string | Chave do instrumento de Garantia. | Sim | | `document_type` * | string | Tipo do documento da Garantia. | Sim | ### **Enumeradores collateral_type** | Enum | Descrição | |-----------------|-----------------------------------| | `fiduciary_alienation_property` | Alienação fiduciária de imóvel. | | `fiduciary_alienation_vehicle` | Alienação fiduciária de veículo. | | `fiduciary_alienation_aircraft` | Alienação fiduciária de aeronave. | | `fiduciary_alienation_equipment` | Alienação fiduciária de equipamentos/produtos/Estoque. | | `fiduciary_alienation_artwork` | Alienação fiduciária de obras de arte. | | `fiduciary_alienation_securities` | Alienação fiduciária de títulos e valores mobiliários. | | `fiduciary_assignment_shares` | Alienação fiduciária/Penhor de Ações/Cotas. | | `fiduciary_assignment_credit_rights` | Alienação fiduciária de diretos creditórios. | | `mortgage_property` | Hipoteca de imóveis. | | `mortgage_ship` | Hipoteca de embarcações. | | `guarantor` | Aval. | | `surety` | Fiador. | | `bank_surety` | Fiança Bancária. | | `card_receivables` | Recebiveis de cartão. | | `stock_guarantee` | Garantia de estoque. | | `monitoring_guarantee` | Monitoramento de garantias. | | `vehicle_stock` | Garantia de estoque de veículos (Floor Plan). Não utiliza `collateral_document_key`/`additional_documents` — veja [Garantia de estoque de veículos (Floor Plan)](#garantia-de-estoque-de-veículos-floor-plan). | | `others` | Outras garantias. | --- # Remoção de Garantia na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia Este endpoint permite a **remoção de garantias** associadas a uma operação. --- ## **Remoção de Collateral (DELETE)** ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral/ COLLATERAL-KEY MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `COLLATERAL-KEY` * | string | Chave única do collateral a ser removido (UUID v4). | 36 | ## **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Envio de documentos URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento Este endpoint permite o envio de **documentos** associados a uma operação. Tais documentos podem ser utilizados no sistema de garantias para realizar a adição de documentos acessórios, além do instrumento da garantia em si. --- ## **Envio de Documento (POST)** ## **Request** ENDPOINT /commercial_paper/upload MÉTODO POST Request Body ```json { "document_base64": "sringb64", } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------|----------|------------------------------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ## **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|----------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento adicionado (UUID v4). | 36 | --- --- # Cadastro e Remoção de Metadata na Operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao Este conjunto de endpoints permite o cadastro e a remoção de metadados em uma operação. --- ## **Cadastro de Metadata na Operação (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | Chave do metadado. | 255 | | `metadata_value` * | string | Valor do metadado. | 1023 | ### **Response** STATUS 201 Response Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | Chave do metadado. | 255 | | `metadata_value` * | string | Valor do metadado. | 1023 | --- ## **Remoção de Metadata na Operação (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "metadata_key": "custom_meta_field", "metadata_value": "custom_meta_value" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|--------------------------------------|-----------------| | `metadata_key` * | string | Chave do metadado. | 255 | | `metadata_value` * | string | Valor do metadado. | 1023 | --- ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Envio e Remoção de Documentos de Representantes de Partes Relacionadas URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento Este conjunto de endpoints permite o envio e a remoção de documentos associados a representantes de partes relacionadas a uma operação. --- ## **Envio de Documento do Representante (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36 | Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|-----------------------------------------------------------------|-----------------| | `document_base64` * | string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | ## **Response** STATUS 201 Response Body **Cenário 1: Validação Automática (Sucesso no OCR)** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **Significado**: O documento foi processado e validado automaticamente pelo nosso OCR. **Cenário 2: Verificação Manual Necessária** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnh", "ocr_key": null } ``` **Significado**: O documento não pôde ser validado automaticamente pelo OCR e foi encaminhado para nossa fila de verificação manual. :::warning Atenção A resposta para requisições bem-sucedidas (sucesso no envio) apresenta dois comportamentos distintos, dependendo do resultado da validação automática (OCR). ::: ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|----------------------------------------------|-----------------| | `document_key` * | string | Identificador único do documento enviado. | 36 | | `document_type` * | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- ## **Remoção de Documento do Representante (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36 | | `DOCUMENT-KEY` * | string | Chave única do documento a ser removido. | 36 | ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** ### **Enumeradores document_type** | Enum | Descrição | |---------------------------|-----------------------------------------| | `proof_of_address` | Comprovante de Endereço. | | `letter_of_attorney` | Procuração. | | `company_statute` | Estatuto da Empresa. | | `cnh` | Carteira Nacional de Habilitação (CNH). | | `cnh_front` | Frente da CNH. | | `cnh_back` | Verso da CNH. | | `cnh_digital` | CNH Digital. | | `rg_front` | Frente do RG. | | `rg_back` | Verso do RG. | --- # Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes Este conjunto de endpoints permite o envio e a remoção de grupos de assinantes associados a representantes de partes relacionadas a uma operação. --- ## **Envio de Grupo de Assinantes (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36 | Request Body ```json { "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "12345678901", "email": "joao.silva@example.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "98765432100", "email": "maria.souza@example.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|--------------------------------------------------------|-----------------| | `minimum_required_signers` * | integer | Número mínimo de assinantes necessários no grupo. | - | | `signers` * | array | Lista de assinantes do grupo. | **[Objeto signers](#objeto-signers)** | --- ### **Objeto signers** | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------------|----------|-------------------------------------------------|-----------------| | `name` * | string | Nome completo do assinante. | 255 | | `document_number` * | string | CPF do assinante (11 dígitos). | 11 | | `email` * | string | Endereço de e-mail do assinante. | 1023 | | `phone_number` * | string | Número de telefone do assinante, incluindo DDI. | 20 | | `is_group_mandatory` * | boolean | Indica se o assinante é obrigatório. | - | ## **Response** STATUS 201 Response Body ```json { "signer_group_key": "123e4567-e89b-12d3-a456-426614174000", "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "12345678901", "email": "joao.silva@example.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "98765432100", "email": "maria.souza@example.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|-------------------------------------------------|-----------------| | `signer_group_key` * | string | Chave única do grupo de assinantes (UUID v4). | 36 | | `minimum_required_signers` * | integer | Número mínimo de assinantes no grupo. | - | | `signers` * | array | Lista de assinantes do grupo. | **[Objeto signers](#objeto-signers)** | --- ## **Remoção de Grupo de Assinantes (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group/ SIGNER-GROUP-KEY MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------|--------|----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36 | | `SIGNER-GROUP-KEY` * | string | Chave única do grupo de assinantes. | 36 | ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Cadastro e Remoção de Partes Relacionadas de um documento específico URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento Este conjunto de endpoints permite o cadastro e a remoção de partes relacionadas a uma operação de um documento específico da operação. --- ## **Adicionar Parte Relacionada ao documento (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document /FORMALIZATION-DOCUMENT-KEY /related_party MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `FORMALIZATION-DOCUMENT-KEY` * | string | Chave única do documento da operação (UUID v4). | 36 | Request Body ```json { "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `related_party_key` * | string | Chave da Parte Relacionada | | 36 ## **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** ## **Remoção de Parte Relacionada (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document/ FORMALIZATION-DOCUMENT-KEY /related_party MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `FORMALIZATION-DOCUMENT-KEY` * | string | Chave única do documento da da operação (UUID v4). | 36 | Request Body ```json { "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Cadastro e Remoção de Partes Relacionadas URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada Este conjunto de endpoints permite o cadastro e a remoção de partes relacionadas a uma operação. :::warning Todas as partes relacionadas são adicionadas por padrão ao Termo Constitutivo (**commercial_paper**), caso deseje adicionar essa parte relacionada à um documento específico, preencher o campo **related_document_key** com a chave do documento desejado. ::: --- ## **Cadastro de Parte Relacionada (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | :::info Importante **Atenção ao tipo de pessoa ao montar o payload:** - **Pessoa Física (PF)**: `"person_type": "natural"` - **Pessoa Jurídica (PJ)**: `"person_type": "legal"` ::: Request Body - Pessoa Física (PF) ```json { "person_type": "natural", "name": "João da Silva", "document_number": "123.731.320-10", "street": "Rua dos Exemplos", "neighborhood": "Centro", "number": "123", "postal_code": "29173-509", "city": "São Paulo", "state": "SP", "role_type": "guarantor", "marital_status": "single", "birthdate": "2000-01-01", "mother_name": "Mãe do João", "father_name": "Pai do João", "occupation": "Desenvolvedor", "is_pep": false } ``` Request Body - Pessoa Jurídica (PJ) ```json { "person_type": "legal", "name": "João da Silva", "trading_name": "Padaria do João LTDA", "document_number": "92.123.456/0001-00", "street": "Rua dos Exemplo", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "guarantor", "cnae_code": "12.34-5-67", "company_type": "ltda", "foundation_date": "2025-01-01" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `person_type` * | string | Tipo da pessoa. | **[Enumeradores person_type](#enumeradores-person_type)** | | `name` * | string | Nome da parte relacionada. | 255 | | `document_number` * | string | CPF (formato "XXX.XXX.XXX-XX") ou CNPJ (formato "XX.XXX.XXX/XXXX-XX"). | 14 | | `street` * | string | Logradouro do endereço. | 500 | | `neighborhood` | string | Bairro do endereço. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (formato "XXXXX-XXX"). | 8 | | `city` * | string | Cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `role_type` * | string | Papel da parte relacionada. | **[Enumeradores role_type](#enumeradores-role_type)** | | `related_document_key` | string | Chave de identificação do documento (UUIDv4) | 36 ### **Enumeradores person_type** | Enum | Descrição | | ----------- | ---------------- | | `natural` | Pessoa Física | | `legal` | Pessoa Jurídica | ### **Campos adicionais para Pessoa Física** | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------------- | ------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------- | | `document_identification_number` | string | RG (sem formatação) | 20 | | `marital_status` | string | Estado civil. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system` | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `birthdate` | string | Data de nascimento (YYYY-MM-DD). | - | | `nationality` | string | Nacionalidade. | 255 | | `mother_name` | string | Nome da mãe. | 255 | | `father_name` | string | Nome do pai. | 255 | | `occupation` | string | Ocupação. | 255 | | `is_pep` * | boolean | Indica se a parte relacionada é uma Pessoa Politicamente Exposta (PEP). | | ### **Campos adicionais para Pessoa Jurídica** | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | -------------------------------------- | -------------------------------------------------------------- | | `trading_name` * | string | Nome fantasia da empresa. | 1023 | | `cnae_code` * | string | Código CNAE da empresa (10 dígitos). | 10 | | `company_type` * | string | Tipo da empresa. | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date` * | string | Data de fundação (YYYY-MM-DD). | - | ### **Enumeradores role_type** | Enum | Descrição | | -------------------------- | ------------------------ | | `cosigner` | Avalista | | `fiduciary_debtor` | Devedor Fiduciário | | `solidary_debtor` | Devedor Solidário | | `surety` | Garantidor | | `guarantor` | Fiador | | `bonafide_depositary` | Fiel Depositário | | `intervening_guarantor` | Interveniente Fiador | | `intervening_consentor` | Interveniente Anuente | | `intervening_discharger` | Interveniente Quitante | | `assignor` | Cedente | | `endorser` | Endossante | | `consulting` | Consultor | | `fund_administrator` | Administrador do Fundo | | `fund_representative` | Representante do Fundo | | `company_representative` | Representante da Empresa | | `attestant` | Testemunha | | `debtor` | Devedor | | `bestowal` | Outorga Uxória | | `manager` | Gestor | ### Enumeradores marital_status | Enum | Descrição | | ----------- | ---------------- | | `single` | Solteiro(a) | | `married` | Casado(a) | | `divorced` | Divorciado(a) | | `widowed` | Viúvo(a) | | `separated` | Separado(a) | | `stable_union`| União estável | ### Enumeradores property_system | Enum | Descrição | | --------------------------------- | -------------------------------------- | | `total_communion_of_goods` | Comunhão Total de Bens | | `partial_communion_of_goods` | Comunhão Parcial de Bens | | `total_separation_of_goods` | Separação Total de Bens | | `final_participation_of_acquisitions` | Participação Final nos Aquestos | | `compulsory_separation_of_goods` | Separação Obrigatória de Bens | ### Enumeradores company_type | Enum | Descrição | | ------------------- | ---------------------------- | | `ltda` | Sociedade Limitada | | `sa` | Sociedade Anônima | | `cop` | Cooperativa | ## **Response** STATUS 201 Response Body ```json { "related_party_key": "c642a117-ea6e-4da7-a8fd-451f556e5c38", "name": "João da Silva", "document_number": "12345678901", "role_type": "guarantor", "is_active": true, "updated_at": null, "person_type": "natural", "street": "Rua dos Exemplo", "neighborhood": "Centro", "number": "123", "postal_code": "01001000", "city": "São Paulo", "state": "SP", "signer_group_list": [], "document_list": [], "contact_information_list": [] } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------------- | ------- | ---------------------------------------------------- | ------------------------------------------------------------ | | `related_party_key` * | string | Chave única da parte relacionada. | 36 | | `name` * | string | Nome da parte relacionada. | 255 | | `document_number` * | string | CPF/CNPJ da parte relacionada. | 14 | | `role_type` * | string | Papel da parte relacionada. | 50 | | `is_active` * | boolean | Indica se está ativa. | - | | `updated_at` | string | Data da última atualização (YYYY-MM-DD HH:mm:ss). | - | | `person_type` * | string | Tipo da pessoa. | **[Enumeradores person_type](#enumeradores-person_type)** | | `street` * | string | Logradouro. | 500 | | `neighborhood` | string | Bairro. | 100 | | `number` * | string | Número. | 10 | | `postal_code` * | string | CEP (somente números). | 8 | | `city` * | string | Cidade. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | --- ## **Remoção de Parte Relacionada (DELETE)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY MÉTODO DELETE ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | | `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada. | 36 | ### **Response** STATUS 204 **Nenhum conteúdo é retornado no corpo da resposta.** --- # Cadastro de Operação de Nota Comercial URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao Este endpoint permite criar uma nova operação de nota comercial com base nos dados financeiros e de investidores. --- ## **Request** ENDPOINT /commercial_paper/operation MÉTODO POST Request Body ```json { "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_bank_account": { "account_number": "4464541", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" }, "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "issue_date": "2025-01-23", "signature_method": "certifiqi", "financial": { "interest_type": "pre_price_days", "financial_base_date": "2025-01-23", "released_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee" } ] } } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------------- | ------ | ------------------------------------------------------ | ---------------------------------------------------------------- | | `issuer_key` * | string | Chave única do emissor. | - | | `issuer_bank_account` * | object | Conta bancária do emissor. | **[Objeto issuer_bank_account](#objeto-issuer_bank_account)** | | `investors` * | array | Lista de investidores envolvidos. | **[Objeto investors](#objeto-investors)** | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `financial` * | object | Dados financeiros da operação. | **[Objeto financial](#objeto-financial)** | | `third_party_disbursement` | object | Instrução de desembolso para terceiro. Opcional; requer habilitação prévia. | **[Objeto third_party_disbursement](#objeto-third_party_disbursement)** | ### **Objeto issuer_bank_account** | Campo | Tipo | Descrição | | --------------------------------------- | ------ | ------------------------------------------ | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` * | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`). | ### **Objeto investors** | Campo | Tipo | Descrição | | ----------------------------- | ------ | ------------------------------ | | `investor_key` * | string | Chave única do investidor. | | `subscription_percentage` * | number | Percentual de subscrição. | | `bank_account` * | object | Conta bancária do investidor. | ### **Objeto financial** | Campo | Tipo | Descrição | | ---------------------------- | ------- | -------------------------------------------- | | `interest_type` * | string | Tipo de juros. | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `released_amount` | number | Valor liberado. | | `issue_amount` | number | Valor de Emissão. | | `number_of_installments` * | integer | Número de parcelas. | | `installments` | array | **[Objeto installments](#objeto-installments)** | | `prefixed_interest_rate` * | object | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fine_delay_rate` * | object | Taxa de multa por atraso. | | `contract_fine_rate` * | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | :::warning Atenção O **objeto financial** deve conter uma combinação válida de parâmetros para ser processado. As combinações aceitas são: Valor de Emissão/Liberado + Taxa de Juros, Valor de Emissão/Liberado + Valor por Parcela, Valor por Parcela + Taxa de Juros, Valor de Emissão/Liberado + Taxa de Juros + Percentual de Amortização por Parcela. ::: ### Objeto installments | Campo | Tipo | Descrição | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------| | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | | `amount` | number | Valor total da parcela. | | `principal_amortization_percentage` | number | Valor percentual amortizado do principal. | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------| | `interest_base` * | string | Base de cálculo para os juros. | - | | `daily_rate` | number | Taxa de juros diária aplicada. | - | | `monthly_rate` | number | Taxa de juros mensal aplicada. | - | | `annual_rate` | number | Taxa de juros anual aplicada. | - | ### **Objeto third_party_disbursement** Instrução opcional que indica que o valor liberado será pago a um beneficiário terceiro, e não à conta de liquidação do emissor. O objeto não aceita campos além dos listados (`additionalProperties: false`) e as duas trilhas — TED e boleto — são mutuamente exclusivas. | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | `payment_method` * | string | Trilha de pagamento utilizada no desembolso (`ted`, `bank_slip`, `pix`). | - | | `target_account` | object | Conta bancária do beneficiário. Obrigatório quando `payment_method` é `ted`; proibido nas demais trilhas. | **[Objeto target_account](#objeto-target_account)** | | `digitable_line` | string | Linha digitável do boleto do beneficiário, somente dígitos (padrão `^[0-9]{47}$`). Obrigatório quando `payment_method` é `bank_slip`; proibido nas demais trilhas. | 47 | | `pix_key` | string | Chave Pix do beneficiário, **sem formatação** para CPF e CNPJ. Obrigatório quando `payment_method` é `pix`; proibido nas demais trilhas. | 77 | | `pix_key_type` | string | Tipo declarado da chave Pix (`cpf`, `cnpj`, `phone`, `email`, `evp`). Obrigatório quando `payment_method` é `pix`; proibido nas demais trilhas. | - | | `beneficiary` | object | Qualificação do terceiro beneficiário. **Obrigatório** quando `payment_method` é `pix`; opcional em `ted` e `bank_slip`. | **[Desembolso para terceiro](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro)** | :::info Recurso sob habilitação O envio de `third_party_disbursement` requer habilitação prévia junto à QI Tech; sem ela a criação é recusada com `COM000062`. As regras completas — incluindo a conferência do valor do boleto, os tipos de chave Pix e os campos do objeto `beneficiary` — estão em [Desembolso para terceiro na operação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro). ::: ### **Objeto target_account** | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- | --------------- | | `account_branch` * | string | Agência da conta bancária do beneficiário, somente dígitos (exatamente 4). | 4 | | `account_number` * | string | Número da conta bancária do beneficiário, somente dígitos (1 a 20). | 20 | | `account_digit` * | string | Dígito da conta bancária do beneficiário, somente dígitos (exatamente 1). | 1 | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira do beneficiário, somente dígitos (exatamente 8). Define o roteamento da TED. | 8 | | `financial_institution_code_number` | string ou `null` | Código da instituição financeira do beneficiário, somente dígitos (3). Opcional e não utilizado no roteamento. | 3 | | `account_type` * | string | Tipo da conta do beneficiário (`checking`, `savings`, `salary`, `payment`). | - | | `owner_document_number` * | string | CPF ou CNPJ do titular da conta, **formatado** (`000.000.000-00` ou `00.000.000/0000-00`). Os dígitos verificadores são conferidos. | 18 | | `owner_name` * | string | Nome do titular da conta (1 a 50 caracteres). | 50 | ### Enumeradores signature_method | Valor | Descrição | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | | `client_side` | Os documentos são assinados fora da plataforma da QI Tech e enviados pelo endpoint de **[envio de documentos assinados](/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados)**. Nenhuma URL de assinatura é gerada. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "in_filling", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "financial": { ... } } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Chave única do tenant. | | `operation_key` * | string | Chave única da operação. | | `operation_status` * | string | Status da operação. | | `issuer_key` * | string | Chave única do emissor. | | `issuer_name` * | string | Nome do emissor. | | `issuer_document_number` * | string | Documento do emissor. | | `financial` * | object | **[Objeto financial](#objeto-financial-response)** | ### Objeto financial response | Campo | Tipo | Descrição | Caracteres Máx. | | ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate-response)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-installments-response)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto prefixed_interest_rate response | Campo | Tipo | Descrição | | ------------------- | ------ | ------------------------------- | | `interest_base` * | string | Base de cálculo para os juros. | | `monthly_rate` | number | Taxa de juros mensal aplicada. | | `daily_rate` | number | Taxa de juros diária aplicada. | | `annual_rate` | number | Taxa de juros anual aplicada. | ### Objeto fees | Campo | Tipo | Descrição | | ----------------- | ------ | ---------------------------------------- | | `amount` * | number | Valor percentual da taxa. | | `fee_amount` * | number | Valor monetário correspondente à taxa. | | `amount_type` * | string | Tipo do valor da taxa. | | `fee_type` * | string | Tipo da taxa. | | `type` * | string | Destinatário da taxa. | ### Objeto installments response | Campo | Tipo | Descrição | | --------------------------------------- | ------- | ----------------------------------------------------- | | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Desembolso para terceiro na operação URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro Este endpoint define ou substitui a instrução de desembolso para terceiro de uma operação, indicando que o valor liberado será pago a um beneficiário terceiro (por exemplo, um fornecedor) e não à conta de liquidação do emissor. :::info Recurso sob habilitação O desembolso para terceiro não vem habilitado por padrão. Solicite a habilitação à QI Tech antes de integrar — sem ela, a requisição é recusada com `COM000062`. ::: :::warning Substituição integral e janela de alteração A requisição **substitui a instrução inteira** — não há atualização parcial de campos. A instrução só pode ser definida ou alterada enquanto a operação está no status `in_filling`; fora desse status a requisição é recusada com `COM000010`. ::: --- ## **Desembolso para terceiro na operação (PUT)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /third_party_disbursement MÉTODO PUT ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body — 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** O corpo não aceita campos além dos listados (`additionalProperties: false`). As três trilhas são mutuamente exclusivas e a exclusividade é garantida pelo schema: enviar o campo de uma trilha junto de outra, omitir o campo obrigatório da trilha escolhida ou enviar um campo desconhecido retorna `QIT000001`. | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | `payment_method` * | string | Trilha de pagamento utilizada no desembolso. | **[Enumeradores payment_method](#enumeradores-payment_method)** | | `target_account` | object | Conta bancária do beneficiário. Obrigatório quando `payment_method` é `ted`; proibido nas demais trilhas. | **[Objeto target_account](#objeto-target_account)** | | `digitable_line` | string | Linha digitável do boleto do beneficiário, somente dígitos (padrão `^[0-9]{47}$`). Obrigatório quando `payment_method` é `bank_slip`; proibido nas demais trilhas. | 47 | | `pix_key` | string | Chave Pix do beneficiário, **sem formatação** para CPF e CNPJ. Obrigatório quando `payment_method` é `pix`; proibido nas demais trilhas. | 77 | | `pix_key_type` | string | Tipo declarado da chave Pix. Obrigatório quando `payment_method` é `pix`; proibido nas demais trilhas. | **[Enumeradores pix_key_type](#enumeradores-pix_key_type)** | | `beneficiary` | object | Qualificação do terceiro beneficiário. **Obrigatório** quando `payment_method` é `pix`; opcional em `ted` e `bank_slip`. | **[Objeto beneficiary](#objeto-beneficiary)** | ### **Enumeradores payment_method** | Valor | Descrição | | ------------- | ------------------------------------------------------------------------------ | | `ted` | Pagamento por TED para a conta informada em `target_account`. | | `bank_slip` | Pagamento do boleto informado em `digitable_line`. | | `pix` | Pagamento por Pix para a chave informada em `pix_key`. | ### **Enumeradores pix_key_type** | Valor | Descrição | | -------- | ---------------------------------------------------------------- | | `cpf` | CPF, 11 dígitos, sem pontuação. | | `cnpj` | CNPJ, 14 dígitos, sem pontuação. | | `phone` | Telefone no formato `+55` seguido de 10 ou 11 dígitos. | | `email` | Endereço de e-mail, até 77 caracteres. | | `evp` | Chave aleatória (UUID minúsculo). | O **formato** da chave é validado pelo schema conforme o `pix_key_type` declarado — fora do formato, `QIT000001`. Para `cpf` e `cnpj`, os **dígitos verificadores** são conferidos depois: formato certo com dígito verificador errado retorna `COM000071`. ### **Objeto target_account** | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `account_branch` * | string | Agência da conta bancária do beneficiário, somente dígitos (exatamente 4). | 4 | | `account_number` * | string | Número da conta bancária do beneficiário, somente dígitos (1 a 20). | 20 | | `account_digit` * | string | Dígito da conta bancária do beneficiário, somente dígitos (exatamente 1). | 1 | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira do beneficiário, somente dígitos (exatamente 8). Define o roteamento da TED. | 8 | | `financial_institution_code_number` | string ou `null` | Código da instituição financeira do beneficiário, somente dígitos (3). Opcional e não utilizado no roteamento. | 3 | | `account_type` * | string | Tipo da conta do beneficiário. | **[Enumeradores account_type](#enumeradores-account_type)** | | `owner_document_number` * | string | CPF ou CNPJ do titular da conta, **formatado** (`000.000.000-00` ou `00.000.000/0000-00`). Os dígitos verificadores são conferidos. | 18 | | `owner_name` * | string | Nome do titular da conta (1 a 50 caracteres). | 50 | ### **Enumeradores account_type** | Valor | Descrição | | ------------ | ---------------------- | | `checking` | Conta corrente. | | `savings` | Conta poupança. | | `salary` | Conta salário. | | `payment` | Conta de pagamento. | ### **Objeto beneficiary** Identifica o terceiro que recebe o valor. Obrigatório na trilha `pix` — uma chave Pix não diz quem é o recebedor — e opcional em `ted` e `bank_slip`. Viaja junto da instrução, é assinado com a operação e é usado na ata que formaliza o pagamento ao terceiro. **Apenas `name` e `document_number` são obrigatórios.** Todos os demais campos são opcionais e servem para enriquecer a qualificação do beneficiário na ata. | Campo | Tipo | Descrição | Obrigatório | | ----- | ---- | ----------- | ----------- | | `person_type` | string | `natural` (pessoa física) ou `legal` (pessoa jurídica). | Opcional | | `name` * | string | Nome do beneficiário. | Sempre | | `document_number` * | string | CPF ou CNPJ **formatado** (`000.000.000-00` ou `00.000.000/0000-00`). | Sempre | | `street` | string | Logradouro. | Opcional | | `number` | string | Número do endereço. | Opcional | | `postal_code` | string | CEP no formato `00000-000`. | Opcional | | `city` | string | Cidade. | Opcional | | `state` | string | UF, duas letras maiúsculas. | Opcional | | `is_pep` | boolean | Indica se é Pessoa Politicamente Exposta. | Opcional | | `trading_name` | string | Nome fantasia. | Opcional | | `cnae_code` | string | CNAE no formato `00.00-0-00`. | Opcional | | `company_type` | string | Tipo de empresa. | Opcional | | `foundation_date` | string | Data de fundação (`AAAA-MM-DD`). | Opcional | | `neighborhood` | string | Bairro. | Opcional | | `complement` | string | Complemento do endereço. | Opcional | | `document_identification_number` | string | RG. | Opcional | | `marital_status` | string | Estado civil. | Opcional | | `property_system` | string | Regime de bens. | Opcional | | `birthdate` | string | Data de nascimento (`AAAA-MM-DD`). | Opcional | | `nationality` | string | Nacionalidade. | Opcional | | `mother_name` | string | Nome da mãe. | Opcional | | `father_name` | string | Nome do pai. | Opcional | | `occupation` | string | Ocupação. | Opcional | :::tip Quanto mais você enviar, mais completa fica a ata Com `person_type`, a ata ganha a **qualificação** do beneficiário. Com `street`, `number`, `postal_code`, `city` e `state` — os cinco juntos —, ganha o **endereço** formatado. Enviando só nome e documento, a ata nomeia o beneficiário sem qualificar nem endereçar: nada falha, o documento apenas fica mais enxuto. ::: :::warning TED — confira o ISPB A instituição de destino da TED é determinada pelo `financial_institution_ispb`. Um ISPB incorreto envia o dinheiro para a instituição errada mesmo que o `financial_institution_code_number` esteja correto. ::: :::warning Boleto — o valor precisa bater com o valor liberado O valor do boleto é lido dos **10 últimos dígitos da linha digitável, em centavos**, e precisa ser igual ao `financial.released_amount` da operação. Qualquer diferença é recusada com `COM000061`. Como o `released_amount` calculado difere do valor solicitado por causa das taxas, o caminho prático é: criar a operação, ler o `released_amount` da resposta e só então anexar um boleto daquele valor exato. **Não reescreva o valor de uma linha digitável real** — isso invalida seus dígitos verificadores e o boleto deixa de ser pagável. Uma nota comercial paga exatamente um beneficiário, pelo valor integral: split de pagamento não é suportado. ::: ## **Response** STATUS 200 A resposta traz o objeto completo da operação, na mesma forma retornada pela [consulta de operação por chave](/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** | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------- | | `tenant_key` * | string | Chave única do tenant. | | `operation_key` * | string | Chave única da operação. | | `operation_status` * | string | Status da operação. | | `issuer_key` * | string | Chave única do emissor. | | `issuer_name` * | string | Nome do emissor. | | `issuer_document_number` * | string | Documento do emissor. | | `financial` * | object | Dados financeiros da operação. | :::info A instrução aparece no objeto da operação como `third_party_disbursement`, na mesma forma em que foi enviada. Quando a operação não tem desembolso para terceiro, a chave é **omitida** da resposta — não retorna como `null`. ::: --- ## **Erros** Os códigos abaixo estão descritos também no [catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). | Código | HTTP | Descrição | | ---------- | ---- | -------------------------------------------------------------------------------------------------------- | | `QIT000001` | 400 | Falha de schema — por exemplo, `payment_method` ausente ou fora do enum, combinação inválida entre `target_account` e `digitable_line`, `digitable_line` fora do padrão de 47 dígitos, `pix_key` fora do formato do seu `pix_key_type`, ou campo desconhecido no corpo. | | `COM000010` | 400 | Operação não pode ser atualizada fora do status `in_filling`. | | `COM000061` | 400 | Valor do boleto diferente do `released_amount` da operação. | | `COM000062` | 400 | Tenant não habilitado para desembolso a terceiro. | | `COM000063` | 400 | Documento do beneficiário inválido. | | `COM000071` | 400 | `pix_key` de `cpf`/`cnpj` com dígito verificador inválido. | | `COM000007` | 404 | Operação não encontrada. | | `COM000008` | 403 | Operação não pertence ao tenant solicitante. | --- # Campos Extras (Extra Fields) URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields Este conjunto de endpoints permite consultar os campos extras disponíveis em um template de documento e salvar valores personalizados para esses campos em uma operação. :::warning Para utilizar os campos extras, é necessário que o template do documento já tenha sido definido. Caso contrário, gere uma pré-visualização de minuta antes de utilizar estes endpoints. ::: :::info Importante Os campos extras são organizados por tipo de documento (`document_type`). Ao salvar campos extras via POST, os valores anteriores para aquele `document_type` são **substituídos integralmente** — não é feito merge com valores existentes. ::: --- ## **Consulta de Campos Extras Disponíveis (GET)** Retorna os campos extras disponíveis no template associado ao tipo de documento da operação. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | ### **Query Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `document_type` * | string | Tipo do documento. | **[Enumeradores document_type](#enumeradores-document_type)** | ### **Response** STATUS 200 Response Body ```json { "operation_key": "550e8400-e29b-41d4-a716-446655440000", "document_type": "commercial_paper", "template_key": "660e8400-e29b-41d4-a716-446655440001", "extra_fields": [ { "field_key": "warranty_description", "field_label": "Descrição da Garantia", "field_type": "string" }, { "field_key": "special_conditions", "field_label": "Condições Especiais", "field_type": "string" }, { "field_key": "additional_clause", "field_label": "Cláusula Adicional", "field_type": "string" } ] } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `document_type` * | string | Tipo do documento consultado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `template_key` * | string | Chave única do template associado (UUID v4). | 36 | | `extra_fields` * | array | Lista de campos extras disponíveis no template. | - | ### **Campos do objeto extra_fields** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `field_key` * | string | Identificador único do campo extra. | 255 | | `field_label` * | string | Rótulo descritivo do campo extra. | 255 | | `field_type` * | string | Tipo de dado do campo extra (ex: `string`). | 50 | --- ## **Salvar Campos Extras (POST)** Salva os valores dos campos extras para um tipo de documento específico em uma operação. Os valores enviados substituem integralmente os campos extras anteriores para o `document_type` informado. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | ------------------------------------- | ---------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "document_type": "commercial_paper", "extra_fields": { "warranty_description": "Garantia prestada pelo avalista", "special_conditions": "Condição especial de vencimento antecipado", "additional_clause": "Cláusula de cross default" } } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `document_type` * | string | Tipo do documento. | **[Enumeradores document_type](#enumeradores-document_type)** | | `extra_fields` * | object | Objeto contendo os campos extras e seus valores. As chaves devem corresponder aos `field_key` retornados na consulta GET. Todos os valores devem ser strings. | - | :::warning As chaves enviadas no objeto `extra_fields` devem corresponder exatamente aos `field_key` disponíveis no template. Chaves inválidas resultarão em erro. ::: ### **Response** STATUS 201 Response Body ```json { "operation_key": "550e8400-e29b-41d4-a716-446655440000", "document_type": "commercial_paper", "extra_fields": { "warranty_description": "Garantia prestada pelo avalista", "special_conditions": "Condição especial de vencimento antecipado", "additional_clause": "Cláusula de cross default" } } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | --------------------------------------------------------------- | ---------------- | | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `document_type` * | string | Tipo do documento. | **[Enumeradores document_type](#enumeradores-document_type)** | | `extra_fields` * | object | Objeto contendo os campos extras salvos com seus respectivos valores. | - | --- ## **Enumeradores document_type** | Enum | Descrição | | -------------------- | ---------------------- | | `commercial_paper` | Termo Constitutivo | | `adhesion_term` | Termo de Adesão | --- ## **Erros** | Código | HTTP | Descrição | | ---------- | ---- | -------------------------------------------------------------------------------------------------------- | | `COM000007` | 404 | Operação não encontrada. | | `COM000008` | 403 | Operação não pertence ao tenant solicitante. | | `COM000044` | 400 | Template não definido para o tipo de documento. Gere uma pré-visualização de minuta antes de prosseguir. | | `COM000045` | 400 | Chaves de campos extras não disponíveis no template. | --- # Envio do log de aceite do cliente URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite Este endpoint anexa à operação um PDF com o log de aceite do cliente — o registro das evidências de que o cliente final aceitou as condições da operação. Ele existe para o fluxo de **auto-assinatura**: quando a QI Tech assina o Termo Constitutivo em nome do emissor com o certificado privado liberado na CertifiQI, nenhum link de assinatura é gerado para o cliente, e o log de aceite é o que documenta o consentimento dele. :::info Envio opcional O envio **não é obrigatório** e nenhuma etapa da emissão depende dele. A operação segue para análise, assinatura e emissão normalmente sem o log de aceite — o documento é guardado como evidência anexada à operação. ::: :::warning Exige emissor com auto-assinatura habilitada O envio só é aceito quando o emissor da operação tem a habilitação de auto-assinatura em `enabled` no sistema de emissores. Emissor sem habilitação, ou com habilitação em qualquer outro status (`pending_term_generation`, `pending_signature`, `reproved`, `canceled`), é recusado com `COM000077` e nada é armazenado. O envio também só é aceito enquanto a operação está no status `in_filling`; fora desse status a requisição é recusada com `COM000010`. ::: --- ## **Envio do log de aceite (POST)** ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /acceptance_log MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ------------------------------------ | --------------- | | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "document_base64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..." } ``` ### **Request Body Params** O corpo não aceita campos além do listado (`additionalProperties: false`) — um campo desconhecido, ou a ausência de `document_base64`, retorna `QIT000001`. | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------ | -------------------------------------------------------------------------------------------- | --------------- | | `document_base64` * | string | PDF do log de aceite do cliente, codificado em base64, sem prefixo `data:` e sem quebras de linha. | — | ## **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** | Campo | Tipo | Descrição | | ----------------- | ------ | ----------------------------------------------------------------- | | `document_key` * | string | Chave única do documento gerada neste envio (UUID v4). | | `operation_key` * | string | Chave única da operação à qual o documento foi anexado. | | `created_at` * | string | Data e hora do envio, em UTC. | :::info Como conferir o que ficou anexado A operação passa a expor o campo `acceptance_log_document_key` na [consulta de operação por chave](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave), preenchido a partir do envio mais recente. Antes do primeiro envio o campo retorna `null`. ::: :::warning Reenvio substitui o documento anterior Um novo envio para a mesma operação gera um novo `document_key` e passa a ser o log de aceite vigente — a referência anterior deixa de ser apontada pela operação. Não há atualização parcial e não há endpoint de remoção. ::: --- ## **Erros** Os códigos abaixo estão descritos também no [catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). | Código | HTTP | Descrição | | ----------- | ---- | ----------------------------------------------------------------------------------------------- | | `QIT000001` | 400 | Falha de schema — `document_base64` ausente ou campo desconhecido no corpo. | | `COM000010` | 400 | Operação não pode ser atualizada fora do status `in_filling`. | | `COM000077` | 400 | Emissor da operação não está habilitado para auto-assinatura. | | `COM000007` | 404 | Operação não encontrada. | | `COM000008` | 403 | Operação não pertence ao tenant solicitante. | --- # Cancelar Operação URL: /documentation/escrituracao/emissao-de-notas/cancelar-operacao Este endpoint permite alterar o status de uma operação para "cancelado", status final para caso em que a operação não será mais finalizada pelo cliente. --- ## Cancelar Operação (PATCH) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body ```json { "operation_status": "canceled" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |--------------------|----------|------------------------------------------------------------|-------------| | `operation_status` | string | Status da operação. Deve ser definido como `canceled`. | Sim | --- ### Response O corpo da resposta é um JSON completo da operação atualizado. --- --- # Consulta do Link dos contratos assinados via QI SIGN da Operação URL: /documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign Este endpoint permite consultar todos os documentos assinados de uma operação específica via QI SIGN, utilizando sua chave única. --- :::warning Atenção O link do contrato assinado tem validade de 24 horas. Após isso, é necessário renovar o link fazendo uma nova requisição pelo endpoint. ::: ## Consulta de Link Assinado da Operação (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signed_url MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce", "status": "signed", "documents": [ { "document_type": "ncom_pre_price", "signed_url": "https://qisign-dossiers.com/7bcf5868-784a-4356-85fb-dd72fd53cd4a.pdf", "signers": [] }, { "document_type": "adhesion_term", "signed_url": "https://qisign-dossiers.com/7bcf5868-784a-4356-85fb-dd72fd53cd4a.pdf", "signers": [] } ] } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `envelope_key` | string | Chave única do envelope (UUID v4). | 36 | | `status` | string | Status dos envelopes | [Enumeradores status](#enumeradores-operation-status) | `documents` | list | Lista de documentos do envelope | - | ### Objeto document | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_type` | string | Tipo do documento. | [Enumeradores document type](#enumeradores-document-type) | | `signed_url` | string | Url do contrato assinado para download | - | | `signers` | list | Lista de assinantes | - | ## **Enumeradores operation-status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `waiting_signature` | Aguardando assinaturas dos envolvidos. | | `signed` | Assinatura finalizada. | | `signature_rejected` | Assinatura rejeitada. | | `canceled` | Operação cancelada. | ## **Enumeradores document-type** | Enum | Descrição | |----------------------------------|------------------------------------------------------------------| | `contract` | Identificador do contrato. | | `ncom_pre_price` | Nota comercial Pre price. | | `ncom_pre_price_days` | Nota comercial Pre price days. | | `ncom_pre_sac` | Nota comercial Pre sac. | | `ncom_post_sac_cdi` | Nota comercial Pós sac vinculado ao CDI. | | `ncom_post_sac_ipca` | Nota comercial Pós sac vinculado ao IPCA. | | `ncom_post_sac_igpm` | Nota comercial Pós sac vinculado ao IGP-M. | | `ncom_post_price_cdi` | Nota comercial Pós price vinculado ao CDI. | | `ncom_post_price_ipca` | Nota comercial Pós price vinculado ao IPCA. | | `ncom_post_price_igpm` | Nota comercial Pós price vinculado ao IGP-M. | | `ncom_post_price_days_cdi` | Nota comercial Pós price days vinculado ao CDI. | | `ncom_post_price_days_ipca` | Nota comercial Pós price days vinculado ao IPCA. | | `ncom_post_price_days_igpm` | Nota comercial Pós price days vinculado ao IGP-M. | | `subscription_note` | Boletim de subscrição. | | `adhesion_term` | Termo de adesão. | --- # Consulta dos Links para assinatura via QI SIGN da Operação URL: /documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign Este endpoint permite consultar todos os links para assinatura de uma operação específica via QI SIGN, utilizando sua chave única. --- ## Consulta de Link para Assinatura da Operação (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signers MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | ### 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": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce", "status": "pending_signature", "documents": [ { "document_type": "adhesion_term", "signers": [ { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Emissor assinante", "email": "emissor@qitech.com.br", "status": "on_signature" }, { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Assinante QI CTVM", "email": "dtvm@qitech.com.br", "status": "on_signature" }, { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Assinante QI TECH", "email": "qi@qitech.com.br", "status": "on_signature" } ] }, { "document_type": "ncom_pre_price", "signers": [ { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Assinante QI TECH", "email": "qi@qitech.com.br", "status": "on_signature" }, { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Emissor assinante", "email": "emissor@qitech.com.br", "status": "on_signature" }, { "document_number": "145.736.070-56", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "name": "Assinante QI CTVM", "email": "dtvm@qitech.com.br", "status": "on_signature" } ] } ] } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `envelope_key` | string | Chave única do envelope (UUID v4). | 36 | | `status` | string | Status dos envelopes | [Enumeradores operation status](#enumeradores-operation-status) | `documents` | list | Lista de documentos do envelope | - | ### Objeto document | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_type` | string | Tipo do documento. | [Enumeradores document type](#enumeradores-document-type) | | `signers` | list | Lista de assinantes | - | ### Objeto signer | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `document_number` | string | Documento do assinante. | 18 | | `signature_url` | string | Link do assinante | - | | `status` | string | Status do assinante. | [Enumeradores status](#enumeradores-status) | | `name` | string | nome do assinante | - | | `email` | string | email do assinante | - | ## **Enumeradores operation-status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `waiting_signature` | Aguardando assinaturas dos envolvidos. | | `signed` | Assinatura finalizada. | | `signature_rejected` | Assinatura rejeitada. | | `canceled` | Operação cancelada. | ## **Enumeradores status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `on_signature` | Aguardando assinaturas dos envolvidos. | | `analyzed` | Assinatura completa via API. | | `signed` | Assinatura finalizada. | | `signature_rejected` | Assinatura rejeitada. | | `canceled` | Operação cancelada. | | `created` | Assinatura criada. | | `submitted` | Enviado para o assinante. | | `sending_sign_receipt` | Enviando dossiê simplificado da assinatura. | | `analyzing` | Assinantes em análise. | | `completed` | Assinatura completa. | | `expired` | Assinatura expirada. | | `removed` | Assinante removido. | | `failed_waiting_for_manual_fix` | Criação da assinatura falhou, ação manual da QI necessária. | ## **Enumeradores document-type** | Enum | Descrição | |----------------------------------|------------------------------------------------------------------| | `contract` | Identificador do contrato. | | `ncom_pre_price` | Nota comercial Pre price. | | `ncom_pre_price_days` | Nota comercial Pre price days. | | `ncom_pre_sac` | Nota comercial Pre sac. | | `ncom_post_sac_cdi` | Nota comercial Pós sac vinculado ao CDI. | | `ncom_post_sac_ipca` | Nota comercial Pós sac vinculado ao IPCA. | | `ncom_post_sac_igpm` | Nota comercial Pós sac vinculado ao IGP-M. | | `ncom_post_price_cdi` | Nota comercial Pós price vinculado ao CDI. | | `ncom_post_price_ipca` | Nota comercial Pós price vinculado ao IPCA. | | `ncom_post_price_igpm` | Nota comercial Pós price vinculado ao IGP-M. | | `ncom_post_price_days_cdi` | Nota comercial Pós price days vinculado ao CDI. | | `ncom_post_price_days_ipca` | Nota comercial Pós price days vinculado ao IPCA. | | `ncom_post_price_days_igpm` | Nota comercial Pós price days vinculado ao IGP-M. | | `subscription_note` | Boletim de subscrição. | | `adhesion_term` | Termo de adesão. | --- # Consulta dos Documentos da Operação URL: /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)**. --- # Consulta de Operação por Chave URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave Este endpoint permite consultar os detalhes completos de uma operação específica, utilizando sua chave única. --- ## Consulta de Operação (GET) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74", "operation_type": "commercial_paper", "operation_status": "issued", "backoffice_analysis_status": "approved", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "issuer_onboarding_approved": true, "issue_number": 1, "issue_series": 1, "contract_number": "0000000001", "issue_date": "2025-02-03", "financial_base_date": "2025-02-03", "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9", "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8", "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f", "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c", "envelope_signature_status": "signed", "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b", "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a", "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files", "financial": { "financial_base_date": "2025-02-03", "issue_quantity": 1000000, "unit_price": 1.0, "issue_amount": 1000000.0, "released_amount": 1000000.0, "cet": 5.0, "annual_cet": 79.59, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0016053474, "annual_rate": 0.795856326, "monthly_rate": 0.05, "interest_base": "calendar_days_365" }, "fine_delay_rate": { "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "financial_index": null, "post_fixed_interest_rate": null, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 20000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 50000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_number": 1, "workdays": 20, "calendar_days": 30, "principal_amortization_unit_price": 0.18122484, "principal_amortization_amount": 181224.84138231, "interest_amount": 49298.45861769, "amount": 230523.3, "due_principal": 1000000.0, "due_interest": 0.0, "due_date": "2025-03-05", "has_interest": true }, { "installment_number": 2, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.19153595, "principal_amortization_amount": 191535.95353305, "interest_amount": 38987.34646695, "amount": 230523.3, "due_principal": 818775.15861769, "due_interest": 0.0, "due_date": "2025-04-03", "has_interest": true }, { "installment_number": 3, "workdays": 19, "calendar_days": 32, "principal_amortization_unit_price": 0.19748652, "principal_amortization_amount": 197486.52331007, "interest_amount": 33036.77668993, "amount": 230523.3, "due_principal": 627239.20508464, "due_interest": 0.0, "due_date": "2025-05-05", "has_interest": true }, { "installment_number": 4, "workdays": 21, "calendar_days": 29, "principal_amortization_unit_price": 0.21005991, "principal_amortization_amount": 210059.90840452, "interest_amount": 20463.39159548, "amount": 230523.3, "due_principal": 429752.68177457, "due_interest": 0.0, "due_date": "2025-06-03", "has_interest": true }, { "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.21969277, "principal_amortization_amount": 219692.77337005, "interest_amount": 10830.52662995, "amount": 230523.3, "due_principal": 219692.77337005, "due_interest": 0.0, "due_date": "2025-07-03", "has_interest": true } ] }, "tags": [], "investor_list": [ { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "subscription_percentage": 100.0, "subscription_quantity": 1000000, "investor_onboarding_approved": true, "bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "updated_at": null } ], "related_party_list": [ { "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c", "name": "Blue Logic", "document_number": "97.923.586/0001-06", "role_type": "issuer", "is_active": true, "updated_at": null, "trading_name": "Blue Logic", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5511988887777", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5516982399722", "document_number": "123.456.789-00", "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414" } ] }, { "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30", "name": "Ultimate Cascade", "document_number": "31.424.651/0001-32", "role_type": "investor", "is_active": true, "updated_at": null, "trading_name": "Ultimate Cascade", "cnae_code": "47.21-1-02", "company_type": "ltda", "foundation_date": "2007-10-25", "person_type": "legal", "street": "Rua Romualdo de Souza Brito", "neighborhood": "Centro", "number": "89", "postal_code": "08150-470", "city": "São Paulo", "state": "SP", "complement": "Letra C", "signer_group_list": [ { "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca", "minimum_required_signers": 1, "signers": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "phone_number": "+5516982399722", "document_number": "123.456.789-00", "is_group_mandatory": true } ] } ], "document_list": [], "contact_information_list": [ { "name": "John Doe", "email": "123.456.789-00@yopmail.com", "is_default": true, "phone_number": "+5511988887777", "document_number": "123.456.789-00", "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ] } ], "collateral_list": [ { "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "collateral_type": "fiduciary_alienation_property" } ], "metadata_list": [ { "metadata_key": "convenio", "metadata_value": "12398129038" } ], "integralization_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754", "security_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae" } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------| | `tenant_key` * | string | Chave única do tenant (UUID v4). | 36 | | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `operation_type` * | string | Tipo da operação. `commercial_paper` | - | | `operation_status` * | string | Status da operação. | [Enumeradores operation_status](#enumeradores-operation_status) | | `issuer_key` * | string | Chave única do emissor (UUID v4). | 36 | | `issuer_name` * | string | Nome do emissor. | - | | `issuer_document_number` * | string | Número do documento do emissor (CNPJ). | 18 | | `issuer_bank_account` * | object | Dados bancários do emissor. | [Objeto bank_account](#objeto-bank_account) | | `issuer_onboarding_approved` * | boolean | Indica se o onboarding do emissor foi aprovado. | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `contract_number` * | string | Número do contrato. | - | | `issue_date` * | string | Data da emissão (formato ISO 8601). | - | | `financial_base_date` * | string | Data base financeira da operação (formato ISO 8601). | - | | `commercial_paper_template_key` * | string | Chave única do template do commercial paper. | 36 | | `commercial_paper_document_key` * | string | Chave do documento do commercial paper. | - | | `adhesion_term_template_key` * | string | Chave única do template do termo de adesão. | 36 | | `adhesion_term_document_key` * | string | Chave do documento do termo de adesão. | - | | `investor_list` * | object | Lista de investidores. | [Objeto investor](#objeto-investor) | ### Objeto bank_account | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_type` * | string | Tipo da conta (ex: checking). | - | | `account_digit` * | string | Dígito da conta bancária. | - | | `account_branch` * | string | Agência bancária. | - | | `account_number` * | string | Número da conta bancária. | - | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | - | | `financial_institution_code_number` * | string | Código da instituição financeira. | - | ### Objeto financial | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|-----------------------------------------------------------------|-----------------------------------------------------------------| | `financial_base_date` * | string | Data base financeira da operação (formato ISO 8601). | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | float | Preço unitário da emissão. | - | | `issue_amount` * | float | Valor total da emissão. | - | | `released_amount` * | float | Valor total liberado. | - | | `cet` * | float | Custo Efetivo Total da operação (%). | - | | `annual_cet` * | float | Custo Efetivo Total anualizado (%). | - | | `number_of_installments` * | integer | Número total de parcelas da operação. | - | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | [Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate) | | `fine_delay_rate` * | object | Taxa de multa por atraso | [Objeto fine_delay_rate](#objeto-fine_delay_rate). | | `contract_fine_rate` * | float | Taxa de multa contratual (%). | - | | `financial_index` | string | Índice financeiro de referência (caso exista). | - | | `post_fixed_interest_rate` | object | Taxa de juros pós-fixada (se aplicável). | - | | `fees` * | array | Lista de taxas aplicáveis.| [Objeto fees](#objeto-fees) | | `installment_list` * | array | Lista de parcelas. | [Objeto installment](#objeto-installment) | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | |-----------------------|--------|------------------------------------------------------------|-----------------| | `daily_rate` * | float | Taxa de juros diária (%). | - | | `annual_rate` * | float | Taxa de juros anualizada (%). | - | | `monthly_rate` * | float | Taxa de juros mensal (%). | - | | `interest_base` * | string | Base de cálculo da taxa de juros (`calendar_days_365`). | - | ## Objeto fine_delay_rate | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|--------------------------------------------------|-----------------| | `monthly_rate` * | float | Taxa de multa mensal por atraso (%). | - | | `interest_base` * | string | Base de cálculo da taxa de juros (`calendar_days_365`). | - | ## Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | |---------------|---------|------------------------------------------------|-----------------| | `type` * | string | Tipo da taxa (`internal`, `external`). | - | | `amount` * | float | Percentual da taxa aplicada. | - | | `fee_type` * | string | Tipo da taxa. | - | | `fee_amount` * | float | Valor absoluto da taxa aplicada. | - | | `amount_type` * | string | Tipo do valor (`percentage`, `fixed`). | - | ## Objeto installment | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------------|---------|----------------------------------------------------------|-----------------| | `installment_number` * | integer | Número da parcela. | - | | `workdays` * | integer | Quantidade de dias úteis até o vencimento. | - | | `calendar_days` * | integer | Quantidade de dias corridos até o vencimento. | - | | `principal_amortization_unit_price` * | float | Valor unitário de amortização do principal. | - | | `principal_amortization_amount` * | float | Valor total de amortização do principal. | - | | `interest_amount` * | float | Valor total dos juros da parcela. | - | | `amount` * | float | Valor total da parcela. | - | | `due_principal` * | float | Valor do principal a vencer após a parcela. | - | | `due_interest` * | float | Valor dos juros a vencer após a parcela. | - | | `due_date` * | string | Data de vencimento da parcela (formato ISO 8601). | - | | `has_interest` * | boolean | Indica se a parcela possui cobrança de juros. | - | ## Objeto investor | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------------------|---------|----------------------------------------------------------------------|----------------------------------------------| | `investor_key` * | string | Chave única do investidor (UUID v4). | 36 | | `investor_name` * | string | Nome do investidor. | - | | `investor_document_number` * | string | Número do documento do investidor (CNPJ/CPF). | 18 | | `subscription_percentage` * | float | Percentual de participação do investidor na operação. | - | | `subscription_quantity` * | integer | Quantidade de unidades subscritas pelo investidor. | - | | `investor_onboarding_approved` * | boolean | Indica se o onboarding do investidor foi aprovado. | - | | `bank_account` * | object | Informações bancárias do investidor. | [Objeto bank_account](#objeto-bank_account). | ## **Enumeradores operation_status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `in_filling` | Operação em fase de preenchimento. | | `in_analysis` | Operação em análise. | | `waiting_onboarding_approval` | Aguardando aprovação do onboarding do emissor. | | `pending_signature_submission` | Aguardando envio para assinatura. | | `waiting_signature` | Aguardando assinaturas dos envolvidos. | | `issued` | Operação emitida. | | `finished` | Operação concluída. | | `signature_rejected` | Assinatura rejeitada. | | `onboarding_reproved` | Onboarding do emissor reprovado. | | `compliance_reproved` | Reprovado por compliance. | | `canceled` | Operação cancelada. | --- # Consulta de Operações por Filtros URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros Este endpoint permite consultar operações de **nota comercial** utilizando filtros opcionais. --- ## **Request** ENDPOINT /commercial_paper/operation MÉTODO GET ### **Query Params** | Campo | Tipo | Descrição | Obrigatório | |----------------------------|----------|-----------------------------------------------|-------------| | `issuer_document_number` | string | Número do documento do emissor (CNPJ). | Não | | `investor_document_number` | string | Número do documento do investidor (CPF/CNPJ). | Não | | `operation_status` | string | Status da operação. | **[Enumeradores operation_status](#enumeradores-operation_status)** | Não | | `metadata_key` | array | Chave de metadado. | Não | | `metadata_value` | array | Valor de metadado. | Não | --- ## **Response** STATUS 200 Response Body ```json { "data": [ { "tenant_key": "13edaf06-9810-4689-b00b-2367274d1a14", "operation_key": "34bc5da7-89df-467d-93af-ed25184ab72e", "operation_type": "commercial_paper", "operation_status": "in_filling", "backoffice_analysis_status": "waiting_submission_for_analysis", "issuer_key": "7fbe9f89-b9ca-4445-85ac-6098da86bb56", "issuer_name": "Global Networks", "issuer_document_number": "73364815000123", "issue_number": 1, "contract_number": "0000000004" }, { "tenant_key": "13edaf06-9810-4689-b00b-2367274d1a14", "operation_key": "f456ee66-5844-4ebc-b69d-365ce6df7138", "operation_type": "commercial_paper", "operation_status": "in_filling", "backoffice_analysis_status": "waiting_submission_for_analysis", "issuer_key": "7fbe9f89-b9ca-4445-85ac-6098da86bb56", "issuer_name": "Global Networks", "issuer_document_number": "73364815000123", "issue_number": 2, "contract_number": "0000000005" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 2 } } ``` --- ### **Response Body Params** #### **Objeto Data** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|-----------------------------------------------------------|-----------------| | `tenant_key` * | string | Chave única do tenant (UUID v4). | 36 | | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `operation_type` * | string | Tipo da operação. Sempre será `commercial_paper`. | 50 | | `operation_status` * | string | Status atual da operação. | **[Enumeradores operation_status](#enumeradores-operation_status)** | 50 | | `backoffice_analysis_status` | string | Status da análise de backoffice. | 50 | | `issuer_key` * | string | Chave única do emissor associado à operação (UUID v4). | 36 | | `issuer_name` * | string | Nome do emissor associado à operação. | 255 | | `issuer_document_number` * | string | Número do documento do emissor (CNPJ). | 14 | | `issue_number` * | integer | Número da emissão associada à operação. | - | | `contract_number` * | string | Número do contrato associado à operação. | 20 | #### **Objeto Pagination** | Campo | Tipo | Descrição | |-------------------|----------|----------------------------------------------------------| | `current_page` * | integer | Página atual da consulta. | | `next_page` | integer | Próxima página, caso exista. | | `rows_per_page` * | integer | Número de registros por página. | | `total_pages` * | integer | Total de páginas disponíveis. | | `total_rows` * | integer | Total de registros encontrados para os filtros aplicados. | --- ## **Enumeradores operation_status** | Enum | Descrição | |--------------------------------|----------------------------------------------------------------| | `in_filling` | Operação em fase de preenchimento. | | `in_analysis` | Operação em análise. | | `waiting_onboarding_approval` | Aguardando aprovação do onboarding do emissor. | | `pending_signature_submission` | Aguardando envio para assinatura. | | `waiting_signature` | Aguardando assinaturas dos envolvidos. | | `issued` | Operação emitida. | | `finished` | Operação concluída. | | `signature_rejected` | Assinatura rejeitada. | | `onboarding_reproved` | Onboarding do emissor reprovado. | | `compliance_reproved` | Reprovado por compliance. | | `canceled` | Operação cancelada. | --- # Consulta do Próximo Número de Emissão por Emissor URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao Este endpoint retorna o próximo `issue_number` (número de emissão) disponível para o emissor identificado por `issuer_key`. O valor retornado considera a maior numeração já utilizada em operações **não canceladas** do emissor e o controle interno de numeração na configuração do emissor — sempre é devolvido o maior entre os dois. Caso ainda não exista configuração de numeração para o emissor, ela é criada automaticamente com `current_issue_number = 1` e esse valor é retornado. --- ## **Request** ENDPOINT /commercial_paper/issuer/ ISSUER-KEY /issue_number MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|-------------|---------------------------------------------------------------------------|-----------------| | `ISSUER-KEY` * | string/uuid | Identificador único (UUID v4) do emissor cadastrado no Issuer Management. | 36 | --- ## **Response** STATUS 200 Response Body ```json { "issue_number": 42 } ``` --- ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|---------|----------------------------------------------------------------------------------------------------------------------|-----------------| | `issue_number` * | integer | Próximo número de emissão sugerido para uma nova operação do emissor. Inicia em `1` para emissores sem operações nem configuração prévia. | - | --- # Enviar Atas de Aprovação Assinadas URL: /documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao Este endpoint permite enviar as atas de aprovação de empresas do tipo SA ou COP assinadas de forma externa para o sistema de escrituação, enviando um base64 que será analisado e aprovado pelo escriturador. --- ## Enviar Operação Assinada (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "sa_minute" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `contract_type` * | string | Tipo de contrato assinado | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Ata de aprovação assinada em base64. | - | ### Enumeradores contract_type | Enum | Descrição | |--------------------|------------------------------------------| | `sa_minute` | Ata de aprovação de emissão da nota comercial para empresa **SA**. | | `cop_minute` | Ata de aprovação de emissão da nota comercial para empresa **COOPERATIVA**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Enviar Documentos Assinados da Operação URL: /documentation/escrituracao/emissao-de-notas/envio-contratos-assinados Este endpoint recebe as assinaturas dos documentos de formalização de operações com `signature_method` igual a **client_side**. O emissor assina os documentos na certificadora dele e envia à QI Tech apenas o arquivo de assinatura (`p7s_base64`), sem o PDF. :::warning Aviso Use este endpoint apenas em operações com `signature_method` **client_side**. Nos fluxos **QI Sign** e **CertifiQI** os contratos são gerados e assinados pela própria plataforma. Para a ata de aprovação use o endpoint de **[envio de ata de aprovação](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao)**. ::: --- ## Enviar Documento Assinado (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Assinatura do termo constitutivo ```json { "contract_type": "commercial_paper", "p7s_base64": "MIIJugYJKoZIhvcNAQcCoIIJqzCCCacC..." } ``` Assinatura de uma garantia ```json { "contract_type": "collateral", "collateral_key": "8f0b6f0a-1a2b-4c3d-9e8f-7a6b5c4d3e2f", "p7s_base64": "MIIJugYJKoZIhvcNAQcCoIIJqzCCCacC..." } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|-----------------------------------------------------------------------------------------------------------------|-----------------| | `contract_type` * | string | Tipo do documento enviado. | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `p7s_base64` * | string | Assinatura CAdES em base64, destacada ou anexada. | - | | `collateral_key` | string | Chave da garantia a que a assinatura se refere. Obrigatório quando `contract_type` é `collateral`. | 36 | ### Enumeradores contract_type | Enum | Descrição | |---------------------|------------------------------------------------------------------------------| | `commercial_paper` | Termo constitutivo da nota comercial. | | `adhesion_term` | Termo de adesão da nota comercial. | | `collateral` | Documento de garantia da operação. Exige `collateral_key`. | ### Response O corpo da resposta é o JSON completo da operação atualizada. --- ## Assinatura dos documentos de formalização Os documentos ficam disponíveis para download depois que a operação é aprovada na análise, pelo endpoint de **[consulta de documentos da operação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao)**. Cada documento aceita um único `.p7s` e é enviado em uma requisição própria. Quando todos os documentos exigidos são aceitos, os assinantes da QI Tech assinam e a operação é emitida. :::danger Assine exatamente o documento baixado A QI Tech compara o resumo (SHA-256) declarado dentro do `.p7s` com o do documento gerado na aprovação. Ferramentas que reprocessam o PDF antes de assinar, como reabrir e salvar ou recomprimir, alteram esse resumo e a assinatura é recusada com `COM000074`. ::: ## **Erros** Os códigos abaixo estão descritos também no [catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). | Código | HTTP | Descrição | |---------------|--------|--------------------------------------------------------------------------------------------| | `COM000072` | 400 | O documento de formalização exige o arquivo de assinatura e o `p7s_base64` não foi enviado. | | `COM000073` | 400 | O arquivo enviado não pôde ser lido como estrutura CMS, ou excede o tamanho aceito. | | `COM000074` | 422 | A assinatura não corresponde ao documento emitido pela QI Tech. | | `COM000075` | 409 | O documento já teve uma assinatura aceita. | --- # Enviar Operação para Análise URL: /documentation/escrituracao/emissao-de-notas/envio-para-analise Este endpoint permite alterar o status de uma operação para "em análise", enviando-a para o processo de validação de compliance pelo escriturador. --- ## Enviar Operação para Análise (PATCH) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body ```json { "operation_status": "in_analysis" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |--------------------|----------|------------------------------------------------------------|-------------| | `operation_status` | string | Status da operação. Deve ser definido como `in_analysis`. | Sim | --- ### Response O corpo da resposta é um JSON completo da operação atualizado. --- --- # Enviar Operação para Assinatura URL: /documentation/escrituracao/emissao-de-notas/envio-para-assinatura :::warning Aviso Operações aprovadas pelo compliance são enviadas automaticamente para assinatura periodicamente. Este endpoint deve ser usado apenas para realizar um envio imediato, caso necessário. ::: --- ## Enviar Operação para Assinatura (POST) ### Request ENDPOINT /commercial_paper/operation/ OPERATION-KEY /send_to_signature MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|----------------------------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Nenhum corpo de requisição é necessário. --- ### Response O corpo da resposta é um JSON completo da operação atualizado. --- --- # Alterar Template do Termo de Adesão URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta Este endpoint permite a alteração do template do Termo de Adesão para uma operação específica. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- Request Body ```json { "adhesion_term_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------------|----------|--------------------------------------------------|-------------| | `adhesion_term_template_key` * | string | Chave única do novo template a ser utilizado (UUID v4). | Sim | ## Response O corpo da resposta é um JSON completo da operação atualizado. --- # Alterar Template do Termo Constitutivo URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc Este endpoint permite a alteração do template do Termo Constitutivo para uma operação específica. ### **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY MÉTODO PATCH ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- Request Body ```json { "commercial_paper_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------------|----------|--------------------------------------------------|-------------| | `commercial_paper_template_key` * | string | Chave única do novo template a ser utilizado (UUID v4). | Sim | ## Response O corpo da resposta é um JSON completo da operação atualizado. --- # Pré-visualizar Termo de Adesão URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao Este endpoint permite a pré-visualização de uma minuta do Termo de Adesão para uma operação específica, utilizando um template predefinido. --- ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_adhesion_term MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------------|----------|--------------------------------------------------|-------------| | `template_key` * | string | Chave única do novo template a ser utilizado (UUID v4). | Sim | ## **Response** STATUS 201 Response Body ```json { "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "document_type": "adhesion_term", "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|------------------------------------------------|-----------------| | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `document_type` * | string | Tipo do documento gerado. Sempre será `adhesion_term`. | 50 | | `document_base64` * | string | Conteúdo do documento gerado, codificado em Base64. | - | --- # Pré-visualizar Termo Constitutivo URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato Este endpoint permite a geração de uma minuta do Termo Constitutivo para uma operação específica, utilizando um template predefinido. --- ## **Request** ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_commercial_paper MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | Request Body ```json { "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |--------------------------------------|----------|--------------------------------------------------|-------------| | `template_key` * | string | Chave única do novo template a ser utilizado (UUID v4). | Sim | ## **Response** STATUS 201 Response Body ```json { "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "document_type": "commercial_paper", "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|----------|------------------------------------------------|-----------------| | `operation_key` * | string | Chave única da operação (UUID v4). | 36 | | `document_type` * | string | Tipo do documento gerado. Sempre será `commercial_paper`. | 50 | | `document_base64` * | string | Conteúdo do documento gerado, codificado em Base64. | - | --- # Introdução à Emissão de Notas Comerciais URL: /documentation/escrituracao/emissao-de-notas/inicio As notas comerciais são instrumentos financeiros utilizados por empresas para captar recursos diretamente no mercado. Este processo envolve diversas etapas, desde o cadastro de emissores e investidores, passando pela definição de condições financeiras, até a emissão formal dos títulos. Cada etapa é crucial para garantir a conformidade regulatória e a eficiência no processo de captação. --- ## Visão Geral do Processo de Emissão O processo de emissão de notas comerciais é estruturado em várias etapas, que garantem transparência, segurança e controle. Abaixo, estão os principais passos do processo: 1. **Cadastro de Emissores e Investidores** Empresas que desejam emitir notas comerciais e investidores interessados em adquirir esses títulos precisam ser cadastrados no sistema. O cadastro inclui informações detalhadas, como documentos e contas bancárias. 2. **Definição das Condições da Operação** O emissor define as condições financeiras da operação, incluindo taxas de juros, número de parcelas, datas de emissão e vencimento, além de eventuais taxas e encargos. 3. **Simulação** Antes da emissão formal, é realizada uma simulação para calcular os valores de emissão, o fluxo de parcelas e outros detalhes financeiros. Esta etapa permite ajustar as condições da operação de acordo com as necessidades do emissor e dos investidores. 4. **Cadastro de Partes Relacionadas e Documentação** Inclui o registro de partes envolvidas, como garantidores e coobrigados, e o envio de documentos relevantes, como contratos e termos. 5. **Geração e Assinatura de Documentos** São geradas as minutas dos principais documentos, como o **Termo de Adesão** e o **Termo Constitutivo**. Após aprovação, os documentos são enviados para assinatura eletrônica. 6. **Envio para Análise e Aprovação** A operação é submetida para análise de compliance e backoffice, garantindo que todas as exigências regulatórias e contratuais sejam atendidas. 7. **Emissão Formal e Registro** Após aprovação, as notas comerciais são formalmente emitidas e disponibilizadas para os investidores. A partir das próximas páginas, exploraremos em detalhes cada etapa do processo de emissão de notas comerciais, incluindo endpoints e exemplos práticos para integrar seu sistema à API. --- # Simulação de condições financeiras URL: /documentation/escrituracao/emissao-de-notas/simulacao Este endpoint permite simular as condições financeiras e o fluxo de pagamentos de uma operação --- :::warning Atenção O **Request Body** deve conter uma combinação válida de parâmetros para ser processado. As combinações aceitas são: - Valor de Emissão/Liberado + Taxa de Juros - Valor de Emissão/Liberado + Valor por Parcela - Valor por Parcela + Taxa de Juros - Valor de Emissão/Liberado + Taxa de Juros + Percentual de Amortização por Parcela. ::: ## Request ENDPOINT /commercial_paper/simulation MÉTODO POST ## Operação pré-fixada Valor de emissão + Taxa ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-01-20", "issue_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ], "first_due_date_delay": 60, } ``` Valor desembolsado + Taxa ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-01-20", "released_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "external" } ], "first_due_date": "2026-01-31" } ``` Valor da parcela + taxa de juros ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-01-20", "number_of_installments": 2, "installments": [ { "due_date": "2026-01-01", "amount": 500000 }, { "due_date": "2026-02-01", "amount": 502004.01 } ], "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ] } ``` Valor de emissão + Percentual de amortização da parcela + taxa de juros ```json { "interest_type": "pre_sac", "financial_base_date": "2025-01-20", "issue_amount": 1000000, "number_of_installments": 3, "installments": [ { "due_date": "2026-01-01", "principal_amortization_percentage": 0.1 }, { "due_date": "2026-02-01", "principal_amortization_percentage": 0.1 }, { "due_date": "2026-03-01", "principal_amortization_percentage": 0.8 } ], "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "external" } ] } ``` Valor de emissão + Valor das parcelas ```json { "interest_type": "pre_price_days", "financial_base_date": "2025-01-20", "issue_amount": 700000, "number_of_installments": 2, "installments": [ { "due_date": "2026-01-01", "amount": 500000 }, { "due_date": "2026-02-01", "amount": 502004.01 } ], "prefixed_interest_rate": { "interest_base": "calendar_days_365", }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ] } ``` ## Operação pós-fixada Valor de emissão + Taxa + Pós fixado ```json { "interest_type": "post_price_days", "financial_base_date": "2025-01-20", "issue_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 1000, "amount_type": "absolute", "fee_type": "structuring_fee", "type": "external" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` Valor desembolsado + Taxa + Pós fixado ```json { "interest_type": "post_price_days", "financial_base_date": "2025-01-20", "released_amount": 1000000, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "external" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` Valor da parcela + taxa de juros + Pós fixado ```json { "interest_type": "post_price_days", "financial_base_date": "2025-01-20", "number_of_installments": 2, "installments": [ { "due_date": "2026-01-01", "amount": 500000 }, { "due_date": "2026-02-01", "amount": 502004.01 } ], "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` Valor de emissão + Percentual de amortização da parcela + taxa de juros + Pós fixado ```json { "interest_type": "post_sac", "financial_base_date": "2025-01-20", "issue_amount": 1000000, "number_of_installments": 3, "installments": [ { "due_date": "2026-01-01", "principal_amortization_percentage": 0.1 }, { "due_date": "2026-02-01", "principal_amortization_percentage": 0.1 }, { "due_date": "2026-03-01", "principal_amortization_percentage": 0.8 } ], "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` Valor de emissão + Valor das parcelas + Pós fixado ```json { "interest_type": "post_price_days", "financial_base_date": "2025-01-20", "issue_amount": 700000, "number_of_installments": 2, "installments": [ { "due_date": "2026-01-01", "amount": 500000 }, { "due_date": "2026-02-01", "amount": 502004.01 } ], "prefixed_interest_rate": { "interest_base": "calendar_days_365", }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 5, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ], "post_fixed_interest_rate": 100, "financial_index": "CDI" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_type` * | string | Tipo de juros aplicado. | **[Enumeradores interest_type](#enumeradores-interest_type)** | | `financial_base_date` * | string | Data base da operação (formato "YYYY-MM-DD"). | - | | `released_amount` | number | Valor total liberado na operação. | - | | `issue_amount` | number | Valor de emissão da operação. | `number_of_installments` * | integer | Número total de parcelas. | - | | `installments` | array | Objeto contendo detalhes sobre cada parcela. | **[Objeto installments](#objeto-installments)** | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `post_fixed_interest_rate` | number | Valor da taxa pós fixada prefixada. | - | | `financial_index` | string | Tipo de Taxa pós-fixada. | **[Enumeradores financial_index](#enumeradores-financial_index)** | | `first_due_date` | date | Data da primeira parcela | - | | `first_due_date_delay` | number | Dias para o ínicio do pagamento da primeira parcela. | - | ### Objeto installments | Campo | Tipo | Descrição | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------| | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | | `amount` | number | Valor total da parcela. | | `principal_amortization_percentage` | number | Valor percentual amortizado do principal. | ### Objeto prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `daily_rate` | number | Taxa de juros diária aplicada. | - | | `monthly_rate` | number | Taxa de juros mensal aplicada. | - | | `annual_rate` | number | Taxa de juros anual aplicada. | - | ### Objeto fine_delay_rate | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `interest_base` * | string | Base para cálculo da multa. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de multa mensal. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------| | `amount` * | number | Valor da taxa aplicada. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Enumeradores interest_type | Enum | Descrição | |--------------------|------------------------------------------| | `pre_price` | Juros pré-fixados no modelo Price. | | `pre_price_days` | Juros pré-fixados no modelo Price por dias corridos. | | `pre_sac` | Juros pré-fixados no modelo SAC. | | `post_sac` | Juros pós-fixados no modelo SAC. | | `post_price_days` | Juros pós-fixados no modelo Price por dias corridos. | ### Enumeradores financial_index | Enum | Descrição | |--------------------|------------------------------------------| | `CDI` | Pós fixado de CDI | | `IPCA` | Pós fixado de IPCA | | `IGPM` | Pós fixado de IGPM | ### Enumeradores interest_base | Enum | Descrição | |--------------------|------------------------------------------| | `calendar_days` | Base de dias corridos. | | `calendar_days_365`| Base de 365 dias corridos. | | `workdays` | Base de dias úteis. | ### Enumeradores amount_type | Enum | Descrição | |-------------|---------------------------| | `percentage` | Valor em percentual. | | `absolute` | Valor absoluto em moeda. | ### Enumeradores fee_type | Enum | Descrição | |-------------------------------------|-------------------------------------------| | `bookkeeping_fee` | Taxa de escrituração financiada. | | `structuring_fee` | Taxa de estruturação financiada. | ### Enumeradores fee_recipient | Enum | Descrição | |-----------|-------------------------------------------------------| | `internal` | Taxa paga ao escriturador. | | `external` | Rebate pago ao originador. | ## Response STATUS 200 Response Body ```json { "financial_base_date": "2025-01-20", "issue_amount": 1075268.82, "released_amount": 1000000.0, "issue_quantity": 1075268, "unit_price": 1.00000076, "cet": 7.7, "annual_cet": 143.55, "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }, { "amount": 5.0, "fee_amount": 53763.44, "amount_type": "percentage", "fee_type": "structuring_fee", "type": "external" } ], "installments": [ { "installment_number": 1, "workdays": 23, "calendar_days": 31, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 0.17976244, "interest_amount": 54820.37344366, "amount": 248113.17, "due_principal": 1075268.82, "due_interest": 0.0, "due_date": "2025-02-20", "has_interest": true }, { "installment_number": 2, "workdays": 18, "calendar_days": 28, "principal_amortization_amount": 207597.32873049, "principal_amortization_unit_price": 0.19306566, "interest_amount": 40515.84126951, "amount": 248113.17, "due_principal": 881976.02344366, "due_interest": 0.0, "due_date": "2025-03-20", "has_interest": true }, { "installment_number": 3, "workdays": 21, "calendar_days": 33, "principal_amortization_amount": 211453.91638185, "principal_amortization_unit_price": 0.19665229, "interest_amount": 36659.25361815, "amount": 248113.17, "due_principal": 674378.69471317, "due_interest": 0.0, "due_date": "2025-04-22", "has_interest": true }, { "installment_number": 4, "workdays": 19, "calendar_days": 28, "principal_amortization_amount": 226847.52746545, "principal_amortization_unit_price": 0.21096836, "interest_amount": 21265.64253455, "amount": 248113.17, "due_principal": 462924.77833132, "due_interest": 0.0, "due_date": "2025-05-20", "has_interest": true }, { "installment_number": 5, "workdays": 22, "calendar_days": 31, "principal_amortization_amount": 236077.25086587, "principal_amortization_unit_price": 0.21955201, "interest_amount": 12035.91913413, "amount": 248113.17, "due_principal": 236077.25086587, "due_interest": 0.0, "due_date": "2025-06-20", "has_interest": true } ], "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02 } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |------------------------------|----------|---------------------------------------------------------------------------------------------------------|-----------------| | `financial_base_date` * | string | Data base financeira da operação (formato "YYYY-MM-DD"). | - | | `issue_amount` * | number | Valor total emitido da operação. | - | | `released_amount` * | number | Valor líquido liberado na operação. | - | | `issue_quantity` * | integer | Quantidade total de unidades emitidas. | - | | `unit_price` * | number | Preço unitário da emissão. | - | | `cet` * | number | Custo Efetivo Total (CET) em percentual. | - | | `annual_cet` * | number | CET anual em percentual. | - | | `number_of_installments` * | integer | Número total de parcelas. | - | | `prefixed_interest_rate` * | object | Objeto contendo detalhes da taxa de juros prefixada. | **[Objeto prefixed_interest_rate](#objeto-response-prefixed_interest_rate)** | | `fees` | array | Lista de taxas associadas à operação. | **[Objeto fees](#objeto-fees)** | | `installments` | array | Lista de detalhes das parcelas geradas na operação. | **[Objeto installments](#objeto-response-installments)** | | `fine_delay_rate` * | object | Objeto contendo detalhes da multa por atraso. | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** | | `contract_fine_rate` * | number | Multa contratual aplicada em percentual. | - | ### Objeto Response prefixed_interest_rate | Campo | Tipo | Descrição | Caracteres Máx. | |---------------|----------|------------------------------------------------------------|-----------------| | `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** | | `monthly_rate` * | number | Taxa de juros mensal aplicada. | - | | `daily_rate` * | number | Taxa de juros diária aplicada. | - | | `annual_rate` * | number | Taxa de juros anual aplicada. | - | ### Objeto fees | Campo | Tipo | Descrição | Caracteres Máx. | |------------|--------|------------------------------------------------------------|-----------------| | `amount` * | number | Valor percentual da taxa. | - | | `fee_amount` * | number | Valor monetário correspondente à taxa. | - | | `amount_type` * | string | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** | | `fee_type` * | string | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** | | `type` * | string | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** | ### Objeto Response installments | Campo | Tipo | Descrição | |----------------------------|----------|--------------------------------------------------------| | `installment_number` * | integer | Número da parcela. | | `workdays` * | integer | Dias úteis até o vencimento da parcela. | | `calendar_days` * | integer | Dias corridos até o vencimento da parcela. | | `principal_amortization_amount` * | number | Valor amortizado do principal. | | `principal_amortization_unit_price` * | number | Valor amortizado por unidade. | | `interest_amount` * | number | Valor dos juros aplicados na parcela. | | `amount` * | number | Valor total da parcela. | | `due_date` * | string | Data de vencimento da parcela (formato "YYYY-MM-DD"). | --- # Cadastro de Operação de Debênture URL: /documentation/escrituracao/emissao-debentures/cadastro-operacao Este endpoint cria uma operação de Debênture completa em uma única requisição. :::info O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados. ::: --- ## **Request** ENDPOINT /debenture/create_operation MÉTODO POST O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo. Payload com os campos obrigatórios ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "issue_date": "2025-01-20", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] } } ``` Payload completo (com partes relacionadas) ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issue_number": 10, "issue_series": 1, "contract_number": "DEB-2025-0001", "issue_date": "2025-01-20", "signature_method": "certifiqi", "investors": [ { "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7", "subscription_percentage": 100, "bank_account": { "account_number": "33400254", "account_digit": "3", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking" } } ], "financial": { "financial_base_date": "2025-01-20", "interest_type": "pre_price_days", "issue_amount": 1075268.82, "issue_quantity": 1075268, "unit_price": 1.0000007626, "released_amount": 1075268.82, "cet": 7.7, "annual_cet": 143.55, "first_due_date": "2025-02-20", "number_of_installments": 5, "prefixed_interest_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.05, "daily_rate": 0.0016053474, "annual_rate": 0.795856326 }, "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 }, "contract_fine_rate": 0.02, "fees": [ { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" } ], "installments": [ { "installment_number": 1, "due_date": "2025-02-20", "amount": 248113.17, "principal_amortization_amount": 193292.79655634, "principal_amortization_unit_price": 1.02, "interest_amount": 0.0, "calendar_days": 31, "workdays": 23 } ] }, "related_party_list": [ { "person_type": "legal", "name": "Garantidora S.A.", "document_number": "12.345.678/0001-90", "trading_name": "Garantidora", "cnae_code": "64.62-0-00", "company_type": "sa", "foundation_date": "2010-05-01", "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "postal_code": "01310-100", "city": "São Paulo", "state": "SP", "role_type": "guarantor" }, { "person_type": "natural", "name": "João da Silva", "document_number": "123.456.789-00", "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "role_type": "solidary_debtor", "is_pep": false } ] } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------- | ------- | ---------------------------------------------------- | -------------------------- | | `tenant_key` * | string | Chave única do tenant. | - | | `issuer_key` * | string | Chave única do emissor (previamente cadastrado). | - | | `issue_number` * | integer | Número da emissão. | - | | `issue_series` * | integer | Série da emissão. | - | | `issue_date` * | string | Data de emissão da operação (formato "YYYY-MM-DD"). | - | | `signature_method` | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** | | `investors` * | array | Lista de investidores envolvidos. | **Objeto investors** | | `financial` * | object | Dados financeiros já calculados da operação. | **Objeto financial** | | `contract_number` | string | Número do contrato. | - | | `related_party_list` | array | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** | ### Objeto investors | Campo | Tipo | Descrição | | --------------------------- | ------ | -------------------------------------------------------- | | `investor_key` * | string | Chave única do investidor (previamente cadastrado). | | `bank_account` * | object | Conta bancária do investidor (**Objeto bank_account**). | | `subscription_percentage` | number | Percentual de subscrição. | | `subscription_quantity` | number | Quantidade subscrita. | ### Objeto bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. | | `account_digit` * | string | Dígito da conta bancária. | | `account_branch` * | string | Agência da conta bancária. | | `financial_institution_code_number` | string | Código da instituição financeira. | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira. | | `account_type` * | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`). | ### Objeto financial | Campo | Tipo | Descrição | | --------------------------- | ------- | -------------------------------------------------- | | `financial_base_date` * | string | Data base financeira (formato "YYYY-MM-DD"). | | `interest_type` * | string | Tipo de juros. | | `issue_amount` | number | Valor total emitido. | | `issue_quantity` | integer | Quantidade de unidades emitidas. | | `unit_price` | number | Preço unitário da emissão. | | `released_amount` | number | Valor líquido liberado. | | `cet` / `annual_cet` | number | Custo Efetivo Total (mensal e anual), em percentual. | | `number_of_installments` * | integer | Número de parcelas. | | `prefixed_interest_rate` * | object | Taxa de juros prefixada. | | `fine_delay_rate` | object | Taxa de multa por atraso. | | `contract_fine_rate` | number | Multa contratual em percentual. | | `fees` | array | Lista de taxas. | | `installments` | array | Lista de parcelas já calculadas. | ### Objeto related_party Cada item de `related_party_list` representa uma parte envolvida na operação. | Campo | Tipo | Descrição | | ----------------- | ------- | ------------------------------------------------------------- | | `person_type` * | string | Tipo de pessoa (`natural` para PF, `legal` para PJ). | | `name` * | string | Nome da parte relacionada. | | `document_number` * | string | CPF (PF) ou CNPJ (PJ). | | `role_type` * | string | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** | | `street` * | string | Logradouro. | | `number` * | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `postal_code` * | string | CEP (formato "00000-000"). | | `city` * | string | Cidade. | | `state` * | string | UF (2 letras). | | `complement` | string | Complemento do endereço. | | `is_pep` | boolean | (PF) Indica se é Pessoa Politicamente Exposta. | | `marital_status` | string | (PF) Estado civil. | | `property_system` | string | (PF) Regime de bens. | | `birthdate` | string | (PF) Data de nascimento. | | `mother_name` | string | (PF) Nome da mãe. | | `occupation` | string | (PF) Ocupação. | | `trading_name` | string | (PJ) Nome fantasia. | | `cnae_code` | string | (PJ) Código CNAE (formato "00.00-0-00"). | | `company_type` | string | (PJ) Tipo de empresa. | | `foundation_date` | string | (PJ) Data de fundação. | :::warning Atenção Os campos obrigatórios variam conforme o `person_type`: - **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório. - **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios. ::: ### Enumeradores role_type | Enum | Descrição | |------|-----------| | `issuer` | Emissor. | | `investor` | Investidor. | | `cosigner` | Coobrigado. | | `fiduciary_debtor` | Devedor fiduciante. | | `solidary_debtor` | Devedor solidário. | | `guarantor` | Avalista. | | `bonafide_depositary` | Fiel depositário. | | `intervening_guarantor` | Interveniente garantidor. | | `intervening_consentor` | Interveniente anuente. | | `intervening_discharger` | Interveniente quitante. | | `assignor` | Cedente. | | `endorser` | Endossante. | | `consulting` | Consultoria. | | `fund_administrator` | Administrador do fundo. | | `fund_representative` | Representante do fundo. | | `company_representative` | Representante da empresa. | | `attestant` | Anuente / testemunha. | | `debtor` | Devedor. | | `bestowal` | Outorgante. | | `manager` | Gestor. | :::tip Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Envio de garantia** desta seção. ::: ### Enumeradores signature_method | Enum | Descrição | |------|-----------| | `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). | | `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. | ## **Response** STATUS 201 Response Body ```json { "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814", "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127", "operation_status": "finished", "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e", "issuer_name": "Dynamic Enterprises", "issuer_document_number": "28980395000155", "issue_number": 10, "issue_series": 1, "related_party_list": [ ... ], "financial": { ... } } ``` A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado. --- # Envio de Documento URL: /documentation/escrituracao/emissao-debentures/envio-documento Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints — por exemplo, no `collateral_document_key` e nos `additional_documents` do [Envio de garantia](./envio-garantia.md). --- ## **Request** ENDPOINT /debenture/upload MÉTODO POST Request Body ```json { "document_base64": "string_b64" } ``` ### **Request Body Params** | Campo | Tipo | Descrição | Obrigatório | |-------------------|--------|----------------------------------------------|-------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim | | `document_name` | string | Nome do documento. | - | ## **Response** STATUS 201 Response Body ```json { "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |----------------|--------|-------------------------------------------------|-----------------| | `document_key` * | string | Chave única do documento enviado (UUID v4). | 36 | --- --- # Enviar Documento Externo da Operação URL: /documentation/escrituracao/emissao-debentures/envio-documento-externo Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador. :::warning Aviso Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal. ::: --- ## Enviar Documento Assinado (POST) ### Request ENDPOINT /debenture/operation/ OPERATION-KEY /upload_signed_document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|--------|--------------------------------------|------------| | `OPERATION-KEY` | string | Chave única da operação (UUID v4). | 36 | --- ### Request Body Request Body ```json { "contract_base64": "image_b64", "contract_type": "debenture" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|--------|-----------------------------|-------------------------------------------------------------| | `contract_type` * | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** | | `contract_base64` * | string | Documento assinado em base64. | - | ### Enumeradores contract_type | Enum | Descrição | |---------------------|--------------------------------------------| | `debenture` | Escritura de emissão da debênture. | | `adhesion_term` | Termo de adesão da debênture. | | `sa_minute` | Ata de aprovação de emissão da debênture para empresa **SA**. | | `ltda_minute` | Ata de aprovação de emissão da debênture para empresa **LTDA**. | | `cop_minute` | Ata de aprovação de emissão da debênture para **Cooperativa**. | ### Response O corpo da resposta é um JSON completo da operação atualizada. --- --- # Envio de Garantia na Operação URL: /documentation/escrituracao/emissao-debentures/envio-garantia Este endpoint permite a **adição de garantias (collateral)** a uma operação de Debênture. A garantia é submetida para assinatura junto com os documentos da operação. Cada tipo de garantia (`collateral_type`) possui suas próprias regras de documentos obrigatórios, listadas abaixo. :::info Origem do `document_key` Os campos `collateral_document_key` e `document_key` (em `additional_documents`) referenciam documentos previamente enviados. Cada chave é obtida no endpoint [Envio de documento](./envio-documento.md) (`POST /debenture/upload`), que recebe o arquivo em Base64 e retorna o `document_key` correspondente. ::: --- ## **Request** ENDPOINT /debenture/operation/ OPERATION-KEY /collateral MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 | --- ## Tipos de garantia :::warning Documentos marcados como **obrigatórios** são exigidos para o respectivo tipo de garantia. ::: ### Alienação fiduciária de imóvel (`fiduciary_alienation_property`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_property", "additional_documents": [ { "document_type": "property_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_registration_updated", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_full_content_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `property_appraisal_report` | Laudo de avaliação do imóvel. | Sim | | `property_registration_updated` | Matrícula atualizada. | Sim | | `property_full_content_certificate` | Certidão de inteiro teor da matrícula. | Sim | | `property_insurance_policy` | Apólice de seguro (se exigível no contrato). | - | | `others` | Outros documentos. | - | ### Alienação fiduciária de veículo (`fiduciary_alienation_vehicle`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_vehicle", "additional_documents": [ { "document_type": "vehicle_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "vehicle_inspection_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "vehicle_crv_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `vehicle_appraisal_report` | Laudo de avaliação do veículo ou Tabela FIPE. | Sim | | `vehicle_inspection_report` | Laudo de vistoria. | Sim | | `vehicle_crv_certificate` | CRLV atualizado. | Sim | | `others` | Outros documentos. | - | ### Alienação fiduciária de aeronave (`fiduciary_alienation_aircraft`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_aircraft", "additional_documents": [ { "document_type": "aircraft_certificate_anac", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "aircraft_rab_consult", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "aircraft_insurance_policy", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "aircraft_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `aircraft_certificate_anac` | Certificado de matrícula - ANAC. | Sim | | `aircraft_rab_consult` | Consulta no Registro Aeronáutico Brasileiro (RAB). | Sim | | `aircraft_insurance_policy` | Apólice de seguro - beneficiário o fundo. | Sim | | `aircraft_appraisal_report` | Laudo de avaliação da aeronave. | Sim | | `others` | Outros documentos. | - | ### Alienação fiduciária de equipamentos/produtos/estoque (`fiduciary_alienation_equipment`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_equipment", "additional_documents": [ { "document_type": "equipment_purchase_invoice", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "equipment_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `equipment_purchase_invoice` | Nota fiscal de compra. | Sim | | `equipment_appraisal_report` | Laudo de avaliação de equipamentos. | Sim | | `equipment_insurance_policy` | Apólice de seguro de equipamentos (se exigível). | - | | `fiduciary_depositary_declaration` | Declaração de fiel depositário. | - | | `others` | Outros documentos. | - | ### Alienação fiduciária de obras de arte (`fiduciary_alienation_artwork`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_artwork", "additional_documents": [ { "document_type": "artwork_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "artwork_storage_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `artwork_appraisal_report` | Laudo de avaliação de obras de arte. | Sim | | `artwork_storage_certificate` | Certificado de adequação do local de armazenamento. | Sim | | `artwork_insurance_policy` | Apólice de seguro (se exigível). | - | | `others` | Outros documentos. | - | ### Alienação fiduciária de títulos e valores mobiliários (`fiduciary_alienation_securities`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_alienation_securities", "additional_documents": [ { "document_type": "securities_negotiation_block", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `securities_negotiation_block` | Bloqueio para negociação junto ao custodiante. | Sim | | `securities_registration_gravame` | Registro do gravame. | - | | `others` | Outros documentos. | - | ### Alienação fiduciária / penhor de ações e cotas (`fiduciary_assignment_shares`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "fiduciary_assignment_shares", "additional_documents": [ { "document_type": "share_registration_book", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `share_registration_book` | Livro de registro de ações nominativas com anotação do gravame. | Sim | | `others` | Outros documentos. | - | ### Hipoteca de imóveis (`mortgage_property`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "mortgage_property", "additional_documents": [ { "document_type": "property_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_registration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "property_full_content_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `property_appraisal_report` | Laudo de avaliação do imóvel. | Sim | | `property_registration` | Registro de propriedade atualizado. | Sim | | `property_full_content_certificate` | Certidão de inteiro teor da matrícula. | Sim | | `property_insurance_policy` | Apólice de seguro (se exigível no contrato). | - | | `others` | Outros documentos. | - | ### Hipoteca de embarcações (`mortgage_ship`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "mortgage_ship", "additional_documents": [ { "document_type": "ship_registration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "ship_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `ship_registration` | Registro de propriedade da embarcação atualizado. | Sim | | `ship_appraisal_report` | Laudo de avaliação da embarcação. | Sim | | `ship_insurance_policy` | Apólice de seguro da embarcação (se exigível). | - | | `others` | Outros documentos. | - | ### Aval (`guarantor`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "guarantor", "additional_documents": [ { "document_type": "guarantor_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `guarantor_civil_status_declaration` | Declaração de estado civil do avalista. | Sim | | `guarantor_personal_document` | Documento pessoal do avalista. | - | | `guarantor_income_tax_declaration` | Declaração de imposto de renda do avalista. | - | | `others` | Outros documentos. | - | ### Fiança (fiador) (`surety`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "surety", "additional_documents": [ { "document_type": "surety_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "surety_personal_document", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "surety_income_tax_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `surety_civil_status_declaration` | Declaração de estado civil do fiador. | Sim | | `surety_personal_document` | Documento pessoal do fiador. | Sim | | `surety_income_tax_declaration` | Declaração de imposto de renda do fiador. | Sim | | `others` | Outros documentos. | - | ### Seguro (`insurance`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "insurance", "additional_documents": [ { "document_type": "insurance_policy_endorsed", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "insurance_policy_with_expiration_and_renewal", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `insurance_policy_endorsed` | Apólice de seguro endossada. | Sim | | `insurance_policy_with_expiration_and_renewal` | Apólice de seguro com vigência e renovação. | Sim | | `others` | Outros documentos. | - | ### Monitoramento de garantias (`monitoring_guarantee`) Request Body ```json { "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b", "collateral_type": "monitoring_guarantee", "additional_documents": [ { "document_type": "guarantee_contract", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }, { "document_type": "guarantee_agent_contract", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ] } ``` #### Tipos de documentos | Enum | Descrição | Obrigatório | |------|-----------|-------------| | `guarantee_contract` | Contrato de garantia. | Sim | | `guarantee_agent_contract` | Contrato de agente de garantia. | Sim | | `others` | Outros documentos. | - | --- ## Request Body Params | Campo | Tipo | Descrição | Obrigatório | |-------|------|-----------|-------------| | `collateral_document_key` * | string | Chave do documento do instrumento de garantia. | Sim | | `collateral_type` * | string | Tipo da garantia. | **[Enumeradores collateral_type](#enumeradores-collateral_type)** | | `additional_documents` | array | Documentos adicionais da garantia. | - | ### additional_documents | Campo | Tipo | Descrição | Obrigatório | |-------|------|-----------|-------------| | `document_key` * | string | Chave do documento. | Sim | | `document_type` * | string | Tipo do documento. | Sim | ### Enumeradores collateral_type | Enum | Descrição | |------|-----------| | `fiduciary_alienation_property` | Alienação fiduciária de imóvel. | | `fiduciary_alienation_vehicle` | Alienação fiduciária de veículo. | | `fiduciary_alienation_aircraft` | Alienação fiduciária de aeronave. | | `fiduciary_alienation_equipment` | Alienação fiduciária de equipamentos/produtos/estoque. | | `fiduciary_alienation_artwork` | Alienação fiduciária de obras de arte. | | `fiduciary_alienation_securities` | Alienação fiduciária de títulos e valores mobiliários. | | `fiduciary_assignment_shares` | Alienação fiduciária / penhor de ações e cotas. | | `mortgage_property` | Hipoteca de imóveis. | | `mortgage_ship` | Hipoteca de embarcações. | | `guarantor` | Aval. | | `surety` | Fiança (fiador). | | `insurance` | Seguro. | | `monitoring_guarantee` | Monitoramento de garantias. | | `bank_surety` | Fiança bancária. | | `fiduciary_assignment_credit_rights` | Cessão fiduciária de direitos creditórios. | | `card_receivables` | Recebíveis de cartão. | | `stock_guarantee` | Garantia de estoque. | | `others` | Outras garantias. | ## Response O corpo da resposta é um JSON completo da operação atualizada, com a nova garantia em `collateral_list`. --- --- # Alteração de Cadastro do Emissor URL: /documentation/escrituracao/homologacao-emissor/alteracao-cadastro/ Para realizar alterações no cadastro do Emissor, é necessário que seu status seja definido para "in_filling", isto irá habilitar novamente todos os endpoints de inclusão/remoção. Após realizadas as modificações, o cadastro deve ser novamente enviado para análise com o status "in_analysis". --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "issuer_status": "in_filling" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | | ------------------ | ------ | ---------------------------------------------------- | ------------ | | `issuer_status`* | string | Novo status do emissor. Valor aceito:`in_filling`. | Sim | ## Response A resposta é um json completo atualizado do emissor. --- # Consulta da Auto-assinatura URL: /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: /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: /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: /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. | --- # Cadastro de Grupos de Assinantes do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor Este endpoint permite o cadastro de grupos de assinantes associados a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- | | `minimum_required_signers` * | integer | Número mínimo de assinantes necessários para validar o grupo. | - | | `signers` * | array | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** | ### Objeto Signer | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Nome completo do assinante. | 255 | | `document_number` * | string | CPF do assinante (formatação "XXX.XXX.XXX-XX"). | 11 | | `email` * | string | Endereço de email do assinante. | 1023 | | `phone_number`* | string | Número de telefone do assinante (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20 | | `is_group_mandatory` * | boolean | Indica se o assinante é obrigatório ou opcional dentro do grupo. | - | ## Response STATUS 201 Response Body ```json { "signer_group_key": "123e4567-e89b-12d3-a456-426614174000", "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- | | `signer_group_key` | string | Identificador único do grupo de assinantes (UUID v4). | 36 | | `minimum_required_signers` | integer | Número mínimo de assinantes necessários no grupo. | - | | `signers` * | array | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** | --- # Remoção de Grupos de Assinantes do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao Este endpoint permite a remoção de grupos de assinantes associados a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group/ SIGNER-GROUP-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|----------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `SIGNER-GROUP-KEY` | string | Chave única do grupo de assinantes a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro Básico do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico Este endpoint permite cadastrar as informações básicas de um emissor. ## Request ENDPOINT /issuer_management/issuer MÉTODO POST ### Request Body Request Body ```json { "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "trading_name": "Exemplo Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- | | `name` * | string | Nome completo da empresa. | 255 | | `document_number` * | string | CNPJ da empresa (formato "XX.XXX.XXX/XXXX-XX"). | 14 | | `trading_name`* | string | Nome fantasia da empresa. | 1023 | | `cnae_code`* | string | Código CNAE da empresa (formato "XX.XX-X-XX"). | 7 | | `company_type`* | string | Tipo da empresa. | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date`* | string | Data de fundação da empresa (formato "YYYY-MM-DD"). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address) | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `is_in_national_financial_system` | boolean | Indicador se o cedente é integrante do SFN. | - | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` * | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (formato "XXXXX-XXX"). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores company_type | Enum | Description | | -------- | ------------------ | | `ltda` | Limitada | | `sa` | Sociedade Anônima | | `cop` | Cooperativa | ## Response STATUS 201 Response Body ```json { "issuer_key": "123e4567-e89b-12d3-a456-426614174000", "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "status": "in_filling", "person_type": "legal", "trading_name": "Exemplo Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2023-01-01T12:00:00Z", "expiration_date": "2024-01-01T12:00:00Z", "payment_bank_account": { "account_number": "19500", "account_digit": "7", "account_branch": "0001" }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` ### Response Body Params | Campo | Tipo | Descrição | Caracteres Máx. | | ------------------------- | ------ | ----------------------------------- | -------------------------------------------------------------- | | `issuer_key` | string | Chave única do emissor (UUID). | 36 | | `name` | string | Nome completo do emissor. | 255 | | `document_number` | string | CNPJ do emissor. | 14 | | `status` | string | Status do emissor. | - | | `person_type` | string | Tipo de pessoa | **[Enumeradores person_type](#enumeradores-person_type)** | | `trading_name` | string | Nome fantasia do emissor. | 1023 | | `cnae_code` | string | Código CNAE do emissor. | 7 | | `company_type` | string | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date` | string | Data de fundação do emissor. | - | | `address` | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `registration_datetime` | string | Data e hora de registro do emissor. | - | | `expiration_date` | string | Data de expiração do emissor. | - | | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `is_in_national_financial_system` | boolean | Indicador se o cedente é integrante do SFN. | - | ### Enumeradores person_type | Enum | Description | | ----------- | ---------------- | | `legal` | Pessoa Jurídica | | `natural` | Pessoa Física | :::warning Aviso Ao cadastrar um emissor é reservada uma conta interna que será aberta somente se uma operação for concretizada. ::: ### Objeto payment_bank_account | Campo | Tipo | Descrição | Caracteres Máx. | | -------------------- | ------ | --------------------------- | ---------------- | | `account_digit` * | string | Dígito da conta bancária. | - | | `account_branch` * | string | Agência bancária. | - | | `account_number` * | string | Número da conta bancária. | - | --- # Cadastro de Conta Bancária do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor Este endpoint permite o cadastro de conta bancária associada a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. Deve conter apenas dígitos. | 20 | | `account_digit` * | string | Dígito verificador da conta. Deve conter um único dígito. | 1 | | `account_branch` * | string | Número da agência bancária. Deve conter apenas dígitos. | 6 | | `financial_institution_code_number`* | string | Código da instituição financeira (3 dígitos). | 3 | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira (8 dígitos). | 8 | | `account_type` * | string | Tipo da conta bancária. | **[Enumeradores account_type](#enumeradores-account_type)** | ### Enumeradores account_type | Enum | Description | | ------------ | ------------------ | | `checking` | Conta corrente | | `savings` | Conta Poupança | | `salary` | Conta Salário | | `payment` | Conta de Pagamento | ## Response STATUS 201 Response Body ```json { "bank_account_key": "123e4567-e89b-12d3-a456-426614174000", "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `bank_account_key` | string | Identificador único da conta bancária cadastrada (UUID v4). | 36 | | `account_number` | string | Número da conta bancária. | 20 | | `account_digit` | string | Dígito verificador da conta bancária. | 1 | | `account_branch` | string | Número da agência bancária. | 6 | | `financial_institution_code_number` | string | Código da instituição financeira. | 3 | | `financial_institution_ispb` | string | Código ISPB da instituição financeira. | 8 | | `account_type` | string | Tipo da conta bancária. | **[Enumeradores account_type](#enumeradores-account_type)** | --- # Definição de Conta Bancária Principal do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal Este endpoint promove uma conta bancária existente do emissor a conta principal (`is_default: true`). A conta anteriormente marcada como principal passa automaticamente a `is_default: false`. --- ## Trocando a conta bancária principal do emissor O emissor pode ter várias contas bancárias cadastradas, e apenas uma é marcada como principal. Para corrigir uma conta principal com dados incorretos (dígito, agência, ISPB), use o fluxo abaixo. :::warning Pré-requisito O emissor precisa estar no status `in_filling`. Após esse status, a conta principal não pode ser alterada — comportamento intencional, dado que a conta principal é referenciada em operações financeiras. ::: ### Fluxo de troca (3 chamadas) 1. **POST** `.../bank_account` → cria a nova conta (correta). 2. **POST** `.../bank_account/{key}/set_default` → promove a nova conta a principal. 3. **DELETE** `.../bank_account/{old_key}` → remove a conta antiga. A mesma restrição de ordem se aplica: como não é permitido deletar a conta principal, a promoção precisa vir antes da remoção. Tentar inverter retorna `HTTP 400 / ISS0000012`. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY /set_default MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|--------------------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `BANK-ACCOUNT-KEY` | string | Chave única da conta bancária que será promovida a principal (UUID v4). | 36 | ### Request Body Nenhum conteúdo é enviado no corpo da requisição. --- ## Response STATUS 204 Conta promovida a principal. Nenhum conteúdo é retornado no corpo da resposta. --- ## Erros | HTTP | Código | Cenário | |------|--------------|------------------------------------------------------------------------| | 400 | `ISS0000011` | Emissor não está em `in_filling`. | | 403 | `ISS000011` | Tenant não tem acesso a esse emissor. | | 404 | `ISS000005` | `bank_account_key` não encontrado para esse emissor. | | 404 | `ISS000009` | `issuer_key` não encontrado. | --- # Remoção de Conta Bancária do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao Este endpoint permite a remoção de conta bancária associada a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `BANK-ACCOUNT-KEY` | string | Chave única da conta bancária a ser removida (UUID v4).| 36 | --- ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- ## Observações - Não é permitido remover a conta marcada como principal (`is_default: true`). A tentativa retorna `HTTP 400 / ISS0000012`. Para trocar a conta principal, veja o fluxo completo em [Definição de conta bancária principal](./conta-bancaria-emissor-principal.md). - Alterações em conta principal só são permitidas com o emissor em `in_filling`. Fora desse status, a operação retorna `HTTP 400 / ISS0000011`. --- --- # Envio de Documentos do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor Este endpoint permite o envio de documentos associados a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "proof_of_address" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ------------------------------------------------------- | ---------------------------------------------------------------- | | `document_base64` * | string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | ### Enumeradores document_type | Enum | Description | | ------------------------------- | ---------------------------------- | | `proof_of_address` | Comprovante de Endereço | | `letter_of_attorney` | Procuração | | `company_statute` * | Contrato ou Estatuto Social | | `commercial_board_certificate` | Certificado da Junta Comercial | | `board_election_record` | Ata de Eleição da Diretoria | | `manager_declaration` | Declaração do Gestor | | `financial_statement` | Balanço Financeiro | | `credit_report` | Relatório de Crédito | | `manager_statement` | Declaração do Administrador | | `compliance_statement` | Declaração de Conformidade | | `cnpj_card` | Cartão CNPJ | | `additional_document` | Documento Adicional | :::warning Atenção O **company_statute** é obrigatório para todos os cadastros. ::: ## Response STATUS 201 Response Body **Cenário 1: Validação Automática (Sucesso no OCR)** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_address", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **Significado**: O documento foi processado e validado automaticamente pelo nosso OCR. **Cenário 2: Verificação Manual Necessária** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnpj_card", "ocr_key": null } ``` **Significado**: O documento não pôde ser validado automaticamente pelo OCR e foi encaminhado para nossa fila de verificação manual. :::warning Atenção A resposta para requisições bem-sucedidas (sucesso no envio) apresenta dois comportamentos distintos, dependendo do resultado da validação automática (OCR). ::: ### Response Body Params | Field | Type | Description | Max Length | | ----------------- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------- | | `document_key` | string | Identificador único do documento enviado (UUID v4). | 36 | | `document_type` | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- # Remoção de Documentos do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao Este endpoint permite a remoção de documentos enviados para o cadastro do emissor. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------|--------|------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Envio de Documentos do Representante do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor Este endpoint permite o envio de documentos associados a um representante de um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | Chave única do representante do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------| | `document_base64` *| string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. Valores aceitos: | **[Enumeradores document_type](#enumeradores-document_type)** | ### Enumeradores document_type | Enum | Description | | ------------------------------- | ---------------------------------- | | `cnh` | Carteira Nacional de Habilitação | | `cnh_front` | Frente da CNH | | `cnh_back` | Verso da CNH | | `cnh_digital` | CNH Digital | | `rg_front` | Frente do RG | | `rg_back` | Verso do RG | | `proof_of_address` | Comprovante de Endereço | | `letter_of_attorney` | Procuração | | `passport` | Passaporte | | `national_registry_of_foreigners`| Registro Nacional de Estrangeiros | :::warning Atenção É obrigatório para todos os cadastros pelo menos um documento identificador (cnh, rg, passport ou national_registry_of_foreigners) e caso o tipo do representante seja **attorney**, é necessário também uma procuração (letter_of_attorney). ::: ## Response STATUS 201 Response Body **Cenário 1: Validação Automática (Sucesso no OCR)** ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf" } ``` **Significado**: O documento foi processado e validado automaticamente pelo nosso OCR. **Cenário 2: Verificação Manual Necessária** ```json { "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3", "document_type": "cnh", "ocr_key": null } ``` **Significado**: O documento não pôde ser validado automaticamente pelo OCR e foi encaminhado para nossa fila de verificação manual. :::warning Atenção A resposta para requisições bem-sucedidas (sucesso no envio) apresenta dois comportamentos distintos, dependendo do resultado da validação automática (OCR). ::: ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |------------------|----------|-----------------------------------------------------|-----------------------| | `document_key` | string | Identificador único do documento enviado (UUID v4). | 36 | | `document_type` | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- # Remoção de Documentos do Representante do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao Este endpoint permite a remoção de documentos associados a um representante de um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | Chave única do representante do emissor (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro de Informações de Contato do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor Este endpoint permite o cadastro de informações de contato associadas a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Nome completo do contato. | 255 | | `document_number` * | string | Número do documento do contato (formato CPF, formato "XXX.XXX.XXX-XX"). | 14 | | `email`* | string | Endereço de email do contato. | 1023 | | `phone_number`* | string | Número de telefone do contato (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20 | ## Response STATUS 201 Response Body ```json { "issuer_contact_information_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ---------------------------------- | ------ | --------------------------------------------------------------------- | --------------------- | | `issuer_contact_information_key` | string | Identificador único da informação de contato cadastrada (UUID v4). | 36 | | `name` | string | Nome completo do contato. | 255 | | `document_number` | string | Número do documento do contato (CPF). | 11 | | `email` | string | Endereço de email do contato. | 1023 | | `phone_number` | string | Número de telefone do contato. | 20 | --- # Definição de Contato Principal do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal Este endpoint promove um contato existente do emissor a contato principal (`is_default: true`). O contato anteriormente marcado como principal passa automaticamente a `is_default: false`. --- ## Trocando o contato principal do emissor O emissor pode ter múltiplos contatos cadastrados, mas apenas um é marcado como principal. Caso o contato principal tenha sido cadastrado com um dado incorreto (typo no e-mail, dígito errado no telefone), use o fluxo abaixo para substituí-lo. :::warning Pré-requisito O emissor precisa estar no status `in_filling`. Após o emissor sair desse status, alterações em contato/conta principal não são permitidas — o endpoint retornará `HTTP 400 / ISS0000011`. ::: ### Fluxo de troca (3 chamadas) 1. **POST** `.../issuer_contact_information` → cria o novo contato (correto). 2. **POST** `.../issuer_contact_information/{key}/set_default` → promove o novo contato a principal. 3. **DELETE** `.../issuer_contact_information/{old_key}` → remove o contato antigo (com o typo). A ordem importa: como não é permitido deletar um contato marcado como principal, é obrigatório promover o novo contato antes de deletar o antigo. Tentar inverter retorna `HTTP 400 / ISS0000013`. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY /set_default MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------------------------|--------|-----------------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-CONTACT-INFORMATION-KEY` | string | Chave única do contato que será promovido a principal (UUID v4).| 36 | ### Request Body Nenhum conteúdo é enviado no corpo da requisição. --- ## Response STATUS 204 Contato promovido a principal. Nenhum conteúdo é retornado no corpo da resposta. --- ## Erros | HTTP | Código | Cenário | |------|--------------|------------------------------------------------------------------------| | 400 | `ISS0000011` | Emissor não está em `in_filling`. | | 403 | `ISS000011` | Tenant não tem acesso a esse emissor. | | 404 | `ISS000008` | `issuer_contact_information_key` não encontrado para esse emissor. | | 404 | `ISS000009` | `issuer_key` não encontrado. | --- # Remoção de Informações de Contato do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao Este endpoint a remoção de informações de contato associadas a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------------------------|--------|-----------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-CONTACT-INFORMATION-KEY` | string | Chave única da informação de contato a ser removida (UUID v4).| 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- ## Observações - Não é permitido remover o contato marcado como principal (`is_default: true`). A tentativa retorna `HTTP 400 / ISS0000013`. Para trocar o contato principal, veja o fluxo completo em [Definição de contato principal](./informacao-contato-emissor-principal.md). - Alterações em contato principal só são permitidas com o emissor em `in_filling`. Fora desse status, a operação retorna `HTTP 400 / ISS0000011`. --- # Cadastro de Representantes do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor Este endpoint permite o cadastro de representantes associados a um emissor previamente cadastrado. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "name": "João da Silva", "document_number": "123.456.789-01", "birthdate": "1990-01-01", "nationality": "BRA", "mother_name": "Maria da Silva", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "related_party_type": "attorney", "annual_revenues": 150000, } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ---------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | `name` * | string | Nome completo do representante do emissor. | 255 | | `document_number` * | string | Número do documento (CPF, no formato "XXX.XXX.XXX-XX"). | 11 | | `birthdate` | string | Data de nascimento do representante no formato ISO 8601 (YYYY-MM-DD). | - | | `document_identification_number` | string | Número do documento de identificação. | 255 | | `marital_status` | string | Estado civil do representante. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system` | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `mother_name` | string | Nome completo da mãe do representante. | 1023 | | `father_name` | string | Nome completo do pai do representante. | 1023 | | `occupation` | string | Ocupação ou profissão do representante. | 255 | | `is_pep` | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `related_party_type` * | enumerador | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (formato "XXXXX-XXX"). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores marital_status | Enum | Description | | ---------------- | ------------------ | | `single` | Solteiro(a) | | `married` | Casado(a) | | `widower` | Viúvo(a) | | `separated` | Separado(a) | | `stable_union` | em União Estável | | `divorced` | Divorciado(a) | ### Enumeradores property_system | Enum | Description | | --------------------------------------- | --------------------------------- | | `total_communion_of_goods` | Comunhão Total de Bens | | `partial_communion_of_goods` | Comunhão Parcial de Bens | | `total_separation_of_goods` | Separação Total de Bens | | `final_participation_of_acquisitions` | Participação Final nos Aquestos | | `compulsory_separation_of_goods` | Separação Compulsória de Bens | ### Related Party Type | Enumerador | Descrição | | ----------------------- | ------------- | | **president** | Presidente | | **partner** | Sócio | | **administrator** | Administrador | | **director** | Diretor | | **manager** | Gestor | | **attorney** | Procurador | --- ## Response STATUS 201 Response Body ```json { "issuer_representative_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "document_identification_number": "987654321", "marital_status": "single", "property_system": "partial_communion_of_goods", "birthdate": "1990-01-01", "nationality": "BRA", "mother_name": "Maria da Silva", "father_name": "José da Silva", "occupation": "Advogado", "is_pep": false, "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "related_party_type": "attorney", "annual_revenues": 150000, "issuer_representative_document_list": [] } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | --------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | `issuer_representative_key` | string | Identificador único do representante do emissor (UUID v4). | 36 | | `name` | string | Nome completo do representante do emissor. | 255 | | `document_number` | string | Número do documento do representante (formato "XXX.XXX.XXX-XX"). | 11 | | `document_identification_number` | string | Número do documento de identificação. | 255 | | `marital_status` | string | Estado civil do representante. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system` | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `birthdate` | string | Data de nascimento do representante. | - | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `mother_name` | string | Nome completo da mãe do representante. | 1023 | | `father_name` | string | Nome completo do pai do representante. | 1023 | | `occupation` | string | Ocupação ou profissão do representante. | 255 | | `is_pep` | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `issuer_representative_document_list` | array | Lista de documentos associados ao representante. | - | | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `related_party_type` * | enumerador | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | --- # Remoção de Representante do Emissor URL: /documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao Este endpoint permite a remoção de representantes enviados para o cadastro do emissor. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|--------------------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | | `ISSUER-REPRESENTATIVE-KEY` | string | Chave única do representante a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Consulta de Emissor URL: /documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave Este endpoint permite consultar os detalhes completos de um emissor cadastrado no sistema, utilizando sua chave única. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|------------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ## Response RESPONSE STATUS 200 Response Body com status *in_filling* ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "in_filling", "backoffice_analysis_status": "in_analysis", "person_type": "legal", "trading_name": "Fabrica Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2025-01-23T13:47:57.354528", "expiration_date": "2026-01-23", "signer_group_list": [], "bank_account_list": [], "issuer_representative_list": [], "issuer_contact_information_list": [], "issuer_document_list": [], "issuer_analysis_list": [], "payment_bank_account": { "account_number": "19500", "account_digit": "7", "account_branch": "0001" }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` RESPONSE STATUS 200 Response Body com status *reproved* ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "reproved", "backoffice_analysis_status": "reproved", "person_type": "legal", "trading_name": "Fabrica Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2025-01-23T13:47:57.354528", "expiration_date": "2026-01-23", "bank_account_list": [ { "bank_account_key": "b6546f3b-329a-4703-addd-ac2fb34a8eea", "account_number": "7567236", "account_digit": "9", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking", "is_default": true } ], "signer_group_list": [ { "minimum_required_signers": 1, "signers": [ { "name": "Jose Representante", "document_number": "037.208.830-94", "email": "037.208.830-94@yopmail.com", "is_group_mandatory": false } ] } ], "issuer_representative_list": [ { "name": "Jose Representante", "document_number": "037.208.830-94", "nationality": "BRA", "related_party_type": "partner", "issuer_representative_document_list": [] } ], "issuer_contact_information_list": [ { "name": "Fabrica Exemplo S.A.", "phone_number": "+5516282399722", "is_default": true, "email": "email@yopmail.com", "document_number": "96.146.194/0001-07" } ], "issuer_document_list": [], "issuer_analysis_list": [], "last_analysis": { "analysis_key": "a274106e-5dbe-4a87-8999-6e41020f09b9", "analysis_number": 3, "status": "reproved", "analysis_datetime": "2025-10-24 02:52:15.886432", "analysis_related_parties": [ { "analysis_related_party_key": "e634cbb5-6b6a-42b6-9348-7cb449f646ca", "name": "Jose Representante", "document_number": "037.208.830-94", "analysis_roles": [ { "related_party_type": "partner" } ], "documents": [ { "document_key": "2b8ab03b-3896-43e9-9e5a-5e3c461164ef", "status": "canceled", "document_type": "cnh", "observation": null }, { "document_key": "77f38757-4688-4027-a19a-b7066747b3b5", "status": "valid", "document_type": "cnh", "observation": null } ] } ], "documents": [ { "document_key": "0ced115e-c008-4fae-93cd-b78c3f7d384d", "document_type": "social_contract", "status": "valid", "observation": null } ], "annotations": [], "last_updated": "2025-10-24 02:52:20.169204", "analysis_origin_type": "nce_integration", "reproval_reason": "missing_related_parties", "reproval_details": "parte relacionada João Representante consta no contrato social mas não está cadastrado" }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` RESPONSE STATUS 200 Response Body com status *approved* ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "approved", "backoffice_analysis_status": "approved", "person_type": "legal", "trading_name": "Fabrica Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2025-01-23T13:47:57.354528", "expiration_date": "2026-01-23", "bank_account_list": [ { "bank_account_key": "b6546f3b-329a-4703-addd-ac2fb34a8eea", "account_number": "7567236", "account_digit": "9", "account_branch": "0001", "financial_institution_code_number": "329", "financial_institution_ispb": "32402502", "account_type": "checking", "is_default": true } ], "signer_group_list": [ { "minimum_required_signers": 1, "signers": [ { "name": "Jose Representante", "document_number": "037.208.830-94", "email": "037.208.830-94@yopmail.com", "is_group_mandatory": false } ] } ], "issuer_representative_list": [ { "name": "Jose Representante", "document_number": "037.208.830-94", "nationality": "BRA", "related_party_type": "partner", "issuer_representative_document_list": [] } ], "issuer_contact_information_list": [ { "name": "Fabrica Exemplo S.A.", "phone_number": "+5516282399722", "is_default": true, "email": "email@yopmail.com", "document_number": "96.146.194/0001-07" } ], "issuer_document_list": [], "issuer_analysis_list": [], "last_analysis": { "analysis_key": "a274106e-5dbe-4a87-8999-6e41020f09b9", "analysis_number": 3, "status": "approved", "analysis_datetime": "2025-10-24 02:52:15.886432", "analysis_related_parties": [ { "analysis_related_party_key": "e634cbb5-6b6a-42b6-9348-7cb449f646ca", "name": "Jose Representante", "document_number": "037.208.830-94", "analysis_roles": [ { "related_party_type": "partner" } ], "documents": [ { "document_key": "2b8ab03b-3896-43e9-9e5a-5e3c461164ef", "status": "canceled", "document_type": "cnh", "observation": null }, { "document_key": "77f38757-4688-4027-a19a-b7066747b3b5", "status": "valid", "document_type": "cnh", "observation": null } ] } ], "documents": [ { "document_key": "0ced115e-c008-4fae-93cd-b78c3f7d384d", "document_type": "social_contract", "status": "valid", "observation": null } ], "annotations": [], "last_updated": "2025-10-24 02:52:20.169204", "analysis_origin_type": "nce_integration", "reproval_reason": null, "reproval_details": null }, "annual_revenues": 150000, "is_in_national_financial_system": false } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |--------|----------|--------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | Identificador único do emissor. | 36 | | `name` | string | Nome completo do emissor. | 255 | | `document_number` | string | Número do documento do emissor (CNPJ). | 14 | | `status` | string | Status do emissor | **[Enumeradores status](#enumeradores-status)** | | `backoffice_analysis_status`| string | Status de análise do backoffice. | - | | `person_type` | string | Tipo de pessoa (`legal` ou `natural`). | - | | `trading_name` | string | Nome fantasia do emissor. | 1023 | | `cnae_code` | string | Código CNAE do emissor. | 10 | | `company_type` | string | Tipo de empresa: ´sa´, ´ltda´, ´cop´, ´-´ | 50 | | `foundation_date` | string | Data de fundação do emissor. | - | | `signer_group_list` | array | Lista de grupos de assinantes associados ao emissor. | - | | `bank_account_list` | array | Lista de contas bancárias associadas ao emissor. | - | | `issuer_representative_list` | array | Lista de representantes do emissor. | - | | `issuer_contact_information_list` | array | Lista de informações de contato associadas ao emissor. | - | | `issuer_document_list` | array | Lista de documentos cadastrados para o emissor. | - | | `address` | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `is_in_national_financial_system` | boolean | Indicador se o cedente é integrante do SFN. | - | | `last_analysis` | object | Objeto de análise. | **[Definição de Análise](#definição-de-análise)**. | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` | string | Número do endereço. | 10 | | `postal_code` | string | CEP do endereço (somente números). | 8 | | `city` | string | Nome da cidade do endereço. | 255 | | `state` | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | ### Objeto payment_bank_account | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_digit` | string | Dígito da conta bancária. | - | | `account_branch` | string | Agência bancária. | - | | `account_number` | string | Número da conta bancária. | - | ### Definição de Análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_key` | string | Identificador da análise. | 36 | | `analysis_number` | integer | Número sequencial da análise. | - | | `status` | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. | | `analysis_related_parties` | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. | | `documents` | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | | `analysis_data` | object | Payload da request que originou a análise. | - | | `analysis_datetime` | string | Objeto date time da criação da análise. | - | | `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. | | `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - | --- ### Analysis Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_documents** | Pendente Documentos | | **sent_to_analysis** | Enviado para Análise | | **pending_internal_validation** | Em Validação de documentos | | **in_manual_analysis** | Em Análise Manual de Compliance | | **approved** | Aprovado | | **reproved** | Reprovado | --- ### Definição de Documentos | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` | string | Identificador do documento. | 36 | | `document_type` | string | Tipo do documento. | | | `status` | string | Status do documento. | | | `observation` | string | Observações enviadas. | - | --- ### Definição de Partes Relacionadas de análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_related_party_key` | string | Identificador da parte relacionada. | 36 | | `document_number` | string | Número de documento da parte relacionada. | 14 a 18 | | `name` | string | Nome da parte relacionada. | 1 a 255 | | `documents` | array | Documentos da anáise da parte relacionada. | | --- ### Analysis Reproval Reason | Enum | Description | |--------------|---------------| | **assignor_update** | Análise cancelada devido à atualização cadastral posterior | | **insuficient_documents** | Documentação mínima para comprovação de poderes não enviada | | **compliance_reproval** | Reprovação de vínculo por análise do time de compliance | | **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado | | **invalid_documents** | Documentação inválida/expirada | | **missing_related_parties** | Parte relacionada obrigatória não enviada | --- --- # Consulta de Emissores por filtros URL: /documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro Este endpoint permite consultar emissores cadastrados no sistema utilizando o número de documento (CNPJ) ou Nome. --- ## Request ENDPOINT /issuer_management/issuer MÉTODO GET ### Query Params | Campo | Tipo | Descrição | Obrigatório | |-------------------|----------|------------------------------------|-------------| | `document_number` | string | Número do documento do emissor. | Não | | `name` | string | Nome do emissor. | Não | | `page` | integer | Página atual da consulta. | Não | | `rows_per_page` | integer | Número de registros por página. | Não | ## Response STATUS 200 Response Body ```json { "data": [ { "issuer_key": "495ae701-5c38-49b1-b517-a3b910fe8d8f", "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "status": "in_filling" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 1 } } ``` ### Response Body Params | Campo | Tipo | Descrição | | |--------------|--------|---------------------|-----------------------------------------------------------------| | `data` | list | Lista de resultados | **[Objeto Emissor Simplificado](#objeto-emissor-simplificado)** | | `pagination` | object | Dados de paginação | **[Objeto Paginação](#objeto-paginacao)** | ### Objeto Emissor Simplificado | Campo | Tipo | Descrição | Máximo de Caracteres | |-------------------|----------|-------------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | Identificador único do emissor (UUID v4). | 36 | | `name` | string | Nome completo do emissor. | 255 | | `document_number` | string | Número do documento do emissor (CNPJ). | 14 | | `status` | string | Status atual do emissor. | **[Enumeradores status](#enumeradores-status)** | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | ### Objeto Pagination | Campo | Tipo | Descrição | |-------------------|----------|------------------------------------------| | `current_page` | integer | Página atual da consulta. | | `next_page` | integer | Próxima página, caso exista. | | `rows_per_page` | integer | Número de registros por página. | | `total_pages` | integer | Número total de páginas. | | `total_rows` | integer | Número total de registros encontrados. | --- # Envio para Análise do Emissor URL: /documentation/escrituracao/homologacao-emissor/envio-analise/ Este endpoint permite alterar o status de um emissor para análise, enviando-o para o processo de validação. --- ## Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ------ | ---------------------------------- | ---------- | | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | ### Request Body Request Body ```json { "issuer_status": "in_analysis" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | | ----------------- | ------ | ------------------------------------------------------- | ------------ | | `issuer_status` | string | Novo status do emissor. Valor aceito: `in_analysis`. | Sim | ## Response A resposta é um json completo atualizado do emissor. --- # Introdução URL: /documentation/escrituracao/homologacao-emissor/inicio A parte de cadastro de Emissores é essencial para o início da emissão de Notas Comerciais. Nessa seção iremos explicar todo o fluxo, desde o envio das primeiras informações, até o envio para análise. Para ter acesso aos serviços discutidos nas próximas sessões, entre em contato com o time [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox) quanto em ambiente de produção. ### Cadastro do Emissor Nessa etapa, deve-se enviar todas as informações tanto do Emissor quanto dos seus representantes, documentos, informações de contato, grupos de assinantes e contas bancárias. Uma vez que o envio das informações estiver concluído, o cadastro é enviado para análise do time de cadastro de cedentes e após aprovação este emissor estará apto a participar da emissão de Notas. Caso o cadastro já tenha sido feito na plataforma da QI CTVM de cadastro de cedentes, é possível reaproveitar esse cadastro de forma simples, utilizando o endpoint de solicitação de acesso ao cadastro. ### Auto-assinatura do Emissor Clientes habilitados para auto-assinatura contam com um fluxo adicional: após a aprovação do cadastro, o emissor assina uma única vez um termo de adesão e passa a ter os documentos das emissões seguintes assinados automaticamente. Veja [Auto-assinatura do emissor](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio). ### Atualização de Emissor Em caso de necessidade de atualização cadastral, deve-se enviar novamente todas as informações do Emissor com as modificações desejadas. Após envio, é gerada uma nova Análise para validação. Assim que esta nova Análise for aprovada, os novos dados cadastrais do Emissor são efetivamente alterados. --- # Solicitação de Acesso aos Dados do Emissor URL: /documentation/escrituracao/homologacao-emissor/solicitacao-acesso Clientes que cadastraram um emissor que já possui um **cadastro na homologação de cedente** precisam **solicitar acesso aos dados do emissor** para que possam emitir operações com esse emissor como parte no sistema de escrituração. --- ## **Solicitação de Acesso (POST)** ### **Request** ENDPOINT /issuer_management/issuer/data_access_request MÉTODO POST --- ## **Request Body** Request Body ```json { "document_number": "96.146.194/0001-07", } ``` --- ## **Response** STATUS 201 Response Body ```json { "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "approved", "backoffice_analysis_status": "approved", "person_type": "legal", "trading_name": "Fabrica Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2025-01-23T13:47:57.354528", "expiration_date": "2026-01-23", "signer_group_list": [ { "signer_group_key": "123e4567-e89b-12d3-a456-426614174000", "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ], "bank_account_list": [ { "bank_account_key": "123e4567-e89b-12d3-a456-426614174000", "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ], "issuer_representative_list": [ { "issuer_representative_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "document_identification_number": "987654321", "marital_status": "single", "property_system": "partial_communion_of_goods", "birthdate": "1990-01-01", "nationality": "BRA", "mother_name": "Maria da Silva", "father_name": "José da Silva", "occupation": "Advogado", "is_pep": false, "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "related_party_type": "attorney", "annual_revenues": 150000, "issuer_representative_document_list": [ { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ] } ], "issuer_contact_information_list": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ], "issuer_document_list": [ { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_address", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ], "issuer_analysis_list": [], "payment_bank_account": { "account_number": "19500", "account_digit": "7", "account_branch": "0001" } } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |--------|----------|--------------------------------------------------------|-------------------------------------------------| | `issuer_key` | string | Identificador único do emissor. | 36 | | `name` | string | Nome completo do emissor. | 255 | | `document_number` | string | Número do documento do emissor (CNPJ). | 14 | | `status` | string | Status do emissor | **[Enumeradores status](#enumeradores-status)** | | `backoffice_analysis_status`| string | Status de análise do backoffice. | - | | `person_type` | string | Tipo de pessoa (`legal` ou `natural`). | - | | `trading_name` | string | Nome fantasia do emissor. | 1023 | | `cnae_code` | string | Código CNAE do emissor. | 10 | | `company_type` | string | Tipo de empresa Aceitos: ´sa´, ´ltda´, ´cop´ | 50 | | `foundation_date` | string | Data de fundação do emissor. | - | | `signer_group_list` | array | Lista de grupos de assinantes associados ao emissor. | - | | `bank_account_list` | array | Lista de contas bancárias associadas ao emissor. | - | | `issuer_representative_list` | array | Lista de representantes do emissor. | - | | `issuer_contact_information_list` | array | Lista de informações de contato associadas ao emissor. | - | | `issuer_document_list` | array | Lista de documentos cadastrados para o emissor. | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (somente números). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | ### Objeto payment_bank_account | Campo | Tipo | Descrição | Caracteres Máx. | |-------------------------------------|----------|------------------------------------------------|-----------------| | `account_digit` * | string | Dígito da conta bancária. | - | | `account_branch` * | string | Agência bancária. | - | | `account_number` * | string | Número da conta bancária. | - | --- # Alteraçao de Cadastro do Investidor URL: /documentation/escrituracao/homologacao-investidor/alteracao-cadastro/ Para realizar alterações no cadastro do Investidor, é necessário que seu status seja definido para "in_filling", isto irá habilitar novamente todos os endpoints de inclusão/remoção. Após realizadas as modificações, o cadastro deve ser novamente enviado para análise com o status "in_analysis". --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "investor_status": "in_filling" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |------------------|----------|-----------------------------------------------------|-------------| | `investor_status` | string | Novo status do investidor. Valor aceito: `in_filling`. | Sim | ## Response A resposta é um json completo atualizado do investidor. --- # Cadastro de Grupos de Assinantes do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor Este endpoint permite o cadastro de grupos de assinantes associados a um investidor previamente cadastrado. :::danger Atenção Não é possível adicionar grupo de assinantes para um investidor Pessoa Física (PF). ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- | | `minimum_required_signers` * | integer | Número mínimo de assinantes necessários para validar o grupo. | - | | `signers` * | array | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** | ### Objeto Signer | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Nome completo do assinante. | 255 | | `document_number` * | string | CPF do assinante (formato "XX.XXX.XXX/XXXX-XX"). | 11 | | `email` * | string | Endereço de email do assinante. | 1023 | | `phone_number`* | string | Número de telefone do assinante (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20 | | `is_group_mandatory` * | boolean | Indica se o assinante é obrigatório ou opcional dentro do grupo. | - | ## Response STATUS 201 Response Body ```json { "signer_group_key": "123e4567-e89b-12d3-a456-426614174000", "minimum_required_signers": 2, "signers": [ { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999", "is_group_mandatory": true }, { "name": "Maria Souza", "document_number": "123.456.789-01", "email": "maria.souza@email.com", "phone_number": "+5511988888888", "is_group_mandatory": false } ] } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- | | `signer_group_key` | string | Identificador único do grupo de assinantes (UUID v4). | 36 | | `minimum_required_signers` | integer | Número mínimo de assinantes necessários no grupo. | - | | `signers` * | array | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** | --- # Remoção de Grupos de Assinantes do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao Este endpoint permite a remoção de grupos de assinantes associados a um investidor previamente cadastrado. :::danger Atenção Não é possível remover grupo de assinantes de um investidor Pessoa Física (PF). ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group/ SIGNER-GROUP-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|----------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `SIGNER-GROUP-KEY` | string | Chave única do grupo de assinantes a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro Básico do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico Este endpoint permite cadastrar as informações básicas de um investidor. O mesmo endpoint é utilizado tanto para investidores **pessoa jurídica (PJ)** quanto **pessoa física (PF)** — o corpo da requisição varia de acordo com o campo `person_type`. ## Request ENDPOINT /investor_management/investor MÉTODO POST ### Request Body Caso 01: Pessoa Jurídica ```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" } } ``` Caso 02: Pessoa Física ```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": "engenheira de software", "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 Atenção Se o campo `person_type` for omitido, o cadastro é tratado como **Pessoa Jurídica** (`legal`). Para cadastrar um investidor **Pessoa Física**, envie `person_type: "natural"`. ::: ### Request Body Params — Pessoa Jurídica | Campo | Tipo | Descrição | Caracteres Máx. | | --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- | | `person_type` | string | Opcional. Se omitido, o cadastro é tratado como Pessoa Jurídica (`legal`). | **[Enumeradores person_type](#enumeradores-person_type)** | | `name` * | string | Nome completo da empresa. | 255 | | `document_number` * | string | CNPJ da empresa (formato "XX.XXX.XXX/XXXX-XX"). | 14 | | `trading_name`* | string | Nome fantasia da empresa. | 1023 | | `cnae_code`* | string | Código CNAE da empresa (formato "XXXXX-XXX"). | 7 | | `company_type`* | string | Tipo da empresa. | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date`* | string | Data de fundação da empresa (formato "YYYY-MM-DD"). | - | | `address` * | object | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | ### Request Body Params — Pessoa Física | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------------------------- | ------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `person_type` * | string | Deve ser enviado como `"natural"`. | **[Enumeradores person_type](#enumeradores-person_type)** | | `name` * | string | Nome completo do investidor. | 255 | | `document_number` * | string | CPF do investidor (formato "XXX.XXX.XXX-XX"). | 14 | | `document_identification_number`* | string | Número do documento de identidade do investidor (RG, CNH ou passaporte). | 255 | | `marital_status`* | string | Estado civil do investidor. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system` | string | Regime de bens. Obrigatório apenas quando `marital_status` exigir regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `birthdate`* | string | Data de nascimento do investidor (formato "YYYY-MM-DD"). | - | | `nationality`* | string | Nacionalidade do investidor. | **[Enumeradores nationality](#enumeradores-nationality)** | | `mother_name`* | string | Nome da mãe do investidor. | 1023 | | `father_name`* | string | Nome do pai do investidor. | 1023 | | `occupation`* | string | Ocupação/profissão do investidor. | 255 | | `is_pep`* | boolean | Indica se o investidor é uma Pessoa Politicamente Exposta. | - | | `email`* | string | E-mail de contato do investidor. | 1023 | | `phone_number`* | string | Telefone de contato do investidor. | 20 | | `investor_category` | string | Categoria autodeclarada do investidor. Opcional. | **[Enumeradores investor_category](#enumeradores-investor_category)** | | `investment_suitability` | string | Perfil de suitability autodeclarado do investidor. Opcional. | **[Enumeradores investment_suitability](#enumeradores-investment_suitability)** | | `address` * | object | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | -------------------------------------------- | ---------------- | | `street` * | string | Nome da rua do endereço. | 500 | | `neighborhood` * | string | Nome do bairro do endereço. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (formatação "XXXXX-XXX"). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores company_type | Enum | Description | | -------- | ------------------ | | `ltda` | Limitada | | `sa` | Sociedade Anônima | | `cop` | Cooperativa | ### Enumeradores marital_status | Enum | Description | | ------------- | ------------ | | `single` | Solteiro(a) | | `married` | Casado(a) | | `divorced` | Divorciado(a)| | `widowed` | Viúvo(a) | | `separated` | Separado(a) | ### Enumeradores property_system | Enum | Description | | ---------------------------------------- | --------------------------------------- | | `total_communion_of_goods` | Comunhão universal de bens | | `partial_communion_of_goods` | Comunhão parcial de bens | | `total_separation_of_goods` | Separação total de bens | | `final_participation_of_acquisitions` | Participação final nos aquestos | | `compulsory_separation_of_goods` | Separação obrigatória de bens | ### Enumeradores nationality Lista completa de códigos [ISO 3166-1 alpha-3](https://www.iso.org/obp/ui/#search) (ex.: `BRA` para Brasil, `USA` para Estados Unidos). ### Enumeradores investor_category | Enum | Description | | ------------------ | ------------------ | | `not_applicable` | Não aplicável | | `retail` | Varejo | | `qualified` | Qualificado | | `professional` | Profissional | ### Enumeradores investment_suitability | Enum | Description | | ------------- | ------------- | | `conservative` | Conservador | | `moderate` | Moderado | | `bold` | Arrojado | ## Response STATUS 201 Caso 01: Pessoa Jurídica ```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" } ``` Caso 02: Pessoa Física ```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": "engenheira de software", "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 Informação `investor_contact_information_list` e `signer_group_list` só são retornados quando o cadastro é feito com acesso completo (`data_access_type == full_access`). ::: ### Response Body Params | Campo | Tipo | Pessoa | Descrição | Caracteres Máx. | | ------------------------- | ------- | ----------- | ----------------------------------------- | ----------------------------------------------------------------- | | `investor_key` | string | Ambos | Chave única do investidor (UUID). | 36 | | `name` | string | Ambos | Nome completo (PF) ou razão social (PJ). | 255 | | `document_number` | string | Ambos | CPF (PF) ou CNPJ (PJ) do investidor. | 14 | | `status` | string | Ambos | Status do investidor. | - | | `person_type` | string | Ambos | Tipo de pessoa | **[Enumeradores person_type](#enumeradores-person_type)** | | `trading_name` | string | Somente PJ | Nome fantasia do investidor. | 1023 | | `cnae_code` | string | Somente PJ | Código CNAE do investidor. | 7 | | `company_type` | string | Somente PJ | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** | | `foundation_date` | string | Somente PJ | Data de fundação do investidor. | - | | `document_identification_number` | string | Somente PF | Número do documento de identidade do investidor. | 255 | | `marital_status` | string | Somente PF | Estado civil do investidor. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `birthdate` | string | Somente PF | Data de nascimento do investidor. | - | | `nationality` | string | Somente PF | Nacionalidade do investidor. | **[Enumeradores nationality](#enumeradores-nationality)** | | `occupation` | string | Somente PF | Ocupação/profissão do investidor. | 255 | | `is_pep` | boolean | Somente PF | Indica se o investidor é PEP. | - | | `investor_category` | string | Somente PF | Categoria autodeclarada do investidor. | **[Enumeradores investor_category](#enumeradores-investor_category)** | | `investment_suitability`| string | Somente PF | Perfil de suitability autodeclarado. | **[Enumeradores investment_suitability](#enumeradores-investment_suitability)** | | `address` | object | Ambos | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `investor_contact_information_list` | array | Somente PF | Lista de informações de contato do investidor. Apenas com `data_access_type == full_access`. | - | | `signer_group_list` | array | Somente PF | Lista de grupos de assinantes do investidor. Apenas com `data_access_type == full_access`. | - | | `registration_datetime` | string | Ambos | Data e hora de registro do investidor. | - | | `expiration_date` | string | Ambos | Data de expiração do investidor. | - | ### Enumeradores person_type | Enum | Description | | ----------- | ---------------- | | `legal` | Pessoa Jurídica | | `natural` | Pessoa Física | --- # Cadastro de Conta Bancária do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor Este endpoint permite o cadastro de conta bancária associada a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- | | `account_number` * | string | Número da conta bancária. Deve conter apenas dígitos. | 20 | | `account_digit` * | string | Dígito verificador da conta. Deve conter um único dígito. | 1 | | `account_branch` * | string | Número da agência bancária. Deve conter apenas dígitos. | 6 | | `financial_institution_code_number`* | string | Código da instituição financeira (3 dígitos). | 3 | | `financial_institution_ispb` * | string | Código ISPB da instituição financeira (8 dígitos). | 8 | | `account_type` * | string | Tipo da conta bancária. | **[Enumeradores account_type](#enumeradores-account_type)** | ### Enumeradores account_type | Enum | Description | | ------------ | ------------------ | | `checking` | Conta corrente | | `savings` | Conta Poupança | | `salary` | Conta Salário | | `payment` | Conta de Pagamento | ## Response STATUS 201 Response Body ```json { "bank_account_key": "123e4567-e89b-12d3-a456-426614174000", "account_number": "12345678", "account_digit": "1", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "00000000", "account_type": "checking" } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `bank_account_key` | string | Identificador único da conta bancária cadastrada (UUID v4). | 36 | | `account_number` | string | Número da conta bancária. | 20 | | `account_digit` | string | Dígito verificador da conta bancária. | 1 | | `account_branch` | string | Número da agência bancária. | 6 | | `financial_institution_code_number` | string | Código da instituição financeira. | 3 | | `financial_institution_ispb` | string | Código ISPB da instituição financeira. | 8 | | `account_type` | string | Tipo da conta bancária. | **[Enumeradores account_type](#enumeradores-account_type)** | --- # Remoção de Conta Bancária do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao Este endpoint permite a remoção de conta bancária associada a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account/ BANK-ACCOUNT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------|--------|------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `BANK-ACCOUNT-KEY` | string | Chave única da conta bancária a ser removida (UUID v4).| 36 | --- ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- --- # Envio de Documentos do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor Este endpoint permite o envio de documentos associados a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |---------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "proof_of_address" } ``` ### Request Body Params | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------|----------|------------------------------------------------------------------------------------------|---------------------------------------------------------------| | `document_base64` *| string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. Os valores aceitos variam de acordo com o `person_type` do investidor. | **[Enumeradores document_type](#enumeradores-document_type)** | ### Enumeradores document_type Os valores aceitos dependem do `person_type` do investidor. **Pessoa Jurídica** | Enum | Description | |--------|-----------------------------| | `danfe` | DANFE | | `proof_of_address` | Comprovante de Endereço | | `letter_of_attorney` | Procuração | | `company_statute` | Contrato ou Estatuto Social | **Pessoa Física** | Enum | Description | |--------|-----------------------------| | `cnh` | CNH | | `cnh_front` | Frente da CNH | | `cnh_back` | Verso da CNH | | `cnh_digital` | PDF CNH Digital | | `rg_front` | Frente do RG | | `rg_back` | Verso do RG | | `passport` | Passaporte | ## Response STATUS 201 Response Body ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "proof_of_address", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ``` ### Response Body Params | Field | Type | Description | Max Length | |-----------------|----------|--------------------------------------------------------------------|------------| | `document_key` | string | Identificador único do documento enviado (UUID v4). | 36 | | `document_type` | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- # Remoção de Documentos do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao Este endpoint permite a remoção de documentos enviados para o cadastro do investidor. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Envio de Documentos do Representante do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor Este endpoint permite o envio de documentos associados a um representante de um investidor previamente cadastrado. :::danger Atenção Não é possível adicionar documentos de representante para um investidor Pessoa Física (PF). ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | Chave única do representante do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "document_type": "cnh" } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------| | `document_base64` *| string | Conteúdo do arquivo do documento codificado em Base64. | - | | `document_type` * | string | Tipo do documento enviado. Valores aceitos: | **[Enumeradores document_type](#enumeradores-document_type)** | ### Enumeradores document_type | Enum | Description | |--------|-------------------------| | `cnh` | CNH | | `cnh_front` | Frente da CNH | | `cnh_back` | Verso da CNH | | `cnh_digital` | PDF CNH DIGITAL | `rg_front` | Frente do RG | | `rg_back` | Verso do RG | | `danfe` | DANFE | | `proof_of_address` | Comprovante de Endereço | | `letter_of_attorney` | Procuração | ## Response STATUS 201 Response Body ```json { "document_key": "123e4567-e89b-12d3-a456-426614174000", "document_type": "cnh", "ocr_key": "123e4567-e89b-12d3-a456-426614174000" } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |------------------|----------|-----------------------------------------------------|-----------------------| | `document_key` | string | Identificador único do documento enviado (UUID v4). | 36 | | `document_type` | string | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** | | `ocr_key` | string | Chave OCR associada ao documento enviado. | 36 | --- # Remoção de Documentos do Representante do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao Este endpoint permite a remoção de documentos associados a um representante de um investidor previamente cadastrado. :::danger Atenção Não é possível remover documentos de representante de um investidor Pessoa Física (PF). ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | Chave única do representante do investidor (UUID v4). | 36 | | `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro de Informações de Contato do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor Este endpoint permite o cadastro de informações de contato associadas a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- | | `name` * | string | Nome completo do contato. | 255 | | `document_number` * | string | Número do documento do contato (formato CPF, "XX.XXX.XXX/XXXX-XX"). | 11 | | `email`* | string | Endereço de email do contato. | 1023 | | `phone_number`* | string | Número de telefone do contato (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20 | ## Response STATUS 201 Response Body ```json { "investor_contact_information_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "email": "joao.silva@email.com", "phone_number": "+5511999999999" } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ------------------------------------ | ------ | --------------------------------------------------------------------- | --------------------- | | `investor_contact_information_key` | string | Identificador único da informação de contato cadastrada (UUID v4). | 36 | | `name` | string | Nome completo do contato. | 255 | | `document_number` | string | Número do documento do contato (CPF). | 11 | | `email` | string | Endereço de email do contato. | 1023 | | `phone_number` | string | Número de telefone do contato. | 20 | --- # Remoção de Informações de Contato do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao Este endpoint a remoção de informações de contato associadas a um investidor previamente cadastrado. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information/ INVESTOR-CONTACT-INFORMATION-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |----------------------------------|--------|-----------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `INVESTOR-CONTACT-INFORMATION-KEY` | string | Chave única da informação de contato a ser removida (UUID v4).| 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Cadastro de Representantes do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor Este endpoint permite o cadastro de representantes associados a um investidor previamente cadastrado. :::danger Atenção Não é possível adicionar representante para um investidor Pessoa Física (PF). ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------- | ------ | ------------------------------------- | ---------- | | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "name": "João da Silva", "document_number": "123.456.789-01", "birthdate": "1990-01-01", "nationality": "Brasileiro", "mother_name": "Maria da Silva", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" } } ``` ### Request Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ----------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- | | `name` * | string | Nome completo do representante do investidor. | 255 | | `document_number` * | string | Número do documento (CPF, formato "XX.XXX.XXX/XXXX-XX"). | 11 | | `birthdate`* | string | Data de nascimento do representante no formato ISO 8601 (YYYY-MM-DD). | - | | `document_identification_number`* | string | Número do documento de identificação. | 255 | | `marital_status`* | string | Estado civil do representante. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system`* | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `nationality`* | string | Nacionalidade do representante do investidor. | 255 | | `mother_name` | string | Nome completo da mãe do representante. | 1023 | | `father_name` | string | Nome completo do pai do representante. | 1023 | | `occupation`* | string | Ocupação ou profissão do representante. | 255 | | `is_pep`* | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | | ----------------- | ------ | ---------------------------------------- | ---------------- | | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (somente números). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores marital_status | Enum | Description | | ---------------- | ------------------ | | `single` | Solteiro(a) | | `married` | Casado(a) | | `widower` | Viúvo(a) | | `separated` | Separado(a) | | `stable_union` | em União Estável | | `divorced` | Divorciado(a) | ### Enumeradores property_system | Enum | Description | | --------------------------------------- | --------------------------------- | | `total_communion_of_goods` | Comunhão Total de Bens | | `partial_communion_of_goods` | Comunhão Parcial de Bens | | `total_separation_of_goods` | Separação Total de Bens | | `final_participation_of_acquisitions` | Participação Final nos Aquestos | | `compulsory_separation_of_goods` | Separação Compulsória de Bens | ## Response STATUS 201 Response Body ```json { "investor_representative_key": "123e4567-e89b-12d3-a456-426614174000", "name": "João da Silva", "document_number": "123.456.789-01", "document_identification_number": "987654321", "marital_status": "single", "property_system": "partial_communion_of_goods", "birthdate": "1990-01-01", "nationality": "Brasileiro", "mother_name": "Maria da Silva", "father_name": "José da Silva", "occupation": "Advogado", "is_pep": false, "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "investor_representative_document_list": [] } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | | ----------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | `investor_representative_key` | string | Identificador único do representante do investidor (UUID v4). | 36 | | `name` | string | Nome completo do representante do investidor. | 255 | | `document_number` | string | Número do documento do representante (formato CPF). | 11 | | `document_identification_number` | string | Número do documento de identificação. | 255 | | `marital_status` | string | Estado civil do representante. | **[Enumeradores marital_status](#enumeradores-marital_status)** | | `property_system` | string | Regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** | | `birthdate` | string | Data de nascimento do representante. | - | | `nationality` | string | Nacionalidade do representante do investidor. | 255 | | `mother_name` | string | Nome completo da mãe do representante. | 1023 | | `father_name` | string | Nome completo do pai do representante. | 1023 | | `occupation` | string | Ocupação ou profissão do representante. | 255 | | `is_pep` | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)** | | `investor_representative_document_list` | array | Lista de documentos associados ao representante. | - | --- # Remoção de Representante do Investidor URL: /documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao Este endpoint permite a remoção de representantes enviados para o cadastro do investidor. :::danger Atenção Não é possível remover representante de um investidor Pessoa Física (PF). ::: --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|--------------------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | | `INVESTOR-REPRESENTATIVE-KEY` | string | Chave única do representante a ser removido (UUID v4). | 36 | ## Response STATUS 204 Nenhum conteúdo é retornado no corpo da resposta. --- # Consulta de Investidor URL: /documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave Este endpoint permite consultar os detalhes completos de um investidor cadastrado no sistema, utilizando sua chave única. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ## Response STATUS 200 Response Body ```json { "investor_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e", "name": "Fabrica Exemplo S.A.", "document_number": "96.146.194/0001-07", "status": "in_filling", "backoffice_analysis_status": "in_analysis", "person_type": "legal", "trading_name": "Fabrica Comércio", "cnae_code": "62.02-3-00", "company_type": "sa", "foundation_date": "2000-01-01", "address": { "street": "Rua das Empresas", "neighborhood": "Centro", "number": "123", "postal_code": "01001-000", "city": "São Paulo", "state": "SP", "complement": "Sala 101" }, "registration_datetime": "2025-01-23T13:47:57.354528", "expiration_date": "2026-01-23", "signer_group_list": [], "bank_account_list": [], "investor_representative_list": [], "investor_contact_information_list": [], "investor_document_list": [], "investor_analysis_list": [] } ``` ### Response Body Params | Campo | Tipo | Descrição | Máximo de Caracteres | |--------|----------|--------------------------------------------------------|-----------------------| | `investor_key` | string | Identificador único do investidor. | 36 | | `name` | string | Nome completo do investidor. | 255 | | `document_number` | string | Número do documento do investidor (CNPJ). | 14 | | `status` | string | Status do investidor | **[Enumeradores status](#enumeradores-status)** | | `backoffice_analysis_status`| string | Status de análise do backoffice. | - | | `person_type` | string | Tipo de pessoa (`legal` ou `natural`). | - | | `trading_name` | string | Nome fantasia do investidor. | 1023 | | `cnae_code` | string | Código CNAE do investidor. | 7 | | `company_type` | string | Tipo de empresa Aceitos: ´sa´, ´ltda´, ´cop´ | 50 | | `foundation_date` | string | Data de fundação do investidor. | - | | `signer_group_list` | array | Lista de grupos de assinantes associados ao investidor. | - | | `bank_account_list` | array | Lista de contas bancárias associadas ao investidor. | - | | `investor_representative_list` | array | Lista de representantes do investidor. | - | | `investor_contact_information_list` | array | Lista de informações de contato associadas ao investidor. | - | | `investor_document_list` | array | Lista de documentos cadastrados para o investidor. | - | | `address` * | string | Objeto referenciando o endereço | **[Objeto address](#objeto-address)**| ### Objeto Address | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------|----------|-----------------------------------------------------|-----------------| | `street` * | string | Nome da rua do endereço da empresa. | 500 | | `neighborhood` | string | Nome do bairro do endereço da empresa. | 100 | | `number` * | string | Número do endereço. | 10 | | `postal_code` * | string | CEP do endereço (somente números). | 8 | | `city` * | string | Nome da cidade do endereço. | 255 | | `state` * | string | Sigla do estado (2 caracteres). | 2 | | `complement` | string | Complemento do endereço, se aplicável. | 100 | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | --- # Consulta de Investidores por filtros URL: /documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro Este endpoint permite consultar investidores cadastrados no sistema utilizando o número de documento (CNPJ) ou Nome. --- ## Request ENDPOINT /investor_management/investor MÉTODO GET ### Query Params | Campo | Tipo | Descrição | Obrigatório | |-------------------|----------|------------------------------------|-------------| | `document_number` | string | Número do documento do investidor. | Não | | `name` | string | Nome do investidor. | Não | | `page` | integer | Página atual da consulta. | Não | | `rows_per_page` | integer | Número de registros por página. | Não | ## Response STATUS 200 Response Body ```json { "data": [ { "investor_key": "495ae701-5c38-49b1-b517-a3b910fe8d8f", "name": "Empresa Exemplo S.A.", "document_number": "12.345.678/0001-95", "status": "in_filling" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 1 } } ``` ### Response Body Params | Campo | Tipo | Descrição | | |--------------|--------|---------------------|-----------------------------------------------------------------| | `data` | list | Lista de resultados | **[Objeto Investidor Simplificado](#objeto-investidor-simplificado)** | | `pagination` | object | Dados de paginação | **[Objeto Paginação](#objeto-paginacao)** | ### Objeto Investidor Simplificado | Campo | Tipo | Descrição | Máximo de Caracteres | |-------------------|----------|-------------------------------------------------------------|-------------------------------------------------| | `investor_key` | string | Identificador único do investidor (UUID v4). | 36 | | `name` | string | Nome completo do investidor. | 255 | | `document_number` | string | Número do documento do investidor (CNPJ). | 14 | | `status` | string | Status atual do investidor. | **[Enumeradores status](#enumeradores-status)** | ### Enumeradores status | Enum | Description | |--------|-----------------| | `in_filling` | Em preenchimento | | `in_analysis` | Em análise | | `canceled` | Cancelado | | `approved` | Aprovado | | `reproved` | Reprovado | | `expired` | Expirado | ### Objeto Pagination | Campo | Tipo | Descrição | |-------------------|----------|------------------------------------------| | `current_page` | integer | Página atual da consulta. | | `next_page` | integer | Próxima página, caso exista. | | `rows_per_page` | integer | Número de registros por página. | | `total_pages` | integer | Número total de páginas. | | `total_rows` | integer | Número total de registros encontrados. | --- # Envio para Análise do Investidor URL: /documentation/escrituracao/homologacao-investidor/envio-analise/ Este endpoint permite alterar o status de um investidor para análise, enviando-o para o processo de validação. --- ## Request ENDPOINT /investor_management/investor/ INVESTOR-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | ### Request Body Request Body ```json { "investor_status": "in_analysis" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |------------------|----------|-------------------------------------------------|-------------| | `investor_status` | string | Novo status do investidor. Valor aceito: `in_analysis`. | Sim | ## Response A resposta é um json completo atualizado do investidor. --- # Introdução URL: /documentation/escrituracao/homologacao-investidor/inicio A parte de cadastro de Investidores é essencial para o início da emissão de Notas Comerciais. Nessa seção iremos explicar todo o fluxo, desde o envio das primeiras informações, até o envio para análise. Para ter acesso aos serviços discutidos nas próximas sessões, entre em contato com o time [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox) quanto em ambiente de produção. ### Cadastro do Investidor Nessa etapa, deve-se enviar todas as informações tanto do Investidor quanto dos seus representantes, documentos, informações de contato, grupos de assinantes e contas bancárias. Uma vez que o envio das informações estiver concluído, o cadastro é enviado para análise e após aprovação este investidor estará apto a participar da emissão de Notas. ### Atualização de Investidor Em caso de necessidade de atualização cadastral, deve-se enviar novamente todas as informações do Investidor com as modificações desejadas. Após envio, é gerada uma nova Análise para validação. Assim que esta nova Análise for aprovada, os novos dados cadastrais do Investidor são efetivamente alterados. --- # **Solicitação de Acesso aos Dados do Investidor** URL: /documentation/escrituracao/homologacao-investidor/solicitacao-acesso Clientes que cadastraram um investidor que já possui um **cadastro único** precisam **solicitar acesso aos dados do investidor** para que possam emitir operações com esse investidor como parte. Ao realizar essa solicitação, o **investidor receberá um e-mail com instruções para aprovar ou recusar o acesso**. --- ## **Solicitação de Acesso (POST)** ### **Request** ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request MÉTODO POST ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |---------------|--------|-----------------------------------------------|-----------------| | `INVESTOR-KEY` * | string | Chave única do investidor (UUID v4). | 36 | --- ## **Request Body** Nenhum corpo de requisição é necessário. --- ## **Response** STATUS 201 Response Body ```json { "data_access_request_key": "6beb9e44-1513-4d3b-9af5-f3c39ebbf2d0", "requested_at": "2025-02-22T10:45:49.609517", "responded_at": null, "data_access_request_status": "in_analysis" } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------------------|----------|-------------------------------------------------------------|-----------------| | `data_access_request_key` * | string | Chave única da solicitação de acesso (UUID v4). | 36 | | `requested_at` * | string | Data e hora da solicitação (formato ISO 8601). | - | | `responded_at` | string | Data e hora da resposta à solicitação, se já respondida. | - | | `data_access_request_status` * | string | Status da solicitação. | **[Enumeradores data_access_request_status](#enumeradores-data_access_request_status)** | --- ## **Consulta do Status da Solicitação (GET)** Os clientes podem verificar se sua solicitação foi aprovada, recusada ou ainda está em análise. ## **Request** ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |---------------|--------|-----------------------------------------------|-----------------| | `INVESTOR-KEY` * | string | Chave única do investidor (UUID v4). | 36 | ## **Response** STATUS 200 Response Body ```json [ { "data_access_request_key": "6beb9e44-1513-4d3b-9af5-f3c39ebbf2d0", "requested_at": "2025-02-22T10:45:49.609517", "responded_at": null, "data_access_request_status": "in_analysis" } ] ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |--------------------------------|----------|-------------------------------------------------------------|-----------------| | `data_access_request_key` * | string | Chave única da solicitação de acesso (UUID v4). | 36 | | `requested_at` * | string | Data e hora da solicitação (formato ISO 8601). | - | | `responded_at` | string | Data e hora da resposta à solicitação, se já respondida. | - | | `data_access_request_status` * | string | Status da solicitação. | **[Enumeradores data_access_request_status](#enumeradores-data_access_request_status)** | --- ## **Enumeradores data_access_request_status** | Enum | Descrição | |-------------|------------------------------------------------------| | `in_analysis` | A solicitação está em análise pelo investidor. | | `approved` | O acesso foi aprovado e o cliente pode visualizar os dados do investidor. | | `reproved` | A solicitação foi recusada e o cliente não poderá acessar os dados do investidor. | --- # Consulta de Comprovante de Transação URL: /documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao Este endpoint permite obter o comprovante (PDF + metadados) de uma das TEDs executadas pela QI Tech para uma integralização. Em um ciclo de integralização (pagamento do investidor → tarifas → desembolso) podem ser geradas múltiplas TEDs — você escolhe qual delas quer pelo parâmetro `transaction_type`. Quando houver mais de uma TED do mesmo tipo para a mesma integralização (por exemplo, vários `extraordinary_event_payment`), o endpoint retorna apenas a mais recente. Para listar todas, utilize **[Consulta de Transações da Integralização](./consulta-transacoes-integralizacao.md)**. --- ## Consulta de Comprovante (GET) ### Request ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transaction_receipt MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------|--------|--------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | ### Query Params | Campo | Tipo | Descrição | Obrigatório | |--------------------|--------|------------------------------------------------------------------------------------------|-------------| | `transaction_type` | string | Tipo da TED a ser consultada. **[Enumeradores transaction_type](#enumeradores-transaction_type)** | Sim | --- ### Response STATUS 200 Response Body ```json { "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec", "transaction_amount": 12345.67, "transaction_status": "settled", "pdf_encoded_string": "JVBERi0xLi4u..." } ``` --- ### Response Body Params | Campo | Tipo | Descrição | |----------------------|--------|----------------------------------------------------------------------------------------------------| | `transaction_key` | string | Chave única da TED no BaaS — mesmo valor retornado por `consulta-transacoes-integralizacao`. | | `transaction_amount` | number | Valor da TED conforme registrado pela QI Tech. | | `transaction_status` | string | Status da TED no BaaS (ex.: `settled`, `paid`). | | `pdf_encoded_string` | string | Comprovante bancário em base64. Decodifique para obter o PDF. | --- ### Enumeradores transaction_type | Enum | Descrição | |-------------------------------|----------------------------------------------------------------------------------------| | `disbursement` | TED de desembolso do valor líquido para a conta bancária do emissor. | | `bookkeeping_fee_internal` | TED para a QI CTVM referente à tarifa de escrituração interna. | | `bookkeeping_fee_external` | TED para a conta de escrituração externa do cliente. | | `structuring_fee` | TED para a conta de estruturação do cliente. | | `extraordinary_event_payment` | TED para um investidor referente a um evento extraordinário de liquidação. | --- ### Erros | HTTP | Código | Quando ocorre | |------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | 400 | `HTTPMissingParam` | Parâmetro `transaction_type` não foi informado. | | 400 | `HTTPInvalidParam` | `transaction_type` não corresponde a nenhum dos valores permitidos. | | 404 | `ACL000004` (`IntegralizationTransactionNotFound`) | Não existe TED do tipo informado para essa integralização, OU a integralização nunca foi liquidada (sem TEDs). | :::note O 404 com `ACL000004` é retornado de forma idêntica em todos os cenários (chave inexistente, integralização nunca liquidada, ou tipo de TED ausente) — por design, não diferenciamos os casos. Se precisar saber se a integralização existe, liste suas transações primeiro. ::: --- # Consulta de Conta de Liquidação URL: /documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao Este endpoint permite consultar os detalhes da conta de liquidação de um emissor — dados bancários (agência, conta, dígito), status e, quando a conta já está aberta, informações do titular e saldos. Enquanto a conta ainda não foi aberta no BaaS, o endpoint retorna apenas os dados básicos com `account_status: "pending"`. Após a abertura, a resposta inclui os campos adicionais do titular e de saldo. --- ## Consulta de Conta de Liquidação (GET) ### Request ENDPOINT /account_liquidation/issuer/ ISSUER-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|--------------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | --- ### Response STATUS 200 Response Body — conta aberta ```json { "issuer_key": "23d933e9-88ba-4291-a6a4-33f025ab361f", "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154", "bank_account_key": "8f2a6f10-3c43-4a3b-9f5e-2a9a1d4be0c1", "request_account_key": "1c0a2e54-77a8-4f0e-8d8e-6f2b9b3c1d22", "account_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec", "account_branch": "0001", "account_number": "1234567", "account_digit": "8", "account_status": "opened", "account_type": "payment_account", "account_documents": [], "balance": 12345.67, "blocked_balance": 0.0, "owner_document_number": "12345678000190", "owner_name": "Emissor Exemplo LTDA", "owner_person_key": "9b1f3c77-5a2d-4e8f-b6a0-3d2c1e0f9a88", "created_at": "2026-01-15T12:34:56" } ``` Response Body — conta pendente ```json { "issuer_key": "23d933e9-88ba-4291-a6a4-33f025ab361f", "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154", "bank_account_key": "8f2a6f10-3c43-4a3b-9f5e-2a9a1d4be0c1", "request_account_key": "1c0a2e54-77a8-4f0e-8d8e-6f2b9b3c1d22", "account_branch": "0001", "account_number": "1234567", "account_digit": "8", "account_status": "pending" } ``` --- ### Response Body Params | Campo | Tipo | Descrição | |-------------------------|--------|---------------------------------------------------------------------------------------------| | `issuer_key` | string | Chave única do emissor. | | `tenant_key` | string | Chave única do cliente dono da conta. | | `bank_account_key` | string | Chave única da conta bancária no BaaS. | | `request_account_key` | string | Chave única da solicitação de abertura da conta. | | `account_key` | string | Chave única da conta no BaaS. Presente apenas quando a conta já foi aberta. | | `account_branch` | string | Agência da conta. | | `account_number` | string | Número da conta. | | `account_digit` | string | Dígito da conta. | | `account_status` | string | Status da conta. `pending` enquanto a abertura não foi concluída. | | `account_type` | string | Tipo da conta no BaaS. Presente apenas quando a conta já foi aberta. | | `account_documents` | array | Documentos associados à conta. Presente apenas quando a conta já foi aberta. | | `balance` | number | Saldo disponível da conta. Presente apenas quando a conta já foi aberta. | | `blocked_balance` | number | Saldo bloqueado da conta. Presente apenas quando a conta já foi aberta. | | `owner_document_number` | string | CPF/CNPJ do titular da conta. Presente apenas quando a conta já foi aberta. | | `owner_name` | string | Nome do titular da conta. Presente apenas quando a conta já foi aberta. | | `owner_person_key` | string | Chave única do titular no BaaS. Presente apenas quando a conta já foi aberta. | | `created_at` | string | Data de criação da conta. Presente apenas quando a conta já foi aberta. | --- ### Erros | HTTP | Código | Quando ocorre | |------|---------------------------------------------------------|-------------------------------------------------------------------------------| | 404 | `ACL000002` (`IssuerAccountLiquidationNotFound`) | Não existe conta de liquidação para o emissor informado. | | 400 | `ACL000003` (`IssuerAccountLiquidationNotBelongToTenant`) | A conta de liquidação do emissor não pertence ao cliente que fez a requisição. | --- # Consulta de Integralização por Chave URL: /documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao Este endpoint permite consultar os detalhes de um processo de integralização utilizando sua chave única. --- ## Consulta de Processo de Integralização (GET) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------------|--------|------------------------------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "tenant_key": "39a0d458-c06f-41e7-92cf-a335cea90675", "integralization_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753", "operation_key": "c9cc8980-25b2-49ec-ac40-2a12b8df9dfc", "operation_type": "commercial_paper", "contract_number": "0000000002", "issue_number": 1, "issue_series": 1, "issuer_key": "1bc06a53-9503-4520-916c-38b5a6bb5912", "issuer_name": "Advanced Solutions", "issuer_document_number": "05120047000102", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "subscripted_quantity": 1000000, "subscripted_total_amount": 1000000.0, "integralized_quantity": 1000000, "issue_quantity": 1000000, "integralization_status": "finished", "subscription_list": [ { "subscription_key": "5a2100db-6bad-4fc7-9b5f-390543c63c55", "investor_key": "2d14cfef-7b95-4aa4-be0c-860ec8a60934", "investor_name": "Dynamic Group", "investor_document_number": "99525109000100", "investor_bank_account": { "account_digit": "0", "account_branch": "1234", "account_number": "12345678", "financial_institution_ispb": "12345678", "financial_institution_code_number": "001" }, "subscription_date": "2025-01-27", "financial_base_date": "2025-01-27", "subscripted_quantity": 1000000, "unit_price": 1.0, "expected_amount": 1000000.0, "paid_amount": 1000000.0, "subscription_note_template_key": "8bfba2a3-1cda-45c4-9a97-05b2bf31e486", "subscription_note_document_key": "c9cc8980-25b2-49ec-ac40-2a12b8df9dfc/5a2100db-6bad-4fc7-9b5f-390543c63c55/subscription_note/8b6867d8-95c8-4e0d-b670-6a7d06f3acf7", "subscription_note_signature_status": "pending_creation", "subscription_payment_list": [ { "subscription_payment_key": "edf8a4cc-24c9-4dd9-8cae-9cb9151b40bf", "payment_receipt_document_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753/5a2100db-6bad-4fc7-9b5f-390543c63c55/subscription_payment/edf8a4cc-24c9-4dd9-8cae-9cb9151b40bf", "description": "Comprovante itau", "amount": 1000000.0, "subscription_payment_status": "confirmed", "updated_at": "2025-01-27T14:30:18.741983" } ] } ] } ``` --- ### Response Body Params | Campo | Tipo | Descrição | |------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------| | `tenant_key` | string | Chave única do tenant associado à integralização. | | `integralization_key` | string | Chave única da integralização. | | `operation_key` | string | Chave única da operação associada. | | `operation_type` | string | Tipo da operação. Valores possíveis: `commercial_paper`. | | `contract_number` | string | Número do contrato associado à integralização. | | `issue_number` | integer | Número da emissão associada à integralização. | | `issue_series` | integer | Série da emissão associada à integralização. | | `issuer_key` | string | Chave única do emissor associado. | | `issuer_name` | string | Nome do emissor associado à integralização. | | `issuer_document_number` | string | Número do documento do emissor | | `issuer_bank_account` | object | Dados da conta bancária do emissor. | | `issuer_bank_account.account_type` | string | Tipo da conta bancária (`checking`, etc.). | | `issuer_bank_account.account_digit` | string | Dígito verificador da conta bancária. | | `issuer_bank_account.account_branch` | string | Agência bancária. | | `issuer_bank_account.account_number` | string | Número da conta bancária. | | `issuer_bank_account.financial_institution_ispb` | string | ISPB da instituição financeira. | | `issuer_bank_account.financial_institution_code_number` | string | Código da instituição financeira. | | `subscripted_quantity` | integer | Quantidade total de cotas subscritas. | | `subscripted_total_amount` | number | Valor total das cotas subscritas. | | `integralized_quantity` | integer | Quantidade total de cotas integralizadas. | | `issue_quantity` | integer | Quantidade total de cotas emitidas na operação. | | `integralization_status` | string | **[Enumeradores integralization_status](#enumeradores-integralization_status)** | | `subscription_list` | array | Lista de subscrições associadas à integralização. **[Objeto subscription](#objeto-subscription)** | ### Objeto subscription | Campo | Tipo | Descrição | |------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------------------------------------| | `subscription_key` | string | Chave única da subscrição. | | `investor_key` | string | Chave única do investidor associado à subscrição. | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Número do documento do investidor (CPF ou CNPJ). | | `investor_bank_account` | object | Dados bancários do investidor. | | `subscription_date` | string | Data da subscrição (formato: YYYY-MM-DD). | | `financial_base_date` | string | Data base financeira da subscrição (formato: YYYY-MM-DD). | | `subscripted_quantity` | integer | Quantidade de cotas subscritas. | | `unit_price` | number | Preço unitário das cotas. | | `expected_amount` | number | Valor total esperado da subscrição. | | `paid_amount` | number | Valor pago ja confrimado da subscrição. | | `subscription_note_template_key` | string | Chave do template da nota de subscrição. | | `subscription_note_document_key` | string | Chave do documento da nota de subscrição. | | `subscription_note_signature_status` | string | Status da assinatura da nota de subscrição. | | `subscription_payment_list` | array | Lista de pagamentos associados à subscrição. **[Objeto subscription_payment](#objeto-subscription_payment)]** | ### Objeto subscription_payment | Campo | Tipo | Descrição | |------------------------------------------------------------------------|------------|----------------------------------------------------------------------------------------| | `subscription_payment_key` | string | Chave única do pagamento da subscrição. | | `payment_receipt_document_key` | string | Chave do documento do comprovante de pagamento. | | `description` | string | Descrição do comprovante de pagamento. | | `amount` | number | Valor do pagamento registrado. | | `subscription_payment_status` | string | Status do pagamento. Valores possíveis: `waiting_confirmation`, `confirmed`, `denied`. | | `updated_at` | string | Data e hora da última atualização do pagamento (formato: ISO 8601). | ### Enumeradores integralization_status | Enum | Description | | ------------------------------- | ---------------------------------- | | `pending` | Pendente Subscrição. | | `finished` | Integralização finalizada. | | `canceled` | Integralização cancelada. | --- # Consulta de Transações da Integralização URL: /documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao Este endpoint retorna os metadados de todas as TEDs executadas pela QI Tech para uma integralização — sem o PDF. Útil para descobrir quantos comprovantes existem, em qual ordem foram executados e os respectivos `transaction_key`. Para obter o PDF de uma TED específica, use **[Consulta de Comprovante de Transação](./consulta-comprovante-transacao.md)**. A resposta vem em ordem cronológica (`created_at` ASC) e inclui todas as TEDs do ciclo (desembolso, tarifas e eventos extraordinários). Quando há múltiplas TEDs do mesmo tipo (por exemplo, vários `extraordinary_event_payment`), todas aparecem aqui — diferente do endpoint de comprovante, que retorna apenas a mais recente. --- ## Consulta de Transações (GET) ### Request ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transactions MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------|--------|--------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json [ { "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec", "external_id": "072a7cc4-1fbf-419b-8a41-f57bd86ee753", "transaction_amount": 12345.67, "transaction_type": "disbursement", "transaction_status": "paid", "created_at": "2026-05-05T13:22:01" } ] ``` --- ### Response Body Params | Campo | Tipo | Descrição | |----------------------|--------|----------------------------------------------------------------------------------------------------------| | `transaction_key` | string | Chave única da TED no BaaS. | | `external_id` | string | `integralization_key` à qual a TED pertence. | | `transaction_amount` | number | Valor registrado pela QI Tech para a TED. Não use como fonte oficial para conciliação contábil. | | `transaction_type` | string | Tipo da TED. **[Enumeradores transaction_type](./consulta-comprovante-transacao.md#enumeradores-transaction_type)** | | `transaction_status` | string | Status atual da TED (ex.: `paid`, `settled`). | | `created_at` | string | Data e hora de criação do registro (ISO 8601). | --- # Introdução à Integralização de Cotas URL: /documentation/escrituracao/integralizacao-cotas/inicio Após a conclusão do processo de Emissão da Nota Comercial, a operação restará no status emitido (issued). Por padrão o processo de subscrição de cotas para integralização ocorre de forma automática após a assinatura do termo constitutivo. Ao consultar uma operação no estado emitida, estará disponível um campo chamado `integralization_key` pelo quando o processo de integralização poderá ser acompanhado. O processo de integralização consiste de - Subscrição de cotas - Assinatura do boletim de subscrição - Registro de Pagamento - Confirmação de Pagamento --- # Cadastro de Subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao Este endpoint permite registrar a intenção de um investidor em subscrever uma quantidade específica de cotas de uma integralização. --- ## Cadastro de Subscrição (POST) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ----------------------- | ------ | ------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | --- ### Request Body Request Body ```json { "investor_key": "123e4567-e89b-12d3-a456-426614174000", "investor_bank_account": { "account_number": "12345678", "account_digit": "0", "account_branch": "1234", "financial_institution_code_number": "001", "financial_institution_ispb": "12345678" }, "subscription_date": "2025-01-01", "financial_base_date": "2025-01-01", "subscription_note_template_key": "c649c01a-dd24-47b7-b93e-5a6bac50bcf0", "subscripted_quantity": 100000 } ``` ### Request Body Params | Campo | Tipo | Descrição | | ------------------------------------------------------------ | ------- | ------------------------------------------------------- | | `investor_key`* | string | Chave única do investidor (UUID v4). | | `investor_bank_account`* | object | Dados da conta bancária do investidor. | | `investor_bank_account.account_number`* | string | Número da conta bancária do investidor. | | `investor_bank_account.account_digit`* | string | Dígito verificador da conta bancária do investidor. | | `investor_bank_account.account_branch`* | string | Agência bancária do investidor. | | `investor_bank_account.financial_institution_code_number`* | string | Código da instituição financeira do investidor. | | `investor_bank_account.financial_institution_ispb`* | string | ISPB da instituição financeira do investidor. | | `subscripted_quantity`* | integer | Quantidade de cotas que o investidor deseja subscrever. | | `financial_base_date`* | string | Data base financeira. | | `subscription_date`* | string | Data da subscrição. | | `subscription_note_template_key`* | string | Template do boletim de subscrição. | --- ### Response STATUS 201 Response Body ```json { "subscription_key": "2f7e00b5-988f-4214-bb46-4728d9081148", "investor_key": "a76e408a-c733-4a68-963a-dc93ff0bc3e3", "investor_name": "Global Enterprises", "investor_document_number": "89206257000108", "investor_bank_account": { "account_digit": "0", "account_branch": "1234", "account_number": "12345678", "financial_institution_ispb": "12345678", "financial_institution_code_number": "001" }, "subscription_date": "2025-01-27", "financial_base_date": "2025-01-27", "subscripted_quantity": 1000000, "unit_price": 1.0, "expected_amount": 1000000.0, "paid_amount": 1000000.0, "subscription_note_template_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80", "subscription_note_document_key": "5ea88fca-4ca3-4dfe-aea4-35e431aef3c5/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_note/f206d799-cb94-48d5-81c5-5988ecef8079", "envelope_signature_status": "pending_creation", "envelope_signature_url": "https://certifiqi.com.br/envelope_key", "envelope_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80", "subscription_payment_list": [ { "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "description": "Comprovante itau", "amount": 1000000.0, "subscription_payment_status": "confirmed", "updated_at": "2025-01-27T14:33:54.214891" } ] } ``` ### **Response Body Params** | Campo | Tipo | Descrição | | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | `subscription_key` | string | Chave única da subscrição (UUID v4). | | `investor_key` | string | Chave única do investidor associado à subscrição (UUID v4). | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Número do documento do investidor (CPF ou CNPJ). | | `investor_bank_account` | object | **[Objeto investor_bank_account](#objeto-investor_bank_account)**. | | `subscription_date` | string | Data da subscrição (formato: YYYY-MM-DD). | | `financial_base_date` | string | Data base financeira da subscrição (formato: YYYY-MM-DD). | | `subscripted_quantity` | integer | Quantidade de cotas subscritas. | | `unit_price` | number | Preço unitário das cotas subscritas. | | `expected_amount` | number | Valor total esperado da subscrição. | | `paid_amount` | number | Valor total pago na subscrição. | | `subscription_note_template_key` | string | Chave única do template da nota de subscrição (UUID v4). | | `subscription_note_document_key` | string | Chave única do documento da nota de subscrição. | | `envelope_signature_status` | string | Status de assinatura da nota de subscrição. | | `envelope_signature_url` | string | URL de assinatura da nota de subscrição. | | `envelope_key` | string | Chave do envelope de assinatura. | | `subscription_payment_list` | array | Lista de pagamentos associados à subscrição.**[Objeto subscription_payment_list](#objeto-subscription_payment_list)**. | --- ### Objeto investor_bank_account | Campo | Tipo | Descrição | | ------------------------------------- | ------ | ----------------------------------------------------- | | `account_number` | string | Número da conta bancária do investidor. | | `account_digit` | string | Dígito verificador da conta bancária do investidor. | | `account_branch` | string | Agência bancária do investidor. | | `financial_institution_code_number` | string | Código da instituição financeira do investidor. | | `financial_institution_ispb` | string | ISPB da instituição financeira do investidor. | ### Objeto subscription_payment_list | Campo | Tipo | Descrição | | -------------------------------- | ------ | -------------------------------------------------------------------------------------------- | | `subscription_payment_key` | string | Chave única do pagamento da subscrição (UUID v4). | | `payment_receipt_document_key` | string | Chave do documento do comprovante de pagamento. | | `description` | string | Descrição do comprovante de pagamento. | | `amount` | number | Valor do pagamento registrado. | | `subscription_payment_status` | string | Status do pagamento. Valores possíveis:`waiting_confirmation`, `confirmed`, `denied`. | | `updated_at` | string | Data e hora da última atualização do pagamento (formato: ISO 8601). | --- # Cancelar subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao --- ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | |------------------|--------|------------------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única do processo de integralização (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Chave única da subscrição (UUID v4). | 36 | --- ### Request Body ```json { "subscription_status": "canceled" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | |-------------------|----------|-----------------------------------------|-------------| | `subscription_status` | string | Valores aceitos: `canceled`. | Sim | --- ### Response STATUS 200 Será retornado um exemplar atualizado da Subscrição. --- --- # Confirmação ou Rejeição do Pagamento de Subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento Este endpoint permite confirmar ou rejeitar o pagamento associado a uma subscrição de integralização. O status do pagamento é atualizado conforme o valor fornecido no corpo da requisição. --- ## Atualização do Status do Pagamento (PATCH) ### Request ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment/ SUBSCRIPTION-PAYMENT-KEY MÉTODO PATCH ### Path Params | Campo | Tipo | Descrição | Caracteres | | ---------------------------- | ------ | ---------------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Chave única da subscrição associada (UUID v4). | 36 | | `SUBSCRIPTION-PAYMENT-KEY` | string | Chave única do pagamento da subscrição (UUID v4). | 36 | --- ### Request Body ```json { "subscription_payment_status": "confirmed" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | | -------------------------------- | ------ | ------------------------------------------------------------------------- | ------------ | | `subscription_payment_status`* | string | Novo status do pagamento. Valores possíveis:`confirmed` ou `denied`. | Sim | --- ### Response STATUS 200 Response Body ```json { "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "description": "Comprovante de pagamento Itau R$100.000,00", "amount": 100000.0, "subscription_payment_status": "waiting_confirmation", "updated_at": "2025-01-24T11:30:00Z" } ``` --- ### Response Body Params | Campo | Tipo | Descrição | | ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | | `subscription_payment_key` | string | Chave única do pagamento da subscrição (UUID v4). | | `amount` | number | Valor declarado do pagamento registrado. | | `description` | number | Descrição do conteudo do recibo. | | `subscription_payment_status` | string | Status atualizado do pagamento. Valores possíveis:`waiting_confirmation` `confirmed`, `denied`. | | `updated_at` | string | Data e hora da atualização do status do pagamento (formato: ISO 8601). | --- # Consulta de Subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas Este endpoint permite consultar uma subcrição em andamento. --- ## Consulta de Subscrição (GET) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------|--------|------------------------------------------|------------| | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Chave única da subscrição (UUID v4). | 36 | --- ### Response STATUS 201 Response Body ```json { "subscription_key": "2f7e00b5-988f-4214-bb46-4728d9081148", "investor_key": "a76e408a-c733-4a68-963a-dc93ff0bc3e3", "investor_name": "Global Enterprises", "investor_document_number": "89206257000108", "investor_bank_account": { "account_digit": "0", "account_branch": "1234", "account_number": "12345678", "financial_institution_ispb": "12345678", "financial_institution_code_number": "001" }, "subscription_date": "2025-01-27", "financial_base_date": "2025-01-27", "subscripted_quantity": 1000000, "unit_price": 1.0, "expected_amount": 1000000.0, "paid_amount": 1000000.0, "subscription_note_template_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80", "subscription_note_document_key": "5ea88fca-4ca3-4dfe-aea4-35e431aef3c5/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_note/f206d799-cb94-48d5-81c5-5988ecef8079", "envelope_signature_status": "pending_creation", "envelope_signature_url": "https://certifiqi.com.br/envelope_key", "envelope_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80", "subscription_payment_list": [ { "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "description": "Comprovante itau", "amount": 1000000.0, "subscription_payment_status": "confirmed", "updated_at": "2025-01-27T14:33:54.214891" } ] } ``` --- ### **Response Body Params** | Campo | Tipo | Descrição | |-----------------------------------------------------------|------------|---------------------------------------------------------------------------| | `subscription_key` | string | Chave única da subscrição (UUID v4). | | `investor_key` | string | Chave única do investidor associado à subscrição (UUID v4). | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Número do documento do investidor (CPF ou CNPJ). | | `investor_bank_account` | object | **[Objeto investor_bank_account](#objeto-investor_bank_account)**. | | `subscription_date` | string | Data da subscrição (formato: YYYY-MM-DD). | | `financial_base_date` | string | Data base financeira da subscrição (formato: YYYY-MM-DD). | | `subscripted_quantity` | integer | Quantidade de cotas subscritas. | | `unit_price` | number | Preço unitário das cotas subscritas. | | `expected_amount` | number | Valor total esperado da subscrição. | | `paid_amount` | number | Valor total pago na subscrição. | | `subscription_note_template_key` | string | Chave única do template da nota de subscrição (UUID v4). | | `subscription_note_document_key` | string | Chave única do documento da nota de subscrição. | | `envelope_signature_status` | string | Status de assinatura da nota de subscrição. | | `envelope_signature_url` | string | URL de assinatura da nota de subscrição. | | `envelope_key` | string | Chave do envelope de assinatura. | | `subscription_payment_list` | array | Lista de pagamentos associados à subscrição. **[Objeto subscription_payment_list](#objeto-subscription_payment_list)**. | --- ### Objeto investor_bank_account | Campo | Tipo | Descrição | |--------------------------------|------------|---------------------------------------------------------| | `account_number` | string | Número da conta bancária do investidor. | | `account_digit` | string | Dígito verificador da conta bancária do investidor. | | `account_branch` | string | Agência bancária do investidor. | | `financial_institution_code_number` | string | Código da instituição financeira do investidor. | | `financial_institution_ispb` | string | ISPB da instituição financeira do investidor. | ### Objeto subscription_payment_list | Campo | Tipo | Descrição | |-----------------------------------------------------------|------------|---------------------------------------------------------------------------| | `subscription_payment_key` | string | Chave única do pagamento da subscrição (UUID v4). | | `payment_receipt_document_key` | string | Chave do documento do comprovante de pagamento. | | `description` | string | Descrição do comprovante de pagamento. | | `amount` | number | Valor do pagamento registrado. | | `subscription_payment_status` | string | Status do pagamento. Valores possíveis: `waiting_confirmation`, `confirmed`, `denied`. | | `updated_at` | string | Data e hora da última atualização do pagamento (formato: ISO 8601). | --- # Registro de Pagamento de Subscrição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento Este endpoint permite registrar um pagamento associado a uma subscrição de integralização. O pagamento inclui um valor declarado e um comprovante em Base64. --- ## Registro de Pagamento (POST) ### Request ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment MÉTODO POST ### Path Params | Campo | Tipo | Descrição | Caracteres | | ----------------------- | ------ | ------------------------------------------------- | ---------- | | `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36 | | `SUBSCRIPTION-KEY` | string | Chave única da subscrição associada (UUID v4). | 36 | --- ### Request Body ```json { "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0", "amount": 100000.00, "description": "Comprovante de pagamento Itau R$100.000,00" } ``` ### Request Body Params | Campo | Tipo | Descrição | Obrigatório | | -------------------- | ------- | ---------------------------------------------- | ------------ | | `document_base64`* | string | Comprovante de pagamento codificado em Base64. | Sim | | `amount`* | number | Valor declarado do pagamento realizado. | Sim | | `description` | *number | Descrição do conteúdo do comprovante. | Sim | --- ### Response STATUS 201 Response Body ```json { "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177", "description": "Comprovante de pagamento Itau R$100.000,00", "amount": 100000.0, "subscription_payment_status": "waiting_confirmation", "updated_at": null } ``` --- ### Response Body Params | Campo | Tipo | Descrição | | ------------------------------- | ------ | ----------------------------------------------------------------------------------------------- | | `subscription_payment_key` | string | Chave única do pagamento da subscrição (UUID v4). | | `amount` | number | Valor declarado do pagamento registrado. | | `subscription_payment_status` | string | Status atual do pagamento. Valores possíveis:`waiting_confirmation` `confirmed` `denied` | | `description` | number | Descrição do conteúdo do comprovante. | --- --- # Recebimento de Webhooks URL: /documentation/escrituracao/introducao/autenticacao_webhooks A assinatura dos Webhooks utiliza-se de uma estratégia de criptografia com chaves simétricas, ou seja, tanto a QI CTVM quanto o Parceiro integrador compartilham de uma mesma chave. Ao realizarmos uma configuração de Webhooks, iremos gerar uma Signature Key e disponibiliza-lá. Toda requisição originada no sistema da QI, irá carregar um header SIGNATURE que será um JWT assinado com essa chave. O encoding é realizado com o algoritmo HS256. Abaixo temos um exemplo em python de como realizar o decoding da assinatura: ```python from jose import jwt signature_key = "CHAVE UNICA CONFIGURADA" signature_token = headers["SIGNATURE"] decoded_token = jwt.decode(signature_token, key=signature_key, algorithms=["HS256"]) print(decoded_token) ``` Sugerimos que, além de comparar a assinatura, o parceiro integrador valide o nosso IP, dado que todas as nossas requisições são originadas de um mesmo IP, conforme o ambiente: |Ambiente| IP | |--------|----| |Produção| - | |Sandbox | - | :::danger Atenção! Os webhooks da QI CTVM não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs. ::: --- # Escrituração de Notas Comerciais URL: /documentation/escrituracao/introducao/ Essa documentação tem como objetivo descrever os fluxos, endpoints e estruturas de dados necessárias para operar e emissão de **Notas Comerciais**. Obs.: Em caso de dúvidas em qualquer etapa do processo favor entre em contato com [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br) detalhando seu problema/dúvida que te auxiliaremos. ## Ambientes (Hosts) A QI CTVM possui dois ambientes, SANDBOX e PRODUÇÃO. Ambos os ambientes possuem código e comportamento completamente idênticos, porém, o ambiente de SANDBOX apresenta valores monetários totalmente fictícios, e o ambiente de Produção realiza transações financeiras válidas. O ambiente Sandbox foi criado para os desenvolvedores realizarem suas integrações, e quando estiverem prontos para entrada em produção, atualizarem apenas as variáveis de ambiente com os parâmetros de Produção. | Ambiente | Host | |----------|----------------------------------------------| | Sandbox | https://api.sandbox.securities.qidtvm.com.br | | Produção | https://api.securities.qidtvm.com.br | --- # Endpoints de teste URL: /documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste ## Método GET ### Request ENDPOINT /authentication_test MÉTODO GET ### Response STATUS 200 Response Body ```json { "success": "Congrats!" } ``` ## Metodo POST ### Request ENDPOINT /authentication_test MÉTODO POST Request Body ```json { "name": "QI Tech" } ``` ### Response STATUS 200 Response Body ```json { "name": "QI Tech", "success": "Congrats!" } ``` --- # Teste de autenticação URL: /documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao ### 1. Introdução Nessa seção iremos explicar como deve funcionar a requisição para que possa ser aceita pelo nosso sistema. Em primeiro Lugar deve-se colocar no header API-CLIENT-KEY a Api Key fornecida pelo time da QI CTVM. Depois deve-se criar um Header de AUTHORIZATION assinando com a Chave Privada do parceiro integrador; Abaixo iremos ensinar o passo a passo utilizando de Python para exemplificar o processo de criação da AUTHORIZATION. ### 2. Importar bibliotecas Neste exemplo em python estamos usando 5 bibliotecas para poder realizar o processo de autenticação. ```python from datetime import datetime import json from jose import jwt from hashlib import md5 import requests ``` ### 3. Inserir a chave privada e a chave de integração ```python title="Dados da criptografia" api_key = "\" client_private_key = '''-----BEGIN EC PRIVATE KEY----- MIHbAgEBBEH7OuewosJfz4zKF+Gm0ogJxhb8G6LSMDVQQbFYz335mHCx9/Pr6Yk+ yYwsVozeXhlry3/vnUn1zCasU+4O+yseZ6AHBgUrgQQAI6GBiQOBhgAEAa46fN/2 8vI64shRhu9erMA6JLl3zHFX8gFHQrbb0g4IDfjXCKMCILiwdtL8QecstsgepTa7 yo1pTXOVNDbmLX2TAK38xb2Gv6OC+PA+5drF2wWajWbVLpR2R7mYEzr5HNIAJYHb 5C1jvM2ItK2R22HAbYfH25nsvGhkCGbrRNWQVF9g -----END EC PRIVATE KEY-----''' ``` ### 4. Definir variáveis Definir as variáveis método, endpoint e conteúdo particular a cada requisição (neste exemplo, utilizaremos o método "POST" para o endpoint "/authentication_test") ```python title="Dados da requisição" base_url = "https://api.securities.qidtvm.com.br" today_str = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S") method = "POST" endpoint = "/authentication_test" body = {"name": "QI Tech"} ``` ### 5. Construir Dicionário Base de Assinatura ```python title="Dicionário base" dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint} ``` #### 5.1. Se necessário, adicionar o conteúdo Para as requisições que tenham _body_, deve-se adicionar o md5 do bytes desse conteúdo. Como todas as requisições no nosso sistema são através de JSON, pode-se usar o seguinte: ```python title="Dicionário base" body_bytes = json.dumps(body).encode() md5_instance = md5() md5_instance.update(body_bytes) md5_body = md5_instance.hexdigest() dict_to_sign["payload_md5"] = md5_body ``` ### 6. Realizar criptografia do header Realizar criptografia utilizando biblioteca JWT (neste exemplo de código, utilizamos jsonwebtoken como jwt em javascript) ```python jwt_headers = {"alg": "ES512", "typ": "JWT"} encoded_header_token = jwt.encode( claims=dict_to_sign, key=client_private_key, algorithm="ES512", headers=jwt_headers, ) ``` ### 7. Montando o header final ```python headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token} ``` ```python title="Definindo url final" url = f"{base_url}{endpoint}" ``` ### Realizando requisição ```python resp = requests.post(url=url, headers=headers, json=body) print(resp.json()) ``` --- # Troca de Chaves URL: /documentation/escrituracao/introducao/troca_de_chaves ## 1. Requisição Assinada Todas as requisições em nossas APIs devem usar o protocolo **HTTPs**, utilizando **TLS 1.2 ou 1.3**, contendo dois Headers: 1. API-CLIENT-KEY: Uma chave disponibilizada pelo nosso time de Integração que identifica uma integração específica; 2. AUTHORIZATION: Uma assinatura da requisição que deve ser realizada conforme explicado nesse manual; Como padrão a QI CTVM utiliza-se do padrão de chaves assimétricas, onde existem duas chaves diferentes, uma para assinatura, denominada chave privada , e uma para leitura, denominada de chave pública . Com a chave privada, o parceiro integrador deverá realizar a assinatura utilizando-se do padrão JWT. O parceiro integrador é responsável por gerar o par e fornecer ao time da QI CTVM a chave pública para que possamos validar as suas requisições. :::caution **Atenção** A chave privada é de uso exclusivo do parceiro integrador, e deve ser armazenada com segurança. A QI CTVM nunca irá pedir, em hipótese alguma, que voce a compartilhe conosco. ::: ## 2. Gerando o par Para gerar uma chave privada em um computador UNIX faça: ```bash $ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key ``` E a partir desta chave privada gere sua chave pública. ```bash $ openssl ec -in private.key -pubout -outform PEM -out public.key.pub ``` A chave pública gerada (arquivo public.key.pub) deve ser enviada para o time da QI Tech, e aguardar a integração ser configurada; --- # Consulta de Ativo URL: /documentation/escrituracao/operacoes-ativas/consulta-security Este endpoint permite consultar os detalhes de um ativo utilizando sua chave única. --- ## **Request** ENDPOINT /security/security/ SECURITY-KEY MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres | |--------------|--------|-----------------------------------------------|------------| | `SECURITY-KEY` | string | Chave única do security (UUID v4). | 36 | --- ## **Response** STATUS 200 Response Body ```json { "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4", "security_key": "42bd7161-5ec1-4f64-ac0c-861d93ffb4c2", "operation_key": "8eb2291e-2dbf-4af1-9d12-f29fac665ed2", "operation_type": "commercial_paper", "contract_number": "0000000027", "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618", "issuer_name": "Blue Logic", "issuer_document_number": "97.923.586/0001-06", "issuer_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "4464541", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "financial_base_date": "2025-02-18", "current_unit_price": 1.0, "latest_accrual_date": "2025-02-18", "integralized_quantity": 100000, "issue_quantity": 100000, "security_status": "active", "is_defaulted": false, "financial": { "financial_base_date": "2025-02-18", "issue_quantity": 100000, "unit_price": 1.0, "issue_amount": 100000.0, "released_amount": 100000.0, "cet": 1.0, "annual_cet": 12.68, "number_of_installments": 5, "prefixed_interest_rate": { "daily_rate": 0.0003271877, "annual_rate": 0.1268250301, "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "post_fixed_interest_rate": null, "financial_index": null, "fine_delay_rate": { "daily_rate": 0.00032719, "annual_rate": 0.12682503, "monthly_rate": 0.01, "interest_base": "calendar_days_365" }, "contract_fine_rate": 0.02, "fees": [ { "type": "internal", "amount": 2.0, "fee_type": "bookkeeping_fee", "fee_amount": 2000.0, "amount_type": "percentage" }, { "type": "external", "amount": 5.0, "fee_type": "structuring_fee", "fee_amount": 5000.0, "amount_type": "percentage" } ], "installment_list": [ { "installment_key": "959a1d8f-9f7f-4b5b-b963-828693caad58", "installment_status": "opened", "installment_number": 5, "workdays": 21, "calendar_days": 30, "principal_amortization_unit_price": 0.20395804, "principal_amortization_amount": 20395.80431829, "interest_amount": 201.13568171, "interest_amount_unit_price": 0.00201136, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 20395.80431829, "due_interest": 0.0, "due_date": "2025-07-18", "has_interest": true, "current_unit_price": 0.20395804, "latest_accrual_date": "2025-02-18", "paid_at": null, "paid_amount": 0.0, "settlement_process_list": [] }, { "installment_key": "b1f4fc31-7b73-45b8-bce7-4256394b974e", "installment_status": "paid", "installment_number": 1, "workdays": 18, "calendar_days": 28, "principal_amortization_unit_price": 0.19676756, "principal_amortization_amount": 19676.75638427, "interest_amount": 920.18361573, "interest_amount_unit_price": 0.00920184, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 100000.0, "due_interest": 0.0, "due_date": "2025-03-18", "has_interest": true, "current_unit_price": 0.19676756, "latest_accrual_date": "2025-02-18", "paid_at": "2025-02-18T18:39:47.174392", "paid_amount": 20596.94, "settlement_process_list": [ { "settlement_process_key": "a9030b64-5003-4f82-be4f-8296a4e0b140", "installment_key": "b1f4fc31-7b73-45b8-bce7-4256394b974e", "due_date": "2025-03-18", "reference_date": "2025-03-18", "current_integralized_quantity": 100000, "principal_amortization_amount": 19676.75638427, "interest_amount": 920.18361573, "post_fixed_interest_amount": 0.0, "fine_amount": 0.0, "total_amount": 20596.94, "expected_total_amount": 20596.94, "paid_amount": 20596.94, "settlement_process_status": "paid", "paid_at": "2025-02-18T18:39:47.185004", "settlement_process_payment_list": [ { "settlement_process_payment_key": "69615875-ed71-44f2-9a06-20f6ea4276f3", "investment": { "investment_key": "4b705afb-18cb-4fe5-922a-5eab71c2b558", "acquisition_date": "2025-02-18", "acquisition_unit_price": 1.0, "acquisition_amount": 100000.0, "acquisition_quantity": 100000.0, "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "investor_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "total_sell_amount": 0.0, "total_yield_amount": 920.18, "total_amortization_amount": 20596.94, "current_quantity": 100000, "investment_transaction_list": [ { "transaction_type": "integralization", "transaction_date": "2025-02-18", "transaction_unit_price": 1.0, "transaction_amount": 100000.0, "transaction_quantity": 100000.0, "amortization_amount": 0.0, "yield_amount": 0.0, "old_quantity": 0.0, "new_quantity": 100000.0, "investment_transaction_origin": "subscription", "investment_transaction_origin_key": "8549efc4-76e3-4e62-abd1-71162b383b4e" }, { "transaction_type": "maturity", "transaction_date": "2025-03-18", "transaction_unit_price": 0.2059694, "transaction_amount": 20596.94, "transaction_quantity": 0.0, "amortization_amount": 20596.94, "yield_amount": 920.18, "old_quantity": 100000.0, "new_quantity": 100000.0, "investment_transaction_origin": "settlement_process_payment", "investment_transaction_origin_key": "69615875-ed71-44f2-9a06-20f6ea4276f3" } ] }, "investment_quantity": 100000, "amount": 20596.94, "paid_at": "2025-02-18T18:39:47.159822", "settlement_process_payment_status": "paid", "settlement_process_payment_type": "manual", "settlement_process_payment_receipt_list": [ { "settlement_process_payment_receipt_key": "47fa434a-68cc-47d4-af8c-6a84061f38a6", "settlement_process_payment_receipt_status": "confirmed", "updated_at": "2025-02-18T18:39:47.153603" } ] } ] } ] }, { "installment_key": "dafc9683-a2b3-4bde-bf9a-ff4b2ea2599f", "installment_status": "opened", "installment_number": 2, "workdays": 23, "calendar_days": 35, "principal_amortization_unit_price": 0.19671978, "principal_amortization_amount": 19671.97807672, "interest_amount": 924.96192328, "interest_amount_unit_price": 0.00924962, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 80323.24361573, "due_interest": 0.0, "due_date": "2025-04-22", "has_interest": true, "current_unit_price": 0.19671978, "latest_accrual_date": "2025-02-18", "paid_at": null, "paid_amount": 0.0, "settlement_process_list": [] }, { "installment_key": "aab04935-763e-4431-b0e8-d3d341d5c563", "installment_status": "opened", "installment_number": 3, "workdays": 18, "calendar_days": 27, "principal_amortization_unit_price": 0.20058857, "principal_amortization_amount": 20058.85739386, "interest_amount": 538.08260614, "interest_amount_unit_price": 0.00538083, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 60651.26553901, "due_interest": 0.0, "due_date": "2025-05-19", "has_interest": true, "current_unit_price": 0.20058857, "latest_accrual_date": "2025-02-18", "paid_at": null, "paid_amount": 0.0, "settlement_process_list": [] }, { "installment_key": "6a76fd8f-631b-4b42-ac2e-daae8f87401d", "installment_status": "opened", "installment_number": 4, "workdays": 22, "calendar_days": 30, "principal_amortization_unit_price": 0.20196604, "principal_amortization_amount": 20196.60382686, "interest_amount": 400.33617314, "interest_amount_unit_price": 0.00400336, "post_fixed_interest_amount": 0.0, "post_fixed_interest_amount_unit_price": 0.0, "amount": 20596.94, "due_principal": 40592.40814515, "due_interest": 0.0, "due_date": "2025-06-18", "has_interest": true, "current_unit_price": 0.20196604, "latest_accrual_date": "2025-02-18", "paid_at": null, "paid_amount": 0.0, "settlement_process_list": [] } ] }, "investment_list": [ { "investment_key": "4b705afb-18cb-4fe5-922a-5eab71c2b558", "acquisition_date": "2025-02-18", "acquisition_unit_price": 1.0, "acquisition_amount": 100000.0, "acquisition_quantity": 100000.0, "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "investor_bank_account": { "account_type": "checking", "account_digit": "3", "account_branch": "0001", "account_number": "33400254", "financial_institution_ispb": "32402502", "financial_institution_code_number": "329" }, "total_sell_amount": 0.0, "total_yield_amount": 920.18, "total_amortization_amount": 20596.94, "current_quantity": 100000, "investment_transaction_list": [ { "transaction_type": "integralization", "transaction_date": "2025-02-18", "transaction_unit_price": 1.0, "transaction_amount": 100000.0, "transaction_quantity": 100000.0, "amortization_amount": 0.0, "yield_amount": 0.0, "old_quantity": 0.0, "new_quantity": 100000.0, "investment_transaction_origin": "subscription", "investment_transaction_origin_key": "8549efc4-76e3-4e62-abd1-71162b383b4e" }, { "transaction_type": "maturity", "transaction_date": "2025-03-18", "transaction_unit_price": 0.2059694, "transaction_amount": 20596.94, "transaction_quantity": 0.0, "amortization_amount": 20596.94, "yield_amount": 920.18, "old_quantity": 100000.0, "new_quantity": 100000.0, "investment_transaction_origin": "settlement_process_payment", "investment_transaction_origin_key": "69615875-ed71-44f2-9a06-20f6ea4276f3" } ] } ] } ``` ## **Response Body Params** | Campo | Tipo | Descrição | |------------------------------|----------|--------------------------------------------------------------| | `tenant_key` | string | Chave única do tenant associado ao security. | | `security_key` | string | Chave única do security. | | `operation_key` | string | Chave única da operação associada ao security. | | `operation_type` | string | Tipo da operação. Valores possíveis: `commercial_paper`. | | `contract_number` | string | Número do contrato associado ao security. | | `issuer_key` | string | Chave única do emissor associado. | | `issuer_name` | string | Nome do emissor do security. | | `issuer_document_number` | string | Número do documento do emissor (CPF/CNPJ). | | `issuer_bank_account` | object | **[Objeto issuer_bank_account](#objeto-bank_account)**. | | `financial_base_date` | string | Data base financeira do security. | | `current_unit_price` | number | Preço unitário atual do security. | | `latest_accrual_date` | string | Data do último accrual realizado. | | `integralized_quantity` | integer | Quantidade total de cotas integralizadas. | | `issue_quantity` | integer | Quantidade total de cotas emitidas na operação. | | `security_status` | string | Status do security. Valores possíveis: `active`, `inactive`. | | `is_defaulted` | boolean | Indica se o security está inadimplente (`true` ou `false`). | | `financial` | object | **[Objeto financial](#objeto-financial)**. | | `investment_list` | array | Lista de investimentos. **[Objeto investment](#objeto-investment)**. | --- ### **Objeto bank_account** | Campo | Tipo | Descrição | |--------------------------------|----------|-------------------------------------------------| | `account_number` | string | Número da conta bancária do emissor. | | `account_digit` | string | Dígito verificador da conta bancária do emissor. | | `account_branch` | string | Agência bancária do emissor. | | `financial_institution_ispb` | string | ISPB da instituição financeira do emissor. | | `financial_institution_code_number` | string | Código da instituição financeira do emissor. | --- ### **Objeto financial** | Campo | Tipo | Descrição | |--------------------------------|----------|-------------------------------------------------| | `financial_base_date` | string | Data base financeira. | | `issue_quantity` | integer | Quantidade de cotas emitidas. | | `unit_price` | number | Preço unitário das cotas. | | `issue_amount` | number | Valor total da emissão. | | `released_amount` | number | Valor total liberado. | | `cet` | number | Custo efetivo total (CET). | | `annual_cet` | number | Custo efetivo total anualizado. | | `number_of_installments` | integer | Número total de parcelas. | | `prefixed_interest_rate` | object | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)**. | | `post_fixed_interest_rate` | object | **[Objeto post_fixed_interest_rate](#objeto-post_fixed_interest_rate)**. | | `financial_index` | object | **[Objeto financial_index](#objeto-financial_index)**. | | `fine_delay_rate` | object | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)**. | | `contract_fine_rate` | number | Multa contratual. | | `fees` | array | Lista de taxas. **[Objeto fees](#objeto-fees)**. | | `installment_list` | array | Lista de parcelas. **[Objeto installment](#objeto-installment)**. | --- ### **Objeto investment** | Campo | Tipo | Descrição | |--------------------------------|----------|-------------------------------------------------| | `investment_key` | string | Chave única do investimento. | | `acquisition_date` | string | Data de aquisição do investimento. | | `acquisition_unit_price` | number | Preço unitário na aquisição. | | `acquisition_amount` | number | Valor total da aquisição. | | `acquisition_quantity` | integer | Quantidade de cotas adquiridas. | | `investor_key` | string | Chave única do investidor. | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Documento do investidor (CPF/CNPJ). | | `investor_bank_account` | object | **[Objeto investor_bank_account](#objeto-bank_account)**. | | `total_sell_amount` | number | Valor total de vendas realizadas. | | `total_yield_amount` | number | Valor total de rendimentos. | | `total_amortization_amount` | number | Valor total de amortizações. | | `current_quantity` | integer | Quantidade atual de cotas. | | `investment_transaction_list` | array | Lista de transações. **[Objeto investment_transaction](#objeto-investment_transaction)**. | --- ### **Objeto investment_transaction** | Campo | Tipo | Descrição | |--------------------------------|----------|-------------------------------------------------| | `transaction_type` | string | Tipo da transação (`integralization`, `maturity`). | | `transaction_date` | string | Data da transação. | | `transaction_unit_price` | number | Preço unitário na transação. | | `transaction_amount` | number | Valor total da transação. | | `transaction_quantity` | integer | Quantidade de cotas transacionadas. | | `amortization_amount` | number | Valor de amortização na transação. | | `yield_amount` | number | Valor de rendimento na transação. | | `old_quantity` | integer | Quantidade de cotas antes da transação. | | `new_quantity` | integer | Quantidade de cotas após a transação. | | `investment_transaction_origin`| string | Origem da transação (`subscription`, `settlement_process_payment`). | | `investment_transaction_origin_key` | string | Chave da origem da transação. | ### **Objeto prefixed_interest_rate** | Campo | Tipo | Descrição | |---------------------|--------|--------------------------------------------------| | `daily_rate` | number | Taxa de juros diária prefixada. | | `annual_rate` | number | Taxa de juros anual prefixada. | | `monthly_rate` | number | Taxa de juros mensal prefixada. | | `interest_base` | string | Base de cálculo dos juros (`calendar_days_365`). | --- ### **Objeto post_fixed_interest_rate** | Campo | Tipo | Descrição | |---------------------|--------|---------------------------------------------------| | `daily_rate` | number | Taxa de juros diária pós-fixada. | | `annual_rate` | number | Taxa de juros anual pós-fixada. | | `monthly_rate` | number | Taxa de juros mensal pós-fixada. | | `interest_base` | string | Base de cálculo dos juros (`calendar_days_365`). | --- ### **Objeto financial_index** | Campo | Tipo | Descrição | |------------------|--------|-------------------------------------------------| | `index_type` | string | Tipo do índice financeiro (`CDI`, `IPCA`, etc.). | | `index_value` | number | Valor do índice financeiro. | --- ### **Objeto fine_delay_rate** | Campo | Tipo | Descrição | |---------------------|--------|------------------------------------------------| | `daily_rate` | number | Taxa de juros diária para atraso no pagamento. | | `annual_rate` | number | Taxa de juros anual para atraso no pagamento. | | `monthly_rate` | number | Taxa de juros mensal para atraso no pagamento. | | `interest_base` | string | Base de cálculo dos juros (`calendar_days_365`).| --- ### **Objeto fees** | Campo | Tipo | Descrição | |-------------|---------|--------------------------------------------| | `type` | string | Tipo da taxa (`internal`, `external`). | | `amount` | number | Percentual ou valor absoluto da taxa. | | `fee_type` | string | Tipo da taxa. | | `fee_amount`| number | Valor monetário da taxa aplicada. | | `amount_type` | string | Tipo do valor (`percentage`, `absolute`). | --- ### **Objeto installment** | Campo | Tipo | Descrição | |----------------------------------------|---------|-----------------------------------------------------------| | `installment_key` | string | Chave única da parcela. | | `installment_status` | string | Status da parcela | | `installment_number` | integer | Número da parcela na sequência do cronograma. | | `workdays` | integer | Quantidade de dias úteis até o vencimento. | | `calendar_days` | integer | Quantidade de dias corridos até o vencimento. | | `principal_amortization_unit_price` | number | Valor unitário da amortização do principal. | | `principal_amortization_amount` | number | Valor total da amortização do principal. | | `interest_amount` | number | Valor total dos juros da parcela. | | `interest_amount_unit_price` | number | Valor unitário dos juros da parcela. | | `post_fixed_interest_amount` | number | Valor total dos juros pós-fixados da parcela. | | `post_fixed_interest_amount_unit_price` | number | Valor unitário dos juros pós-fixados da parcela. | | `amount` | number | Valor total da parcela. | | `due_principal` | number | Valor do principal pendente antes da parcela. | | `due_interest` | number | Valor dos juros pendentes antes da parcela. | | `due_date` | string | Data de vencimento da parcela. | | `has_interest` | boolean | Indica se a parcela contém juros (`true` ou `false`). | | `current_unit_price` | number | Preço unitário atualizado da parcela. | | `latest_accrual_date` | string | Data do último accrual da parcela. | | `paid_at` | string | Data do pagamento da parcela (se aplicável). | | `paid_amount` | number | Valor total pago da parcela (se aplicável). | | `settlement_process_list` | array | Lista de processos de liquidação. **[Objeto settlement_process](#objeto-settlement_process)** | ### **Objeto settlement_process** | Campo | Tipo | Descrição | |-----------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------| | `settlement_process_key` | string | Chave única do processo de liquidação. | | `installment_key` | string | Chave única da parcela associada à liquidação. | | `due_date` | string | Data de vencimento da parcela associada. | | `reference_date` | string | Data de referência da liquidação. | | `current_integralized_quantity` | integer | Quantidade de cotas integralizadas no momento da liquidação. | | `principal_amortization_amount` | number | Valor da amortização do principal. | | `interest_amount` | number | Valor total dos juros pagos na liquidação. | | `post_fixed_interest_amount` | number | Valor dos juros pós-fixados pagos na liquidação. | | `fine_amount` | number | Valor da multa aplicada (se houver). | | `total_amount` | number | Valor total da liquidação. | | `expected_total_amount` | number | Valor total esperado da liquidação. | | `paid_amount` | number | Valor total pago na liquidação. | | `settlement_process_status` | string | Status da liquidação (`waiting_payment`, `paid`, `canceled`). | | `paid_at` | string | Data do pagamento da liquidação (se aplicável). | | `settlement_process_payment_list` | array | Lista de pagamentos associados à liquidação. **[Objeto settlement_process_payment](#objeto-settlement_process_payment)** | ### **Objeto settlement_process_payment** | Campo | Tipo | Descrição | |---------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------| | `settlement_process_payment_key` | string | Chave única do pagamento do processo de liquidação. | | `investment` | object | Informações do investimento. **[Objeto investment](#objeto-investment)**. | | `investment_quantity` | integer | Quantidade de cotas do investimento envolvidas no pagamento. | | `amount` | number | Valor do pagamento realizado. | | `paid_at` | string | Data e hora do pagamento (formato ISO 8601). | | `settlement_process_payment_status` | string | Status do pagamento (`waiting_payment`, `paid`, `canceled`). | | `settlement_process_payment_type` | string | Tipo do pagamento (`manual`). | | `settlement_process_payment_receipt_list` | array | Lista de recibos do pagamento. **[Objeto settlement_process_payment_receipt](#objeto-settlement_process_payment_receipt)**. | ### **Objeto settlement_process_payment_receipt** | Campo | Tipo | Descrição | |---------------------------------------------|--------|-------------------------------------------------------------------| | `settlement_process_payment_receipt_key` | string | Chave única do recibo de pagamento do processo de liquidação. | | `settlement_process_payment_receipt_status` | string | Status do recibo (`waiting_confirmation`, `confirmed`, `denied`). | | `amount` | number | Valor do recibo. | | `updated_at` | string | Data e hora da última atualização do recibo (formato ISO 8601). | ### **Enumeradores security_status** | Enum | Descrição | |-----------|------------------------------------------------------| | `issued` | A security foi emitida, mas ainda não está ativa. | | `active` | A security está ativa e em andamento. | | `matured` | A security chegou ao vencimento. | | `canceled` | A security foi cancelada. | ### **Enumeradores installment_status** | Enum | Descrição | |-----------------------------|-----------------------------------------------------------------------| | `created` | A parcela foi criada, mas ainda não está disponível para pagamento. | | `opened` | A parcela está aberta. | | `waiting_payment` | A parcela está aguardando o pagamento pelo investidor. | | `paid_partial` | A parcela foi parcialmente paga. | | `paid` | A parcela foi totalmente paga. | | `paid_early` | A parcela foi paga antecipadamente. | | `overdue` | A parcela venceu e não foi paga. | | `paid_partial_overdue` | A parcela foi parcialmente paga após o vencimento. | | `paid_overdue` | A parcela foi paga após o vencimento. | | `canceled` | A parcela foi cancelada e não precisa ser paga. | | `unmonitored` | A parcela não é monitorada para pagamentos. | --- # Consulta de Posição do Investidor URL: /documentation/escrituracao/operacoes-ativas/posicao-investidor Este endpoint permite consultar a posição consolidada de um investidor, retornando informações sobre suas participações em securities. --- ## Request ENDPOINT /security/investor/ INVESTOR-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|-----------------------------------------------|------------| | `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09", "investor_name": "Ultimate Cascade", "investor_document_number": "31.424.651/0001-32", "total_current_amount": 100000.0, "investment_list": [ { "current_unit_price": 1.0, "current_quantity": 100000, "security_key": "42bd7161-5ec1-4f64-ac0c-861d93ffb4c2", "contract_number": "0000000027", "investment_key": "4b705afb-18cb-4fe5-922a-5eab71c2b558", "current_amount": 100000.0 } ] } ``` --- ### Response Body Params | Campo | Tipo | Descrição | |----------------------------|----------|--------------------------------------------------------------------| | `investor_key` | string | Chave única do investidor. | | `investor_name` | string | Nome do investidor. | | `investor_document_number` | string | Número do documento do investidor (CNPJ). | | `total_current_amount` | number | Valor total consolidado do investidor. | | `investment_list` | array | Lista das participações do investidor em securities. **[Objeto investment](#objeto-investment)** | ### Objeto investment | Campo | Tipo | Descrição | |-----------------------|----------|--------------------------------------------------| | `current_unit_price` | number | Preço unitário atual da security. | | `current_quantity` | integer | Quantidade atual da security do investidor. | | `security_key` | string | Chave única da security associada. | | `contract_number` | string | Número do contrato da security. | | `investment_key` | string | Chave única do investimento do investidor. | | `current_amount` | number | Valor atual da participação do investidor. | --- # Webhooks de Escrituração URL: /documentation/escrituracao/webhooks-escrituracao ## Visão Geral Os webhooks de escrituração permitem que você receba notificações em tempo real sobre mudanças de status e eventos importantes relacionados ao processo de emissão de Notas Comerciais. Quando um evento ocorre, a QI Tech envia automaticamente um payload HTTP POST para a URL configurada em seu sistema. ## Configuração de Webhooks Para receber webhooks, você precisa configurar uma URL de endpoint em seu sistema. Consulte a [documentação de configuração de webhooks](./introducao/autenticacao_webhooks.md) para mais detalhes sobre como cadastrar e gerenciar suas URLs de webhook. ### Autenticação e Segurança Todos os webhooks enviados pela QI Tech incluem uma assinatura HMAC-SHA256 no header `Signature`. Esta assinatura deve ser validada em seu sistema para garantir a autenticidade e integridade dos dados recebidos. Para mais informações sobre o processo de validação, consulte a [documentação de autenticação de webhooks](./introducao/autenticacao_webhooks.md). ## Eventos Disponíveis ### Gestão de Emissores #### Cadastro Emissor Aprovado Enviado quando o cadastro de um emissor é aprovado pelo compliance. **Event Type:** `issuer_management.issuer_status_change` **Payload:** ```json { "event_type": "issuer_management.issuer_status_change", "event_datetime": "2025-07-30T15:32:00Z", "event_data": { "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "status": "approved" } } ``` #### Cadastro Emissor Reprovado Enviado quando o cadastro de um emissor é reprovado pelo compliance. **Event Type:** `issuer_management.issuer_status_change` **Payload:** ```json { "event_type": "issuer_management.issuer_status_change", "event_datetime": "2025-07-30T15:32:00Z", "event_data": { "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "status": "reproved" } } ``` #### Auto-assinatura do Emissor — Mudança de Status Enviado quando o envelope do termo de adesão é aberto e quando esse envelope é resolvido. O envelope é aberto durante a própria [solicitação da habilitação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura), que já responde em `pending_signature` — para quem fez a chamada, este webhook confirma o que a resposta trouxe; para os demais consumidores do tenant, é o aviso de que o termo está disponível para assinatura. A habilitação é solicitada pelo integrador em [`POST .../auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura). Consulte o [fluxo da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) para o significado de cada status. O evento é disparado em três momentos: `pending_signature`, `enabled` e `reproved`. A criação da auto-assinatura (`pending_term_generation`) e o cancelamento (`canceled`) **não** geram webhook — a criação é a resposta da própria solicitação, e o cancelamento é observado pela [consulta da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura). **Event Type:** `issuer_management.auto_signature_status_change` **Payload:** ```json { "event_type": "issuer_management.auto_signature_status_change", "event_datetime": "2026-02-10T09:16:03Z", "event_data": { "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "pending_signature" } } ``` | Campo | Tipo | Descrição | |---|---|---| | `issuer_key` | string | Chave única do emissor. | | `issuer_auto_signature_key` | string | Chave única da auto-assinatura. | | `status` | string | Status atual. No webhook, sempre `pending_signature`, `enabled` ou `reproved`. | Como tratar cada status recebido: | Status recebido | O que fazer | |---|---| | `pending_signature` | Consultar os [links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) e direcionar cada assinante do emissor ao seu próprio link. | | `enabled` | O emissor está habilitado: as emissões seguintes são assinadas automaticamente. | | `reproved` | O envelope do termo foi recusado, cancelado ou expirou. As emissões seguem pelo fluxo de assinatura manual até que uma nova habilitação seja criada. | ### Gestão de Contas de Liquidação #### Abertura de Conta de Liquidação Rejeitada Enviado quando o BaaS rejeita a abertura da conta de liquidação do emissor — por exemplo, por bloqueio no Bacen Protege+. A conta não é aberta, e a integralização do emissor fica impedida até que uma nova solicitação seja aprovada. Não há evento correspondente de aprovação: a abertura bem-sucedida é observada pela [consulta da conta de liquidação](./integralizacao-cotas/consulta-conta-liquidacao.md). **Event Type:** `liquidation_account.account_request_status_change` **Payload:** ```json { "event_type": "liquidation_account.account_request_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "account_request_key": "7e1c53d6-d372-4020-be6b-ed94248d7ae9", "status": "rejected", "rejection_reason": "Rejeitado devido ao Bacen Protege+", "account_info": { "account_branch": "0001", "account_number": "1234567", "account_digit": "3" } } } ``` O campo `account_info` é opcional e só é enviado quando o BaaS informa os dados da conta recusada. O `rejection_reason` é repassado como recebido do BaaS. ### Gestão de Investidores #### Cadastro Investidor Aprovado Enviado quando o cadastro de um investidor é aprovado pelo compliance. **Event Type:** `investor_management.investor_status_change` **Payload:** ```json { "event_type": "investor_management.investor_status_change", "event_datetime": "2025-07-30T15:32:00Z", "event_data": { "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "status": "approved" } } ``` #### Cadastro Investidor Reprovado Enviado quando o cadastro de um investidor é reprovado pelo compliance. **Event Type:** `investor_management.investor_status_change` **Payload:** ```json { "event_type": "investor_management.investor_status_change", "event_datetime": "2025-07-30T15:32:00Z", "event_data": { "investor_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "status": "reproved" } } ``` ### Gestão de Operações #### Operação Aprovada Enviado quando uma operação é aprovada pelo compliance e está pronta para ser enviada para assinatura. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "pending_signature_submission" } } ``` #### Operação Reprovada Enviado quando uma operação é reprovada na análise (pré-análise automática ou análise manual do compliance). A operação não segue para assinatura. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "compliance_reproved", "reproval_reason": { "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue." } } } ``` O campo `reproval_reason` traz os motivos da reprovação em um objeto de chave e descrição. Na pré-análise automática, cada chave é a regra de elegibilidade que reprovou a operação. O campo pode vir `null` quando a reprovação não registrou nenhum motivo. #### Operação Enviada para Assinatura Enviado quando uma operação é enviada para assinatura das partes envolvidas. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "waiting_signature" } } ``` #### Operação Assinada e Emitida Enviado quando uma operação é assinada por todas as partes. Este evento confirma que a Nota Comercial foi emitida com sucesso. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "issued", "signed_files_url": "https://storage.googleapis.com/commercial-paper-bucket/89c7f73a-c184-400c-bb2a-dd4424075a4f/signed_files?X-Goog-Algorithm=..." } } ``` O campo `signed_files_url` traz o link para download de um arquivo compactado com todos os contratos assinados da operação, disponível independentemente do método de assinatura utilizado. O link tem validade de 7 dias a partir do envio do webhook. #### Operação Cancelada Enviado quando uma operação é cancelada. **Event Type:** `commercial_paper.operation_status_change` **Payload:** ```json { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2025-07-30T15:45:00Z", "event_data": { "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f", "status": "canceled" } } ``` ### Gestão de Subscrições #### Subscrição Enviada para Assinatura Enviado quando uma subscrição é criada e enviada para assinatura do investidor. **Event Type:** `subscription.subscription_status_change` **Payload:** ```json { "event_type": "subscription.subscription_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "status": "waiting_signature" } } ``` #### Subscrição Assinada Enviado quando a subscrição é assinada por todas as partes e está aguardando o pagamento. **Event Type:** `subscription.subscription_status_change` **Payload:** ```json { "event_type": "subscription.subscription_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "status": "waiting_payment" } } ``` #### Subscrição Finalizada Enviado quando a subscrição é completamente finalizada após a confirmação do pagamento. **Event Type:** `subscription.subscription_status_change` **Payload:** ```json { "event_type": "subscription.subscription_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "status": "finished" } } ``` #### Subscrição Cancelada Enviado quando a subscrição é cancelada por reprovação na análise de elegibilidade da integralização. A boleta e o envelope de assinatura são cancelados junto. **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." } } } ``` O campo `cancellation_reason` identifica o motivo do cancelamento de forma estável. Para `ineligible`, o campo `ineligible_reasons` traz um objeto em que cada chave é a regra de elegibilidade que reprovou a integralização e cada valor é a descrição correspondente. ### Gestão de Pagamentos de Subscrição #### Comprovante de Pagamento Incluído Enviado quando um comprovante de pagamento é incluído e está aguardando confirmação. **Event Type:** `subscription_payment.subscription_payment_status_change` **Payload:** ```json { "event_type": "subscription_payment.subscription_payment_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1", "status": "waiting_confirmation" } } ``` #### Comprovante de Pagamento Aprovado Enviado quando o comprovante de pagamento é aprovado e confirmado. **Event Type:** `subscription_payment.subscription_payment_status_change` **Payload:** ```json { "event_type": "subscription_payment.subscription_payment_status_change", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099", "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c", "subscription_payment_key": "1413020c-6965-40fb-a162-632459d35fd1", "status": "confirmed" } } ``` ## Fluxo de Eventos ### Fluxo de Emissão de Nota Comercial 1. **Cadastro do Emissor** → `issuer_status_change` (approved/reproved) 2. **Cadastro do Investidor** → `investor_status_change` (approved/reproved) 3. **Criação da Operação** → `operation_status_change` (pending_signature_submission) 4. **Envio para Assinatura** → `operation_status_change` (waiting_signature) 5. **Operação Emitida** → `operation_status_change` (issued) ### Fluxo de Subscrição 1. **Criação da Subscrição** → `subscription_status_change` (waiting_signature) 2. **Assinatura Concluída** → `subscription_status_change` (waiting_payment) 3. **Inclusão do Comprovante** → `subscription_payment_status_change` (waiting_confirmation) 4. **Pagamento Confirmado** → `subscription_payment_status_change` (confirmed) 5. **Subscrição Finalizada** → `subscription_status_change` (finished) ## Boas Práticas 1. **Responda rapidamente**: Retorne um status HTTP 2xx o mais rápido possível para confirmar o recebimento do webhook. 2. **Processamento assíncrono**: Para operações demoradas, confirme o recebimento imediatamente e processe o evento de forma assíncrona. 3. **Idempotência**: Implemente lógica idempotente, pois webhooks podem ser reenviados em caso de falha de rede. 4. **Validação de assinatura**: Sempre valide a assinatura HMAC antes de processar o webhook. 5. **Logs e monitoramento**: Mantenha logs detalhados de todos os webhooks recebidos para auditoria e debugging. ## Referências - [Configuração de Webhooks](./introducao/autenticacao_webhooks.md) --- # Inserção de Documentos URL: /documentation/iaas/aditamento_recebiveis/envio_documento ### Request ENDPOINT /asset_amendment/fund_class/FUND_CLASS_KEY/amendment_configuration/AMENDMENT_CONFIGURATION_KEY/asset_amendment/ASSET_AMENDMENT_KEY/document MÉTODO POST ```json title='Request Body' { "document_type":"amendment_term", "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==" } ``` #### Body Params | Campo | Tipo | Descrição |-|-|-| | `document_type` * | string | Tipo do documento (sempre amendment_term).| | `document_b64` * | string | Deve ser o binário do arquivo, em PDF, encodado em Base64. ### Response STATUS 201 ```json title='Response Body' { "document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a" } ``` --- # Introdução URL: /documentation/iaas/aditamento_recebiveis/inicio O sistema de Aditamento de Recebíveis é uma solução que permite a modificação e atualização de contratos e acordos existentes relacionados a recebíveis. Este módulo oferece funcionalidades essenciais para: - Realizar alterações em contratos de recebíveis já existentes - Gerenciar modificações em condições de pagamento Esta documentação fornece uma visão detalhada sobre como utilizar o sistema de aditamento, incluindo seus principais recursos e fluxos. Aqui você encontrará informações sobre: - Processos de aditamento - Endpoints e payloads Para começar a utilizar o sistema, navegue pelos tópicos disponíveis nesta documentação para entender melhor cada aspecto do módulo de aditamento. --- # Criação de pedido de aditamento URL: /documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato --- Para realizar um pedido de aditamento é necessário realizar uma requisição usando a chave única que representa o fundo(FUND_CLASS_KEY, fornecida pela Qi Tech) e a chave única que representa as configurações da esteira de aditamento(AMENDMENT_CONFIGURATION_KEY, fornecida pela Qi Tech). Nos aditamentos realizados por este sistema é permitido a alteração do fluxo de pagamento ou taxa nominal do contrato ou ambos. Também é possível definir que o aditamento será realizado juntamente com uma entrada realizada pelo devedor. ### Request ENDPOINT /asset_amendment/fund_class/FUND_CLASS_KEY/amendment_configuration/AMENDMENT_CONFIGURATION_KEY/asset_amendment MÉTODO POST ```json title='Request Body' { "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "amendment_date": "2024-04-01", "amendment_type": "all_contract", "down_payment_value": 400.23, "installments":[ { "maturity_date": "2025-01-31", "face_value": 1000.31, "installment_number": 1 }, { "maturity_date": "2025-02-31", "face_value": 1000.31, "installment_number": 2 } ], "pre_fixed":{ "monthly_rate": 0.02, "calendar_base": "workdays" } } ``` #### Body Params | Campo | Tipo | Descrição | Obrigatório | |-|-|-|-| | `asset_external_id` | string | Chave única de identificação do contrato que está sendo aditado. | Sim | | `amendment_date` | string | Data que o aditamento está sendo realizado (formato: YYYY-MM-DD) | Sim | | `amendment_type` | string | Tipo de aditamento a ser realizado. Ver **[Enumerador Tipo de Aditamento](#enumerador-tipo-de-aditamento) | Sim | | `down_payment_value` | number | Valor da entrada a ser paga pelo devedor no momento do aditamento | Não | | `installments` | array | Lista de parcelas do contrato após o aditamento | Sim | | `installments[].maturity_date` | string | Data de vencimento da parcela (formato: YYYY-MM-DD) | Sim | | `installments[].face_value` | number | Valor nominal da parcela | Sim | | `installments[].installment_number` | number | Número sequencial da parcela | Sim | | `pre_fixed` | object | Configurações de taxa pré-fixada | Sim | | `pre_fixed.monthly_rate` | number | Taxa mensal a ser aplicada | Sim | | `pre_fixed.calendar_base` | string | Base de calendário para cálculo (ex: "workdays") | Sim | ### Response STATUS 201 ```json title='Response Body' { "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642", "status": "pending_assets_insertion", } ``` ### Enumerador Tipo de Aditamento | Enumerador | Descrição | |--------------|---------------| | **payment_flow** | Aditamento apenas de fluxo de pagamento | | **nominal_rate** | Aditamento apenas de taxa nominal do contrato | | **all_contract** | Aditamento do fluxo de pagament e taxa nominal do contrato | :::caution **Atenção** Os campos de installments e pre_fixed devem o não existir de acordo com o tipo de aditamento a ser realizado conforme a seguinte tabela ::: | Tipo de aditamento | installments | pre_fixed | |------------------- | ------------ | --------- | | all_contract | Obrigatório | Obrigatório | | pre_fixed | Não deve ser enviado | Obrigatório | | payment_flow | Obrigatório | Não deve ser enviado | --- # Boletador de Títulos Públicos URL: /documentation/iaas/boletador/boletador_titulos_publicos ## Request ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operation MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | | :---- | :---- | :---- | | `fund_class_key` | string | Identificador único do fundo. | ```json title="Request Body" { "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b", "operation_date": "2025-12-04", "payment_date": "2025-12-04", "operation_part": "assignee", "operation_type": "outright_operation", "counterparty": { "iselic_number": "20824264", "selic_account_number": "123456789", "document_number": "20.824.264/0001-77" }, "treasury_type": "ntn_b", "unit_price": 1234.567891, "units": 10, "maturity_date": "2035-05-15" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | | :---- | :---- | :---- | :---- | | `external_id` | string | opcional | Identificador externo para idempotência (UUID). Se não informado, será gerado automaticamente. Máximo de 36 caracteres. | | `operation_date` | string (date) | obrigatório | Data da operação no formato `YYYY-MM-DD`. Deve ser um dia útil e igual à `accounting_date` do fundo. | | `payment_date` | string (date) | obrigatório | Data de liquidação no formato `YYYY-MM-DD`. Deve ser `>= operation_date`. Em operações não-a-prazo (`outright_operation`, `buyback_operation`), deve ser igual à `operation_date`. | | `operation_part` | string | obrigatório | Papel do fundo na operação: `assignee` (comprador) ou `assignor` (vendedor). | | `operation_type` | string | obrigatório | Tipo de operação: `outright_operation`, `buyback_operation`. `buyback_operation` exige `operation_part == "assignee"`. | | `counterparty` | object | obrigatório | Dados da contraparte. Ver objeto abaixo. | | `treasury_type` | string | obrigatório | Tipo de título: `lft`, `ltn`, `ntn_b` ou `ntn_f`. | | `unit_price` | number | obrigatório | Preço unitário do título. Aceita qualquer precisão decimal; o servidor trunca para baixo conforme o tipo: `buyback_operation` → 8 casas decimais; demais → 6 casas decimais. | | `units` | integer | obrigatório | Quantidade de títulos (inteiro positivo). | | `maturity_date` | string (date) | obrigatório | Data de vencimento do título (`YYYY-MM-DD`). Deve ser estritamente posterior à `operation_date`. | | `yearly_negotiated_rate` | number | condicional | Taxa negociada anual (%). **Obrigatório para** `buyback_operation`. | | `return_date` | string (date) | condicional | Data de retorno (`YYYY-MM-DD`). **Obrigatório para** `buyback_operation`. Deve ser `> operation_date`. | #### Objeto `counterparty` | Campo | Tipo | Obrigatoriedade | Descrição | | :---- | :---- | :---- | :---- | | `iselic_number` | string | obrigatório | Número iSELIC da contraparte (8 dígitos). | | `selic_account_number` | string | obrigatório | Conta SELIC da contraparte (9 dígitos). | | `document_number` | string | obrigatório | CNPJ da contraparte com pontuação (formato `XX.XXX.XXX/XXXX-XX`). | ## Response STATUS 201 ```json title="Response Body" { "operation_key": "85cfd700-54a4-40f4-bc61-2ece992864ea", "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b", "fund_class": { "fund_class_key": "5122bf31-660a-4f61-a447-38e5e17162dd", "manager_key": "bea7581a-f901-4995-a486-46e18ae61aab", "name": "FUNDO EXEMPLO DTVM", "document_number": "81.692.758/0001-30", "accounting_date": "2025-12-04" }, "status": "pending_manager_approval", "operation_part": "assignee", "operation_type": { "enumerator": "outright_operation", "code": 1052 }, "treasury": { "enumerator": "ntn_b", "code": 760199 }, "operation_date": "2025-12-04", "payment_date": "2025-12-04", "maturity_date": "2035-05-15", "total_operation_value": 12345.67, "units": 10, "unit_price": 1234.567891, "counterparty": { "iselic_number": "20824264", "document_number": "20.824.264/0001-77", "selic_account_number": "123456789" }, "isin_code": "BRSTNCNTB633", "issue_date": "2025-11-04", "operation_data": {} } ``` ### Atributos da resposta | Campo | Tipo | Descrição | | :---- | :---- | :---- | | `operation_key` | string | Identificador único da operação gerado pela QI Tech (UUID). | | `external_id` | string | Identificador externo fornecido ou gerado automaticamente. | | `fund_class` | object | Dados do fundo associado à operação. | | `status` | string | Status inicial da operação. | | `operation_part` | string | `assignee` (comprador) ou `assignor` (vendedor). | | `operation_type` | object | `{ enumerator, code }` — tipo de operação e código SELIC correspondente. | | `treasury` | object | `{ enumerator, code }` — tipo de título e código SELIC correspondente. | | `operation_date` | string | Data da operação (`YYYY-MM-DD`). | | `payment_date` | string | Data de liquidação (`YYYY-MM-DD`). | | `maturity_date` | string | Data de vencimento do título (`YYYY-MM-DD`). | | `total_operation_value` | decimal | Valor total da operação (units × unit_price). | | `units` | integer | Quantidade de títulos. | | `unit_price` | number | Preço unitário do título. | | `counterparty` | object | Dados da contraparte (`iselic_number`, `document_number`, `selic_account_number`). | | `isin_code` | string | Código ISIN do título. | | `issue_date` | string | Data de emissão do título (`YYYY-MM-DD`). | | `operation_data` | object | Metadados internos adicionais da operação. | --- # Listagem de Títulos Públicos URL: /documentation/iaas/boletador/listagem_titulos_publicos ## Request ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operations MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | | :---- | :---- | :---- | | `fund_class_key` | string | Identificador único do fundo. | ### Query params | Parâmetro | Tipo | Padrão | Máximo | Descrição | | :---- | :---- | :---- | :---- | :---- | | `limit` | integer | 100 | 500 | Quantidade de itens por página. | | `page` | integer | 0 | — | Número da página (base 0). | | `status` | string | — | — | Filtra pelo status exato da operação. | | `not_status` | string | — | — | Exclui operações com determinado status. | | `treasury_type` | string | — | — | Filtra por tipo de título (`lft`, `ltn`, `ntn_b`, `ntn_f`). | | `operation_type` | string | — | — | Filtra por tipo de operação (`outright_operation`, `buyback_operation`). | | `operation_date` | string | — | — | Filtra pela data exata da operação (`YYYY-MM-DD`). | | `from_operation_date` | string | — | — | Filtra operações com data `>=` ao valor (`YYYY-MM-DD`). | | `to_operation_date` | string | — | — | Filtra operações com data `<=` ao valor (`YYYY-MM-DD`). | | `maturity_date` | string | — | — | Filtra pela data exata de vencimento (`YYYY-MM-DD`). | | `from_maturity_date` | string | — | — | Filtra vencimentos `>=` ao valor (`YYYY-MM-DD`). | | `to_maturity_date` | string | — | — | Filtra vencimentos `<=` ao valor (`YYYY-MM-DD`). | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "operation_key": "e96ff035-e0bc-4819-931a-6a9f7fc1c597", "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b", "fund_class": { "fund_class_key": "9b6145dc-2207-428d-84c1-2f949461891a", "manager_key": "73a21e11-0ab7-461d-a93f-1e90c0a5dc0d", "name": "FUNDO DE INVESTIMENTO TESTE", "document_number": "41.202.838/0001-45", "accounting_date": "2025-04-14", "custodian": { "name": "QI DISTRIBUIDORA DE TITULOS E VALORES MOBILIARIOS LTDA", "document_number": "46.955.383/0001-52", "iselic_number": "46955383" }, "selic_account_number": "000216832", "target_account_key": "d3dcbf3c-1bbf-495b-b792-ac448ee20ac4" }, "status": "pending_manager_approval", "operation_part": "assignee", "operation_type": { "enumerator": "outright_operation", "code": 1052 }, "treasury": { "enumerator": "ntn_b", "code": 760199 }, "operation_date": "2025-04-14", "payment_date": "2025-04-14", "maturity_date": "2025-05-15", "total_operation_value": 250.0, "units": 5, "unit_price": 50.0, "counterparty": { "iselic_number": "20824264", "document_number": "20.824.264/0001-77", "selic_account_number": "123456789" }, "isin_code": "BRSTNCNTB633", "issue_date": "2000-07-15", "operation_data": {} } ], "limit": 100, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | | :---- | :---- | :---- | | `data` | array | Lista de operações. Cada item contém os mesmos campos da consulta individual. | | `limit` | integer | Quantidade de itens retornados na página. | | `page` | integer | Página atual (base 0). | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | --- # Introdução URL: /documentation/iaas/boletos/inicio Nesta seção iremos explicar como funciona o ecossistema de **emissão de boletos** no contexto de uma **cessão de recebíveis para Fundos de Investimento**. ## Estrutura de Emissão de Boletos O processo de emissão de boletos dentro da cessão de recebíveis segue a seguinte estrutura: 1. **Cadastro do conta cobrança e geração do contrato de cessão** - [5.2.4. Contrato de Cessão](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato) 2. **Registro do Boleto** - O boleto é registrado no banco emissor assim que a cessão é paga. - Informações obrigatórias: - Identificação do cedente - Identificação do sacado (pagador) - Valor nominal - Data de vencimento 3. **Confirmação do Registro** - A confirmação do registro do boleto é feita no proximo dia útil no processamento do retorno bancário 4. **Liquidação** - Quando o boleto é pago pelo sacado, a liquidação é capturada e atualizada automaticamente. - O fluxo financeiro segue para a conta principal do Fundo, compondo o caixa disponível. 5. **Baixa** - Caso o pagamento do titulo seja feito por uma baixa cedente ou substituição, o boleto é baixado automaticamente :::warning Para que a emissão de boletos ocorra de forma **automática**, é obrigatório que o **Contrato de Cessão** contenha todas as informações de cobrança necessárias e que exista uma **conta de cobrança devidamente cadastrada** no sistema. ::: Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox), quanto em ambiente produtivo. --- # Instruções de Boleto URL: /documentation/iaas/boletos/instrucoes_boleto Este endpoint permite enviar instruções a um boleto já registrado, como prorrogação de vencimento, atualização de juros e multa, inclusão de descontos, abatimento, baixa e solicitação de protesto. ## Request ENDPOINT /bankslip_collection/fund_class/ FUND_CLASS_KEY /bankslip_configuration/ BANKSLIP_CONFIGURATION_KEY /bankslip/ BANKSLIP_KEY MÉTODO PUT ### Path Parameters | Campo | Tipo | Descrição | Caracteres | |--------------------------------|--------|------------------------------------------------------------------------|------------| | `fund_class_key` | uuidv4 | Chave única de identificação da classe de fundo, no formato uuid v4 | 36 | | `bankslip_configuration_key` | uuidv4 | Chave única de identificação da configuração do boleto, no formato uuid v4 | 36 | | `bankslip_key` | uuidv4 | Chave única de identificação do boleto, no formato uuid v4 | 36 | ### Request Body Params O campo `occurrence_type` define qual instrução será enviada ao boleto. O campo `occurrence_data` contém os dados específicos da instrução, quando aplicável. | Campo | Tipo | Descrição | Caracteres | |-------------------|--------|---------------------------------------------------------------------------|-------------------------------------------------------------------------| | `occurrence_type` | string | Tipo da instrução a ser enviada ao boleto. | **[Enumerador occurrence_type](#enumeradores-occurrence_type)** | | `occurrence_data` | object | Dados da instrução. Obrigatório para os tipos que exigem parâmetros adicionais. | Varia conforme o `occurrence_type` | ### Enumeradores occurrence_type | Enumerador | Descrição | |------------------------|-----------------------------------------------------| | `due_date_extension` | Prorrogação da data de vencimento | | `delay_interest_update`| Atualização dos juros de mora | | `delay_fine_update` | Atualização da multa por atraso | | `rebate` | Aplicação de abatimento | | `rebate_withdrawn` | Cancelamento do abatimento | | `discount_inclusion` | Inclusão de descontos | | `write_off` | Baixa do boleto | | `protest_request` | Solicitação de protesto | --- ### Instrução: `due_date_extension` — Prorrogação de Vencimento Request Body ```json { "occurrence_type": "due_date_extension", "occurrence_data": { "due_date": "2026-12-31" } } ``` #### Objeto occurrence_data — due_date_extension | Campo | Tipo | Descrição | Caracteres | |------------|--------|---------------------------------------------------|------------| | `due_date` | string | Nova data de vencimento do boleto (formato `YYYY-MM-DD`) | 10 | --- ### Instrução: `delay_interest_update` — Atualização de Juros de Mora Request Body ```json { "occurrence_type": "delay_interest_update", "occurrence_data": { "interest": { "method": "pre_fixed", "pre_fixed": { "monthly_rate": 1.5, "calendar_base": "calendar_360" } } } } ``` #### Objeto occurrence_data — delay_interest_update | Campo | Tipo | Descrição | |------------|--------|---------------------------------------| | `interest` | object | Configuração dos juros de mora (ver abaixo). | #### Objeto interest | Campo | Tipo | Descrição | |--------------|--------|---------------------------------------------------------------| | `method` | string | Método de cálculo dos juros. Valor: `pre_fixed` | | `pre_fixed` | object | Parâmetros para o cálculo de juros pré-fixados (ver abaixo). | #### Objeto pre_fixed | Campo | Tipo | Descrição | |-----------------|--------|----------------------------------------------------------------------------------------------| | `monthly_rate` | number | Taxa mensal de juros (0.01 Equivale a 1% ao mes). | | `calendar_base` | string | Base de calendário para cálculo. **[Enumerador calendar_base](#enumeradores-calendar_base)** | #### Enumeradores calendar_base | Enumerador | Descrição | |-----------------|------------------------| | `calendar_360` | Base de 360 dias | | `workdays` | Dias úteis | | `calendar_365` | Base de 365 dias | --- ### Instrução: `delay_fine_update` — Atualização de Multa por Atraso Request Body ```json { "occurrence_type": "delay_fine_update", "occurrence_data": { "fine": { "fine_type": "percentage", "percentage_value": 2.0 } } } ``` #### Objeto occurrence_data — delay_fine_update | Campo | Tipo | Descrição | |--------|--------|----------------------------------------| | `fine` | object | Configuração da multa por atraso (ver abaixo). | #### Objeto fine | Campo | Tipo | Descrição | |--------------------|--------|------------------------------------------------------------------| | `fine_type` | string | Tipo da multa. Valor: `percentage` | | `percentage_value` | number | Percentual da multa. Deve ser maior ou igual a `0`. | --- ### Instrução: `rebate` — Abatimento Request Body ```json { "occurrence_type": "rebate", "occurrence_data": { "rebate": 50.00 } } ``` #### Objeto occurrence_data — rebate | Campo | Tipo | Descrição | |----------|--------|------------------------------------| | `rebate` | number | Valor do abatimento a ser aplicado. | --- ### Instrução: `rebate_withdrawn` — Cancelamento de Abatimento Esta instrução não requer `occurrence_data`. Request Body ```json { "occurrence_type": "rebate_withdrawn" } ``` --- ### Instrução: `discount_inclusion` — Inclusão de Descontos Request Body ```json { "occurrence_type": "discount_inclusion", "occurrence_data": { "discounts": [ { "discount_type": "percentage", "discount_number": 1, "discount_limit_date": "2026-11-30", "discount_amount": 5.0 } ] } } ``` #### Objeto occurrence_data — discount_inclusion | Campo | Tipo | Descrição | |-------------|-------------|----------------------------------------------------| | `discounts` | array | Lista de descontos a serem aplicados (ver abaixo). | #### Objeto discount (item do array discounts) | Campo | Tipo | Descrição | Caracteres | |-----------------------|--------|----------------------------------------------------------------------------------------------|------------| | `discount_type` | string | Tipo do desconto. **[Enumerador discount_type](#enumeradores-discount_type)** | - | | `discount_number` | number | Número sequencial do desconto. | - | | `discount_limit_date` | string | Data limite para aplicação do desconto (formato `YYYY-MM-DD`). | 10 | | `discount_amount` | number | Valor do desconto. | - | #### Enumeradores discount_type | Enumerador | Descrição | |-----------------------------------------------|----------------------------------------------------------------------------| | `absolute` | Valor fixo | | `percentage` | Porcentagem fixa | | `anticipation_workdays_daily_amount` | Valor diário de antecipação sobre dias úteis | | `anticipation_workdays_daily_percentage` | Porcentagem diária de antecipação sobre dias úteis | | `anticipation_calendar_days_daily_amount` | Valor diário de antecipação sobre dias corridos | | `anticipation_calendar_days_daily_percentage` | Porcentagem diária de antecipação sobre dias corridos | --- ### Instrução: `write_off` — Baixa do Boleto Esta instrução não requer `occurrence_data`. Request Body ```json { "occurrence_type": "write_off" } ``` --- ### Instrução: `protest_request` — Solicitação de Protesto Request Body ```json { "occurrence_type": "protest_request", "occurrence_data": { "protest_type": "protest" } } ``` #### Objeto occurrence_data — protest_request | Campo | Tipo | Descrição | |----------------|--------|----------------------------------------------------------------------------------------| | `protest_type` | string | Tipo do protesto. **[Enumerador protest_type](#enumeradores-protest_type)** | #### Enumeradores protest_type | Enumerador | Descrição | |----------------------|------------------------------| | `protest` | Protesto padrão | | `bankruptcy_protest` | Protesto por falência | --- ## Response STATUS 201 Response Body ```json title='Response Body' { "bankslip_key": "c9eb109c-800f-4cf5-b209-2119c9d77a72", "external_participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG", "bankslip_configuration": { "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4", "bankslip_profile": { "bankslip_profile_key": "5910d4a3-f5df-432a-902f-849a1a77cd86", "bankslip_profile_code": "329-09-0001-4993010", "bankslip_profile_number": 1, "bankslip_provider": "qi_scd", "additional_information": { "external_beneficiary_key": "2666e7a3-0bd7-46fc-8f6b-725f2ef9b13f" }, "internal_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b", "fund_class": { "fund_class_key": "7f03069e-1854-4cee-8e59-a6a548976015", "document_number": "51.620.927/0001-65", "name": "Sample Fund Class", "manager": { "name": "Sample Manager", "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153", "document_number": "51.620.927/0001-65" } } } }, "due_date": "2026-12-31", "face_value": 629.33, "status": "registered", "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG", "borrower": { "document_number": "755.510.684-12", "name": "Tomador Exemplo", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Cedente LTDA", "document_number": "37.341.966/0001-00", "person_type": "legal_person" }, "bankslip_type": "simple", "delay": null, "our_number": "00000012345", "our_number_digit": "6", "digitable_line": "32991.23456 78901.234567 89012.345678 9 00010000062933", "barcode": "32999000010000062933123456789012345678901234", "occurrences": [ { "occurrence_key": "e9898e50-cd2b-492f-9201-7e5c5f231853", "status": "pending_submission", "type": "due_date_extension", "occurrence_data": { "due_date": "2026-12-31" } } ], "settlement_instructions": [ { "settlement_instruction_key": "fe419363-bf04-4b3a-90bd-185618baa720", "status": "pending_bankslip_payment", "asset_type": "duplicata_mercantil", "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69", "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22", "issue_date": "2025-01-17", "maturity_date": "2026-12-31", "face_value": 629.33, "order_number": "49761-1" } ] } ``` ### Bankslip | Campo | Tipo | Descrição | |---------------------------------------|--------|------------------------------------------------------------------------| | `bankslip_key` | string | Identificador único do boleto. | | `external_participant_control_number` | string | Número de controle externo do participante. | | `bankslip_configuration` | object | Configuração do boleto (ver abaixo). | | `due_date` | date | Data de vencimento do boleto. | | `face_value` | number | Valor nominal do boleto. | | `status` | string | Status atual do boleto. | | `participant_control_number` | string | Número de controle interno do participante. | | `borrower` | object | Objeto que representa o tomador (sacado). | | `assignor` | object | Objeto que representa o cedente do recebível. | | `bankslip_type` | string | Tipo do boleto. | | `delay` | object | Dados de mora do boleto, quando aplicável. | | `order_number` | string | Número do pedido, quando disponível. | | `our_number` | string | Nosso número, quando disponível. | | `our_number_digit` | string | Dígito verificador do nosso número, quando disponível. | | `digitable_line` | string | Linha digitável do boleto, quando disponível. | | `barcode` | string | Código de barras do boleto, quando disponível. | | `occurrences` | array | Lista de ocorrências relacionadas ao boleto (cada item é um objeto). | | `settlement_instructions` | array | Lista de instruções de liquidação relacionadas ao boleto. | ### Bankslip Configuration | Campo | Tipo | Descrição | |------------------------------|--------|----------------------------------| | `bankslip_configuration_key` | string | Chave de configuração do boleto. | | `bankslip_profile` | object | Perfil de boleto associado. | ### Bankslip Profile | Campo | Tipo | Descrição | |----------------------------|--------|--------------------------------------------------------------| | `bankslip_profile_key` | string | Identificador do perfil de boleto. | | `bankslip_profile_code` | string | Código do perfil. | | `bankslip_profile_number` | number | Número do perfil. | | `bankslip_provider` | string | Provedor do boleto. | | `additional_information` | object | Informações adicionais do perfil. | | `internal_account_key` | string | Identificador da conta interna associada. | | `fund_class` | object | Objeto representando a classe de fundo (ver abaixo). | ### Fund Class | Campo | Tipo | Descrição | Caracteres | |-------------------|--------|-------------------------------------------------|------------| | `fund_class_key` | string | Chave única de identificação da classe de fundo | 36 | | `document_number` | string | CNPJ da classe de fundo | - | | `name` | string | Nome da classe de fundo | até 255 | ### Borrower | Campo | Tipo | Descrição | |-------------------|--------|--------------------------------| | `name` | string | Nome do tomador. | | `document_number` | string | Documento (CPF/CNPJ). | | `person_type` | string | Tipo de pessoa. | | `address` | object | Endereço do tomador. | ### Assignor | Campo | Tipo | Descrição | |-------------------|--------|-----------------------| | `name` | string | Nome do cedente. | | `document_number` | string | Documento (CNPJ). | | `person_type` | string | Tipo de pessoa. | ### Occurrences Cada item do array é um objeto com os seguintes campos: | Campo | Tipo | Descrição | |-------------------|--------|---------------------------------| | `occurrence_key` | string | Identificador da ocorrência. | | `status` | string | Status da ocorrência. | | `type` | string | Tipo da ocorrência. | | `occurrence_data` | object | Dados adicionais da ocorrência. | ### Settlement Instructions Cada item do array é um objeto com os seguintes campos: | Campo | Tipo | Descrição | |------------------------------|--------|------------------------------------------------------| | `settlement_instruction_key` | string | Identificador da instrução de liquidação. | | `status` | string | Status da instrução de liquidação. | | `asset_type` | string | Tipo do ativo. | | `asset_key` | string | Chave única do ativo no sistema. | | `external_id` | string | Identificador externo do cliente. | | `issue_date` | date | Data de emissão. | | `maturity_date` | date | Data de vencimento. | | `face_value` | number | Valor de face do ativo. | | `order_number` | string | Número do contrato. | --- ## Error Response STATUS 4xx Response Body: Error ```json { "title": "titulo", "description": "description in English", "translation": "descrição em portugues", "code": "codigo", "extra_fields": {} } ``` | Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (pt-br)
`translation` | |--------------------------|----------------------|-----------------------|--------------------------------------------------------------|------------------------------------------------------------------| | 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido | | 404 | BSC000009 | Bankslip not Found | Bankslip with key `{bankslip_key}` was not found. | Boleto com chave `{bankslip_key}` não foi encontrado. | --- # Recuperação de Arquivos CNAB URL: /documentation/iaas/boletos/recuperar_arquivo_retorno --- ## Listar arquivos CNAB Retorna uma lista paginada de arquivos CNAB (arquivos de remessa e retorno trocados com o banco) pertencentes a um perfil de boleto de uma classe de fundo. ### Request ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/cnab_files MÉTODO GET ### Path Params | Parâmetro | Descrição | |------------------------|-----------------------------------------------------------------------------------------------------------------------------| | `fund_class_key` | Chave da classe de fundo. Retorna `404` (`NotFoundFundClass`) caso não exista. | | `bankslip_profile_key` | Chave do perfil de boleto, que deve pertencer à classe de fundo. Retorna `404` (`NotFoundBankslipConfiguration`) caso não seja encontrado. | ### Query Params Todos os parâmetros são opcionais. | Parâmetro | Tipo | Descrição | |----------------|--------|-------------------------------------------------------------------------------| | `initial_date` | date | Filtra arquivos com `cnab_date` maior ou igual à data informada (YYYY-MM-DD). | | `final_date` | date | Filtra arquivos com `cnab_date` menor ou igual à data informada (YYYY-MM-DD). | | `cnab_type` | string | Filtra pelo tipo do arquivo (ver **[Tipo de CNAB](#tipo-de-cnab)**). | | `limit` | int | Valor entre 0 e 20 com o número de itens por página. Padrão: `10`. | | `page` | int | Número da página (começando por zero). Padrão: `0`. | Quando `is_last_page` for `false`, solicite a próxima `page` para recuperar os demais resultados. ### Response Response Body ```json title='Response Body' { "data": [ { "cnab_file_key": "79f21d3e-ed99-413c-8e05-39cf84fbab7c", "bankslip_profile": { "bankslip_profile_key": "a1d7f09b-cb77-48da-a23d-b83d97d4b46b", "bankslip_profile_code": "329-09-0001-0000000", "bankslip_profile_number": 9, "bankslip_provider": "qi_scd", "additional_information": { "requester_profile_key": "30f72181-042c-4aae-9be7-b2794916416f" }, "internal_account_key": "18809219-17d9-4845-a830-51e7f2beaf28", "fund_class": { "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9", "document_number": "00.000.000/0001-01", "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "GESTÃO DE RECURSOS", "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c", "document_number": "00.100.100/0001-00" } } }, "cnab_date": "2025-07-30", "type": "return", "status": "completed", "download_filename": "cnab-retorno-2025-07-30-79f21d3e.ret", "url": "https://s3.amazonaws.com/...", "external_cnab_file_key": "e8b5e962-eb5f-4b9d-8d2b-70cd6d3d5252", "number_of_occurrences": 6 }, { "cnab_file_key": "ff7aaa47-a901-4f66-98d7-46f76ca4fa16", "bankslip_profile": { "bankslip_profile_key": "e0771a02-4f3e-4162-a468-a872fc6975e4", "bankslip_profile_code": "329-09-0001-0000000", "bankslip_profile_number": 9, "bankslip_provider": "qi_scd", "additional_information": { "requester_profile_key": "cdec985f-e629-44ce-8511-a323f38bd63e" }, "internal_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "fund_class": { "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9", "document_number": "00.000.000/0001-01", "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "GESTÃO DE RECURSOS", "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c", "document_number": "00.100.100/0001-00" } } }, "cnab_date": "2025-07-30", "type": "external_return", "status": "completed", "download_filename": "cnab-retorno-2025-07-30-ff7aaa47.ret", "url": "https://s3.amazonaws.com/...", "external_cnab_file_key": "d3b1f7c4-9e2a-4f6b-8c1d-5a7e9b3f2c8e", "number_of_occurrences": 3, "bankslip_expenses": [ { "bankslip_expense_key": "4d727b05-00df-454e-93e3-160ec9ee596c", "type": "fee_or_costs.payment", "number_of_expenses": 3, "total_value": 2.25, "status": "completed" } ] } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Objeto Paginado | Campo | Tipo | Descrição | |----------------|---------|----------------------------------------------------------| | `data` | array | Lista de objetos de **[CNAB File](#cnab-file)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page` | boolean | Informação que indica se a página recuperada é a última | ### CNAB File | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------| | `cnab_file_key` | string | Identificador único do arquivo CNAB. | | `bankslip_profile` | object | Perfil de boleto associado (ver **[Bankslip Profile](/documentation/iaas/boletos/recuperar_boletos#bankslip-profile)**). | | `cnab_date` | date | Data do arquivo CNAB. | | `type` | string | Tipo do arquivo (ver **[Tipo de CNAB](#tipo-de-cnab)**). | | `status` | string | Status do arquivo (ver **[Status do CNAB](#status-do-cnab)**). | | `download_filename` | string | Nome com o qual o arquivo é baixado. | | `url` | string | URL pré-assinada para download do arquivo, válida por **1 hora**. Omitida caso não seja possível gerá-la. | | `external_cnab_file_key` | string | Identificador do arquivo CNAB externo. Presente apenas quando o arquivo possui esse valor. | | `header` | string | Header do arquivo. Presente apenas quando o arquivo possui esse valor. | | `trailer` | string | Trailer do arquivo. Presente apenas quando o arquivo possui esse valor. | | `number_of_occurrences` | int | Número de ocorrências do arquivo. Presente apenas quando o arquivo possui esse valor. | | `expectation` | object | Dados de expectativa do arquivo. Presente apenas quando o arquivo possui esse valor. | | `bankslip_expenses` | array | Lista de objetos de **[Bankslip Expense](#bankslip-expense)**. Presente apenas quando o arquivo possui despesas associadas. | ### Bankslip Expense | Campo | Tipo | Descrição | |------------------------|--------|-----------------------------------------| | `bankslip_expense_key` | string | Identificador único da despesa. | | `type` | string | Tipo da despesa. | | `number_of_expenses` | int | Quantidade de despesas agrupadas. | | `total_value` | number | Valor total das despesas. | | `status` | string | Status da despesa. | ## Tipo de CNAB | Enumerador | Descrição | |----------------------|-------------------------| | `return` | Arquivo Retorno | | `external_return` | Arquivo Retorno Externo | | `remittance` | Remessa | | `external_remittance`| Remessa Externa | ## Status do CNAB | Enumerador | Descrição | |----------------------|---------------------------| | `created` | Criado | | `pending_processing` | Processamento pendente | | `completed` | Concluído | | `canceled` | Cancelado | --- # Recuperação de Boleto e Segunda via URL: /documentation/iaas/boletos/recuperar_boleto --- ## Lista de Boletos ### Request ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/bankslip/BANKSLIP_KEY MÉTODO GET ### Response Response Body ```json title='Response Body' { "bankslip_key": "c9eb109c-800f-4cf5-b209-2119c9d77a72", "external_participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG", "asset_type": "duplicata_mercantil", "bankslip_configuration": { "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4", "bankslip_profile": { "bankslip_profile_key": "5910d4a3-f5df-432a-902f-849a1a77cd86", "bankslip_profile_code": "329-09-0001-4993010", "bankslip_profile_number": 1, "bankslip_provider": "qi_scd", "additional_information": { "external_beneficiary_key": "2666e7a3-0bd7-46fc-8f6b-725f2ef9b13f" }, "internal_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b", "fund_class": { "fund_class_key": "7f03069e-1854-4cee-8e59-a6a548976015", "document_number": "51.620.927/0001-65", "name": "Sample_Name", "manager": { "name": "Sample name", "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153", "document_number": "51.620.927/0001-65" } } } }, "due_date": "2026-04-21", "face_value": 629.33, "status": "pending_registration", "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG", "borrower": { "document_number": "755.510.684-12", "name": "Tomador", "person_type": "legal_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Assignor LTDA", "document_number": "37.341.966/0001-00", "person_type": "legal_person" }, "occurrences": [ { "occurrence_key": "e9898e50-cd2b-492f-9201-7e5c5f231853", "status": "pending_submission", "type": "registration", "occurrence_data": null } ], "settlement_instructions": [ { "settlement_instruction_key": "fe419363-bf04-4b3a-90bd-185618baa720", "status": "pending_bankslip_payment", "asset_type": "duplicata_mercantil", "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69", "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22", "issue_date": "2025-01-17", "maturity_date": "2026-09-17", "face_value": 629.33, "order_number": "49761-1" } ], "bankslip_url": "https://bankslip-proxys-bucket-production.s3.amazonaws.com/" } ``` ### Bankslip | Campo | Tipo | Descrição | |---------------------------------------|----------|----------------------------------------------------------------------| | `bankslip_key` | string | Identificador único do boleto. | | `external_participant_control_number` | string | Número de controle externo do participante. | | `asset_type` | string | Tipo de ativo atrelado. | | `due_date` | date | Data de vencimento do boleto. | | `face_value` | number | Valor nominal do boleto. | | `status` | string | Status atual do boleto. | | `participant_control_number` | string | Número de controle interno do participante. | | `bankslip_configuration` | object | Objeto que contém a configuração do boleto (ver abaixo). | | `borrower` | object | Objeto que representa o tomador (sacado). | | `assignor` | object | Objeto que representa o cedente do recebível. | | `occurrences` | array | Lista de ocorrências relacionadas ao boleto (cada item é um objeto). | | `settlement_instructions` | array | Lista de instruções de liquidação relacionadas ao boleto. | | `bankslip_url` | array | Link para recuperação de segunda via. | ### Bankslip Configuration | Campo | Tipo | Descrição | |--------------------------------------|----------|----------------------------------| | `bankslip_configuration_key` | string | Chave de configuração do boleto. | | `bankslip_profile` | object | Perfil de boleto associado. | --- ### Bankslip Profile | Campo | Tipo | Descrição | |--------------------------------------|----------|-------------------------------| | `bankslip_profile_key` | string | Identificador do perfil de boleto. | | `bankslip_profile_code` | string | Código do perfil. | | `bankslip_profile_number` | number | Número do perfil. | | `bankslip_provider` | string | Provedor do boleto. | | `additional_information` | object | Informações adicionais (ver abaixo). | | `internal_account_key` | string | Identificador da conta interna associada. | | `fund_class` | object | Objeto representando o fundo de investimento (ver abaixo). | ### Fund Class | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da classe de fundo | até 255 | | `fund_class_key` | string | Chave única de identificação da classe de fundo | 36 | | `document_number` | string | CNPJ da classe de fundo | - | ### Borrower | Campo | Tipo | Descrição | |--------------------------------------|----------|-------------------------------| | `name` | string | Nome do tomador. | | `document_number` | string | Documento (CPF/CNPJ). | | `person_type` | string | Tipo de pessoa. | | `address` | object | Endereço do tomador (ver abaixo). | ### Address | Campo | Tipo | Descrição | |--------------------------------------|----------|-------------------------------| | `street` | string | Logradouro do endereço. | | `number` | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `city` | string | Cidade. | | `postal_code` | string | CEP. | | `uf` | string | Unidade federativa (sigla do estado). | | `country` | string | País no formato ISO Alpha-3. | --- ## Assignor (Cedente) | Campo | Tipo | Descrição | |--------------------------------------|----------|-------------------| | `name` | string | Nome do cedente. | | `document_number` | string | Documento (CNPJ). | | `person_type` | string | Tipo de pessoa. | --- ## Occurrences Cada item do array é um objeto com os seguintes campos: | Campo | Tipo | Descrição | |--------------------------------------|----------|---------------------------------| | `occurrence_key` | string | Identificador da ocorrência. | | `status` | string | Status da ocorrência. | | `type` | string | Tipo da ocorrência. | | `occurrence_data` | object | Dados adicionais da ocorrência. | ## Settlement Instructions Cada item do array é um objeto com os seguintes campos: | Campo | Tipo | Descrição | |-------------------------------|----------|------------------------------------------------------| | `settlement_instruction_key` | string | Identificador da instrução de liquidação. | | `status` | string | Status da instrução de liquidação. | | `asset_type` | string | Tipo do ativo. | | `asset_key` | string | Chave única do ativo no sistema. | | `external_id` | string | Identifica externo do cliente (utilizado na cessão). | | `issue_date` | date | Data de emissão. | | `maturity_date` | date | Data de vencimento. | | `face_value` | number | Valor de face do ativo. | | `order_number` | string | Número do contrato. | | `installment_number` | number | Número da parcela do ativo. | --- # Recuperação de Boletos URL: /documentation/iaas/boletos/recuperar_boletos --- ## Lista de Boletos ### Request ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/bankslips MÉTODO GET ### Query Params | Parâmetro | Descrição | |------------------------------|------------------------------------------------------------| | `limit` | Valor entre 0 e 100 com o número de itens por página. | | `page` | Número da pagina (começando por zero). | | `borrower_document_number` | Número de documento do tomador (somente números). | | `assignor_document_number` | Número de documento do cedente (somente números). | | `participant_control_number` | Número de controle do participante. | | `order_number` | Número do contrato. | | `our_number` | Nosso número do boleto no banco. | ### Response Response Body ```json title='Response Body' { "data": [ { "bankslip_key": "c9eb109c-800f-4cf5-b209-2119c9d77a72", "external_participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG", "asset_type": "duplicata_mercantil", "bankslip_configuration": { "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4", "bankslip_profile": { "bankslip_profile_key": "5910d4a3-f5df-432a-902f-849a1a77cd86", "bankslip_profile_code": "329-09-0001-4993010", "bankslip_profile_number": 1, "bankslip_provider": "qi_scd", "additional_information": { "external_beneficiary_key": "2666e7a3-0bd7-46fc-8f6b-725f2ef9b13f" }, "internal_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b", "fund_class": { "fund_class_key": "7f03069e-1854-4cee-8e59-a6a548976015", "document_number": "51.620.927/0001-65", "name": "Sample_Name", "manager": { "name": "Sample name", "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153", "document_number": "51.620.927/0001-65" } } } }, "due_date": "2024-02-17", "face_value": 629.33, "status": "pending_registration", "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG", "borrower": { "document_number": "755.510.684-12", "name": "Tomador", "person_type": "legal_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Assignor LTDA", "document_number": "37.341.966/0001-00", "person_type": "legal_person" }, "occurrences": [ { "occurrence_key": "e9898e50-cd2b-492f-9201-7e5c5f231853", "status": "pending_submission", "type": "registration", "occurrence_data": null } ], "settlement_instructions": [ { "settlement_instruction_key": "fe419363-bf04-4b3a-90bd-185618baa720", "status": "pending_bankslip_payment", "asset_type": "duplicata_mercantil", "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69", "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22", "issue_date": "2025-01-17", "maturity_date": "2026-09-17", "face_value": 629.33, "order_number": "49761-1" } ], }, { "bankslip_key": "4584e60c-752f-479d-831a-50f09c2c7de2", "external_participant_control_number": "TBFBDWKTEWJ7UTR6CPL4BAE4P", "asset_type": "duplicata_mercantil", "bankslip_configuration": { "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4", "bankslip_profile": { "bankslip_profile_key": "5910d4a3-f5df-432a-902f-849a1a77cd86", "bankslip_profile_code": "329-09-0001-4993010", "bankslip_profile_number": 1, "bankslip_provider": "qi_scd", "additional_information": { "external_beneficiary_key": "2666e7a3-0bd7-46fc-8f6b-725f2ef9b13f" }, "internal_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b", "fund_class": { "fund_class_key": "7f03069e-1854-4cee-8e59-a6a548976015", "document_number": "51.620.927/0001-65", "name": "Sample_Name", "manager": { "name": "Sample name", "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153", "document_number": "51.620.927/0001-65" } } } }, "due_date": "2024-02-17", "face_value": 629.33, "status": "pending_registration", "participant_control_number": "TBFBDWKTEWJ7UTR6CPL4BAE4P", "borrower": { "document_number": "784.508.035-78", "name": "mgkstsdibe", "person_type": "legal_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Assignor LTDA", "document_number": "37.341.966/0001-00", "person_type": "legal_person" }, "occurrences": [ { "occurrence_key": "07ad7fce-fec6-40ac-be22-1ffd031f36bc", "status": "pending_submission", "type": "registration", "occurrence_data": null } ], "settlement_instructions": [ { "settlement_instruction_key": "fe419363-bf04-4b3a-90bd-185618baa720", "status": "pending_bankslip_payment", "asset_type": "duplicata_mercantil", "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69", "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22", "issue_date": "2025-01-17", "maturity_date": "2026-09-17", "face_value": 629.33, "order_number": "49761-1" } ], } ], "limit": 15, "page": 0, "is_last_page": true } ``` ### Objeto Paginado | Campo | Tipo | Descrição | |---------------|----------|----------------------------------------------------------------| | `data` | array | Lista de objetos de **[Bankslip](#bankslip)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean | Informação que indica se a página recuperada é a última | ### Bankslip | Campo | Tipo | Descrição | |---------------------------------------|----------|----------------------------------------------------------------------| | `bankslip_key` | string | Identificador único do boleto. | | `external_participant_control_number` | string | Número de controle externo do participante. | | `asset_type` | string | Tipo de ativo atrelado. | | `due_date` | date | Data de vencimento do boleto. | | `face_value` | number | Valor nominal do boleto. | | `status` | string | Status atual do boleto. | | `participant_control_number` | string | Número de controle interno do participante. | | `bankslip_configuration` | object | Objeto que contém a configuração do boleto (ver abaixo). | | `borrower` | object | Objeto que representa o tomador (sacado). | | `assignor` | object | Objeto que representa o cedente do recebível. | | `occurrences` | array | Lista de ocorrências relacionadas ao boleto (cada item é um objeto). | | `settlement_instructions` | array | Lista de instruções de liquidação relacionadas ao boleto. | ### Bankslip Configuration | Campo | Tipo | Descrição | |--------------------------------------|----------|----------------------------------| | `bankslip_configuration_key` | string | Chave de configuração do boleto. | | `bankslip_profile` | object | Perfil de boleto associado. | --- ### Bankslip Profile | Campo | Tipo | Descrição | |--------------------------------------|----------|-------------------------------| | `bankslip_profile_key` | string | Identificador do perfil de boleto. | | `bankslip_profile_code` | string | Código do perfil. | | `bankslip_profile_number` | number | Número do perfil. | | `bankslip_provider` | string | Provedor do boleto. | | `additional_information` | object | Informações adicionais (ver abaixo). | | `internal_account_key` | string | Identificador da conta interna associada. | | `fund_class` | object | Objeto representando o fundo de investimento (ver abaixo). | ### Fund Class | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da classe de fundo | até 255 | | `fund_class_key` | string | Chave única de identificação da classe de fundo | 36 | | `document_number` | string | CNPJ da classe de fundo | - | ### Borrower | Campo | Tipo | Descrição | |--------------------------------------|----------|-------------------------------| | `name` | string | Nome do tomador. | | `document_number` | string | Documento (CPF/CNPJ). | | `person_type` | string | Tipo de pessoa. | | `address` | object | Endereço do tomador (ver abaixo). | ### Address | Campo | Tipo | Descrição | |--------------------------------------|----------|-------------------------------| | `street` | string | Logradouro do endereço. | | `number` | string | Número do endereço. | | `neighborhood` | string | Bairro. | | `city` | string | Cidade. | | `postal_code` | string | CEP. | | `uf` | string | Unidade federativa (sigla do estado). | | `country` | string | País no formato ISO Alpha-3. | --- ## Assignor (Cedente) | Campo | Tipo | Descrição | |--------------------------------------|----------|-------------------| | `name` | string | Nome do cedente. | | `document_number` | string | Documento (CNPJ). | | `person_type` | string | Tipo de pessoa. | --- ## Occurrences Cada item do array é um objeto com os seguintes campos: | Campo | Tipo | Descrição | |--------------------------------------|----------|---------------------------------| | `occurrence_key` | string | Identificador da ocorrência. | | `status` | string | Status da ocorrência. | | `type` | string | Tipo da ocorrência. | | `occurrence_data` | object | Dados adicionais da ocorrência. | ## Settlement Instructions Cada item do array é um objeto com os seguintes campos: | Campo | Tipo | Descrição | |-------------------------------|----------|------------------------------------------------------| | `settlement_instruction_key` | string | Identificador da instrução de liquidação. | | `status` | string | Status da instrução de liquidação. | | `asset_type` | string | Tipo do ativo. | | `asset_key` | string | Chave única do ativo no sistema. | | `external_id` | string | Identifica externo do cliente (utilizado na cessão). | | `issue_date` | date | Data de emissão. | | `maturity_date` | date | Data de vencimento. | | `face_value` | number | Valor de face do ativo. | | `order_number` | string | Número do contrato. | | `installment_number` | number | Número da parcela do ativo. | --- # Recuperação de Carteiras de Cobrança URL: /documentation/iaas/boletos/recuperar_carteiras_cobranca --- ## Listar carteiras de cobrança Retorna uma lista paginada das carteiras de cobrança (bankslip profiles) de uma classe de fundo. O acesso é permitido apenas ao gestor responsável pela classe de fundo. ### Request ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profiles MÉTODO GET ### Path Params | Parâmetro | Descrição | |------------------|----------------------------------------------------------------------------------| | `fund_class_key` | Chave da classe de fundo. Retorna `404` (`NotFoundFundClass`) caso não exista. | ### Query Params Todos os parâmetros são opcionais. | Parâmetro | Tipo | Descrição | |-----------|------|-----------------------------------------------------------------------| | `limit` | int | Valor entre 0 e 50 com o número de itens por página. Padrão: `10`. | | `page` | int | Número da página (começando por zero). Padrão: `0`. | Quando `is_last_page` for `false`, solicite a próxima `page` para recuperar os demais resultados. ### Response Response Body ```json title='Response Body' { "data": [ { "bankslip_profile_key": "a1d7f09b-cb77-48da-a23d-b83d97d4b46b", "bankslip_profile_code": "329-09-0001-0000000", "bankslip_profile_number": 9, "bankslip_provider": "qi_scd", "additional_information": { "requester_profile_key": "30f72181-042c-4aae-9be7-b2794916416f" }, "internal_account_key": "18809219-17d9-4845-a830-51e7f2beaf28", "fund_class": { "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9", "document_number": "00.000.000/0001-01", "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "GESTÃO DE RECURSOS", "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c", "document_number": "00.100.100/0001-00" } }, "total_value": 12345.67, "total_overdue_value": 890.12 }, { "bankslip_profile_key": "e0771a02-4f3e-4162-a468-a872fc6975e4", "bankslip_profile_code": "329-09-0001-0000001", "bankslip_profile_number": 10, "bankslip_provider": "qi_scd", "additional_information": { "requester_profile_key": "cdec985f-e629-44ce-8511-a323f38bd63e" }, "internal_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "fund_class": { "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9", "document_number": "00.000.000/0001-01", "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "GESTÃO DE RECURSOS", "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c", "document_number": "00.100.100/0001-00" } } } ], "limit": 10, "page": 0, "is_last_page": true, "elapsed_time_ms": 12.34 } ``` ### Objeto Paginado | Campo | Tipo | Descrição | |-------------------|---------|------------------------------------------------------------------| | `data` | array | Lista de objetos de **[Bankslip Profile](#bankslip-profile)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page` | boolean | Informação que indica se a página recuperada é a última | | `elapsed_time_ms` | number | Tempo de execução da consulta no servidor, em milissegundos | ### Bankslip Profile | Campo | Tipo | Descrição | |---------------------------|--------|--------------------------------------------------------------------------------------------------------------------| | `bankslip_profile_key` | string | Identificador da carteira de cobrança. | | `bankslip_profile_code` | string | Código da carteira de cobrança. | | `bankslip_profile_number` | number | Número da carteira de cobrança. | | `bankslip_provider` | string | Provedor do boleto. | | `additional_information` | object | Informações adicionais da carteira de cobrança. | | `internal_account_key` | string | Identificador da conta interna associada. | | `fund_class` | object | Objeto representando a classe de fundo (ver **[Fund Class](/documentation/iaas/boletos/recuperar_boletos#fund-class)**). | | `total_value` | number | Valor total em aberto da carteira. Presente apenas após o cálculo periódico de saldo da carteira. | | `total_overdue_value` | number | Valor total vencido da carteira. Presente apenas após o cálculo periódico de saldo da carteira. | --- # Recuperação de Configurações de Boleto URL: /documentation/iaas/boletos/recuperar_configuracoes_boleto --- ## Listar configurações de boleto Retorna uma lista paginada das configurações de boleto de uma carteira de cobrança de uma classe de fundo. O acesso é permitido apenas ao gestor responsável pela classe de fundo. ### Request ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/bankslip_configurations MÉTODO GET ### Path Params | Parâmetro | Descrição | |------------------------|----------------------------------------------------------------------------------------------------------------------------| | `fund_class_key` | Chave da classe de fundo. Retorna `404` (`NotFoundFundClass`) caso não exista. | | `bankslip_profile_key` | Chave da carteira de cobrança, que deve pertencer à classe de fundo. Retorna `404` (`NotFoundBankslipProfile`) caso não seja encontrada. | ### Query Params Todos os parâmetros são opcionais. | Parâmetro | Tipo | Descrição | |---------------|--------|------------------------------------------------------------------------------------------------------------------| | `issuer_type` | string | Filtra pelo tipo do emissor (ver **[Tipo de Emissor](#tipo-de-emissor)**). Um valor desconhecido retorna o erro `InvalidValueForEntity`. | | `limit` | int | Valor entre 0 e 30 com o número de itens por página. Padrão: `10`. | | `page` | int | Número da página (começando por zero). Padrão: `0`. | Quando `is_last_page` for `false`, solicite a próxima `page` para recuperar os demais resultados. ### Response Response Body ```json title='Response Body' { "data": [ { "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4", "bankslip_profile": { "bankslip_profile_key": "a1d7f09b-cb77-48da-a23d-b83d97d4b46b", "bankslip_profile_code": "329-09-0001-0000000", "bankslip_profile_number": 9, "bankslip_provider": "qi_scd", "additional_information": { "requester_profile_key": "30f72181-042c-4aae-9be7-b2794916416f" }, "internal_account_key": "18809219-17d9-4845-a830-51e7f2beaf28", "fund_class": { "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9", "document_number": "00.000.000/0001-01", "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "GESTÃO DE RECURSOS", "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c", "document_number": "00.100.100/0001-00" } } }, "bankslip_issuer_type": "manager", "delay": 0, "our_number_range": { "our_number_range_initial": 1, "our_number_range_final": 99999 } }, { "bankslip_configuration_key": "9c47d1a8-3f2e-4b6d-8a1c-5e7f9b3d2c80", "bankslip_profile": { "bankslip_profile_key": "a1d7f09b-cb77-48da-a23d-b83d97d4b46b", "bankslip_profile_code": "329-09-0001-0000000", "bankslip_profile_number": 9, "bankslip_provider": "qi_scd", "additional_information": { "requester_profile_key": "30f72181-042c-4aae-9be7-b2794916416f" }, "internal_account_key": "18809219-17d9-4845-a830-51e7f2beaf28", "fund_class": { "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9", "document_number": "00.000.000/0001-01", "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "GESTÃO DE RECURSOS", "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c", "document_number": "00.100.100/0001-00" } } }, "bankslip_issuer_type": "internal", "delay": 1 } ], "limit": 10, "page": 0, "is_last_page": true, "elapsed_time_ms": 12.34 } ``` ### Objeto Paginado | Campo | Tipo | Descrição | |-------------------|---------|--------------------------------------------------------------------------| | `data` | array | Lista de objetos de **[Bankslip Configuration](#bankslip-configuration)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page` | boolean | Informação que indica se a página recuperada é a última | | `elapsed_time_ms` | number | Tempo de execução da consulta no servidor, em milissegundos | ### Bankslip Configuration | Campo | Tipo | Descrição | |------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------| | `bankslip_configuration_key` | string | Identificador único da configuração de boleto. | | `bankslip_profile` | object | Carteira de cobrança associada (ver **[Bankslip Profile](/documentation/iaas/boletos/recuperar_boletos#bankslip-profile)**). | | `bankslip_issuer_type` | string | Tipo do emissor do boleto (ver **[Tipo de Emissor](#tipo-de-emissor)**). | | `delay` | int | Delay configurado para a emissão dos boletos. | | `our_number_range` | object | Faixa de "nosso número" atribuída à configuração (ver **[Our Number Range](#our-number-range)**). Presente apenas quando a configuração possui uma faixa atribuída. | ### Our Number Range | Campo | Tipo | Descrição | |----------------------------|------|-----------------------------------| | `our_number_range_initial` | int | Início da faixa de "nosso número". | | `our_number_range_final` | int | Fim da faixa de "nosso número". | ## Tipo de Emissor | Enumerador | Descrição | |--------------|------------| | `internal` | Interno | | `manager` | Gestor | | `consultant` | Consultor | --- # Webhooks URL: /documentation/iaas/boletos/webhook Ao longo do ciclo de vida do boleto, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status. Todos os eventos utilizam o tipo `bankslip_collection.bankslip_status_change`. :::info Configuração de webhooks Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao@qitech.com.br](mailto:integracao@qitech.com.br) para configurar. ::: ## Estrutura do webhook Todos os webhooks de boleto seguem a mesma estrutura base: | Campo | Tipo | Descrição | |---|---|---| | `webhook_type` | string | Tipo do webhook. Sempre `bankslip_collection.bankslip_status_change`. | | `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. | | `data` | object | Dados do evento. Veja tabela abaixo. | #### Atributos de `data` | Campo | Tipo | Descrição | |---|---|---| | `bankslip_key` | string (UUID) | Identificador único do boleto. | | `bankslip_configuration_key` | string (UUID) | Identificador da configuração do boleto. | | `bankslip_profile_key` | string (UUID) | Identificador do perfil do boleto. | | `status` | string | Status atual do boleto. | | `fund_class` | object | Dados da classe do fundo associada ao boleto. | | `external_participant_control_number` | string | Número de controle externo do participante. | | `participant_control_number` | string | Número de controle interno do participante. | | `face_value` | float | Valor de face do boleto. | | `due_date` | string | Data de vencimento no formato `YYYY-MM-DD`. | | `borrower` | object | Dados do sacado (devedor). | | `assignor` | object | Dados do cedente. | | `settlement_instructions` | array | Lista de instruções de liquidação vinculadas ao boleto. | | `our_number` | integer | **(Opcional)** Nosso número atribuído pelo banco emissor. | | `our_number_digit` | string | **(Opcional)** Dígito verificador do nosso número. | | `order_number` | string | **(Opcional)** Número do pedido. | | `digitable_line` | string | **(Opcional)** Linha digitável do boleto. Presente quando disponível após o registro. | | `barcode` | string | **(Opcional)** Código de barras do boleto. Presente quando disponível após o registro. | #### Atributos de `fund_class` | Campo | Tipo | Descrição | |---|---|---| | `document_number` | string | CNPJ da classe do fundo. | | `fund_class_key` | string (UUID) | Identificador da classe do fundo. | | `name` | string | Nome da classe do fundo. | #### Atributos de `settlement_instructions` | Campo | Tipo | Descrição | |---|---|---| | `asset_key` | string (UUID) | Identificador do ativo associado. | | `asset_type` | string | Tipo do ativo (ex: `duplicata_mercantil`, `duplicata_servicos`, `ccb`). | | `issue_date` | string | Data de emissão do ativo no formato `YYYY-MM-DD`. | | `maturity_date` | string | Data de vencimento do ativo no formato `YYYY-MM-DD`. | | `face_value` | float | Valor de face do ativo. | | `status` | string | Status da instrução de liquidação. | | `external_id` | string | **(Opcional)** Identificador externo do ativo. | | `installment_number` | integer | **(Opcional)** Número da parcela, quando aplicável (ex: CCBs parceladas). | | `order_number` | string | **(Opcional)** Número do pedido da instrução. | --- ## Eventos por status ### Registro do Boleto STATUS pending_registration Enviado quando um boleto é criado e submetido ao banco emissor para registro. O boleto aguarda a confirmação da instituição bancária. Dependendo do banco, os campos `digitable_line`, `barcode` e `our_number` podem estar presentes quando o banco os retorna imediatamente no ato do registro. Para outros bancos, esses campos são preenchidos somente após a confirmação via arquivo de retorno. ```json title='Webhook Body' { "webhook_type": "bankslip_collection.bankslip_status_change", "webhook_datetime": "2026-04-15T12:55:35Z", "data": { "bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2", "bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c", "bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff", "status": "pending_registration", "fund_class": { "document_number": "17.645.194/0001-85", "fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3", "name": "Nome da Classe do Fundo" }, "external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9", "participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9", "face_value": 629.33, "due_date": "2026-09-17", "borrower": { "document_number": "631.430.668-06", "name": "Nome do Sacado", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Nome do Cedente", "document_number": "37.341.966/0001-00", "person_type": "legal_person" }, "settlement_instructions": [ { "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69", "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22", "asset_type": "duplicata_mercantil", "issue_date": "2025-01-17", "maturity_date": "2026-09-17", "face_value": 629.33, "status": "pending_bankslip_payment" } ], "our_number": 10507, "our_number_digit": "0" } } ``` --- ### Boleto Registrado STATUS registered Enviado quando o banco emissor **confirma o registro** do boleto. A partir deste momento, o boleto está apto para pagamento pelo sacado. Neste webhook, os campos `digitable_line`, `barcode`, `our_number` e `our_number_digit` estarão presentes. ```json title='Webhook Body' { "webhook_type": "bankslip_collection.bankslip_status_change", "webhook_datetime": "2026-04-15T13:10:22Z", "data": { "bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2", "bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c", "bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff", "status": "registered", "fund_class": { "document_number": "17.645.194/0001-85", "fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3", "name": "Nome da Classe do Fundo" }, "external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9", "participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9", "face_value": 629.33, "due_date": "2026-09-17", "borrower": { "document_number": "631.430.668-06", "name": "Nome do Sacado", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Nome do Cedente", "document_number": "37.341.966/0001-00", "person_type": "legal_person" }, "settlement_instructions": [ { "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69", "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22", "asset_type": "duplicata_mercantil", "issue_date": "2025-01-17", "maturity_date": "2026-09-17", "face_value": 629.33, "status": "pending_bankslip_payment" } ], "our_number": 10507, "our_number_digit": "0", "digitable_line": "03399.87654 32100.012345 67890.123456 1 00000000062933", "barcode": "03391000000000629333987654321000123456789012345" } } ``` --- ### Boleto Rejeitado STATUS rejected Enviado quando o banco emissor **rejeita o registro** do boleto. O boleto não estará disponível para pagamento e não avançará no fluxo. As instruções de liquidação vinculadas também são marcadas como `rejected`. ```json title='Webhook Body' { "webhook_type": "bankslip_collection.bankslip_status_change", "webhook_datetime": "2026-04-15T13:10:22Z", "data": { "bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2", "bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c", "bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff", "status": "rejected", "fund_class": { "document_number": "17.645.194/0001-85", "fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3", "name": "Nome da Classe do Fundo" }, "external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9", "participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9", "face_value": 629.33, "due_date": "2026-09-17", "borrower": { "document_number": "631.430.668-06", "name": "Nome do Sacado", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Nome do Cedente", "document_number": "37.341.966/0001-00", "person_type": "legal_person" }, "settlement_instructions": [ { "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69", "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22", "asset_type": "duplicata_mercantil", "issue_date": "2025-01-17", "maturity_date": "2026-09-17", "face_value": 629.33, "status": "rejected" } ], "our_number": 10507, "our_number_digit": "0" } } ``` --- ### Boleto Baixado STATUS written_off Enviado quando o boleto é **baixado** na instituição emissora. Isso pode ocorrer por solicitação de cancelamento. ```json title='Webhook Body' { "webhook_type": "bankslip_collection.bankslip_status_change", "webhook_datetime": "2026-04-15T14:30:00Z", "data": { "bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2", "bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c", "bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff", "status": "written_off", "fund_class": { "document_number": "17.645.194/0001-85", "fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3", "name": "Nome da Classe do Fundo" }, "external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9", "participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9", "face_value": 629.33, "due_date": "2026-09-17", "borrower": { "document_number": "631.430.668-06", "name": "Nome do Sacado", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Nome do Cedente", "document_number": "37.341.966/0001-00", "person_type": "legal_person" }, "settlement_instructions": [ { "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69", "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22", "asset_type": "duplicata_mercantil", "issue_date": "2025-01-17", "maturity_date": "2026-09-17", "face_value": 629.33, "status": "written_off" } ], "our_number": 10507, "our_number_digit": "0", "digitable_line": "03399.87654 32100.012345 67890.123456 1 00000000062933", "barcode": "03391000000000629333987654321000123456789012345" } } ``` --- # Carteira - Aprovação URL: /documentation/iaas/composicao_carteira/aprovar_carteira --- ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/composition/COMPOSITION_KEY MÉTODO PUT ```json title='Request Body' { "new_status":"confirmed" } ``` ### Enumeradores do "new_status" | Enumerador | Descrição | |--------------------------|--------| | `confirmed` | Aprovar a carteira | | `reproved` | Reprovar a carteira | --- # Carteira - Baixar a Carteira URL: /documentation/iaas/composicao_carteira/baixar_carteira ## Introdução Este recurso tem como objetivo baixar, de forma síncrona, um relatório baseado na **Composition**. Os relatórios que são suportados são: - **wallet_composition_by_composition.xlsx** - **xml_401_by_composition.xml** - **xml_5_by_composition.xml** ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/report MÉTODO POST STATUS 201 ```json title='Request Body' { "composition_type": "final_quota | pre_quota", "report_type": "wallet_composition_by_composition | xml_401_by_composition | xml_5_by_composition", "reference_date": "2025-01-20" } ``` ### Response ```json title='Response Body' { "document_b64": "BASE64" } ``` :::warning Atenção Para baixar a carteira, ela deve estar no status final **confirmed (Confirmada)**, caso contrário a resposta será um **400**. ::: --- # Introdução URL: /documentation/iaas/composicao_carteira/inicio Nesta seção iremos explicar como funciona o consumo da Carteira por meio de APIs. Todos os dias as carteiras de todos os Fundos de Investimento dos Fundos administrados pela QI CTVM são disponibilizadas por essa API, com as informações que compõe a cota daquele determinado dia. Durante o processamento do fechamento do Fundo, e consequentemente de disponibilização da sua carteira, geramos uma primeira carteira, chamada de **Carteira de Validação**, e uma vez que esta é aprovada, seguimos para a disponibilização da **Carteira Final**. A principal diferença entre ambas as carteiras é que a de validação é gerada anterior ao processamento do passivo, isso inclui amortizações, aplicações e resgates, enquanto a final, já sensibiliza essas movimentações. Informações dos ativos, despesas, conciliações, e caixa, são sempre idênticas entre as duas carteiras. De forma prática o que muda, é que eventuais "A Pagar" de Resgates a Cotizar, ou "A Receber" de Aplicações Financeiras a Cotizar, são cotizados e sensibilizam o número de Cotas das Séries de Emissão, sem alterar portanto a Cota Divulgada. :::warning É muito importante que quaisquer criticas, ou validações sejam feitos em cima da **Carteira de Validação** antes da sua aprovação, pois uma vez que esta é aprovada, o sistema segue para o processamento do passivo e consequentemente para a disponibilização da carteira final. Nesta etapa, como já houve o processamento do passivo, eventuais resgates e amortizações já podem ter sido até liquidados. ::: Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox), quanto em ambiente produtivo. --- # Carteira - Recuperação da Carteira URL: /documentation/iaas/composicao_carteira/recuperar_carteira --- ## Lista de Carteiras ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/compositions MÉTODO GET ### Query Params | Parâmetro | Descrição | |------------------|-----------------------------------------------------------------------------------------------------| | `not_status` | Filtra os resultados excluindo composições que esteja no status informado. | | `status` | Filtra os resultados trazendo apenas composições que esteja no status informado. | | `reference_date` | Data de referência para a consulta das composições. Deve estar no formato `YYYY-MM-DD`. | | `type` | Tipo da composição a ser filtrada pre_quota/final_quota. | | `start_date` | Data inicial do intervalo de busca. Obrigatório se `end_date` for informado. Formato: `YYYY-MM-DD`. | | `end_date` | Data final do intervalo de busca. Obrigatório se `start_date` for informado. Formato: `YYYY-MM-DD`. | :::warning Atenção Existem duas formas de filtrar por data: - Consumindo uma data em específico , enviando como *query param* o campo *reference_date* . - Consumindo um período , enviando como *query param* os campos *start_date* e *end_date* ::: ```json title='Response Body' { "data": [ { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "status": "confirmed", "composition_type": "pre_quota", "composition_date": "2024-11-13", "fund_class": { "name": "A SAMPLE CLASS", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "document_number": "18.687.469/0001-06" } }, { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "status": "confirmed", "composition_type": "final_quota", "composition_date": "2024-11-13", "fund_class": { "name": "A SAMPLE CLASS", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "document_number": "18.687.469/0001-06" } } ], "limit": 50, "page": 0, "is_last_page": true } ``` ### Objeto Paginado | Campo | Tipo | Descrição | |---------------|--------|----------------------------------------------------------------| | `data` | array | Lista de objetos de **[Composition](#composition)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última | ### Composition | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------| | `composition_key` | string | Chave única de identificação da carteira | | `status` | string | O status daquela carteira | | `composition_type` | string | O tipo daquela carteira, pre_quota/final_quota | | `composition_date` | string | Data de referência da carteira | | `fund_class` | object | Objeto de **[Fund Class](#fund_class)** | ### Fund Class {#fund_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da classe de fundo | até 255 | | `fund_class_key` | string | Chave única de identificação da classe de fundo | 36 | | `document_number` | string | CNPJ da classe de fundo | - | --- ## Informações da Carteira ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/composition/COMPOSITION_KEY MÉTODO GET ```json title='Response Body' { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "status": "confirmed", "composition_type": "pre_quota", "composition_date": "2024-12-02", "fund_class": { "name": "A SAMPLE CLASS", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "document_number": "18.687.469/0001-06" }, "issuance_series": [ { "issuance_serie_key": "840e01e9-0df8-4719-83c4-f10b839d8384", "name": "SUBORDINADA - 1", "gross_net_worth": 1891397.29, "net_net_worth": 1891397.29, "gross_quota_value": 1.76821576, "net_quota_value": 1.76821576, "number_of_quotas": 1069664.309518427, "applied_value": 0.0, "applied_quotas": 0.0, "redeemed_value": 0.0, "redeemed_quotas": 0.0, "amortized_value": 0.0, "tax_anticipated_value": 0.0, "tax_anticipated_quotas": 0.0, "profitabilities": [ { "reference_date": "2024-11-29", "quota_value": 1.76065188, "di_benchmark_quota_value": 1.7613906, "quota_percentage": 100.43, "di_benchmark_percentage": 100.43, "type": "monthly" }, { "reference_date": "2024-11-25", "quota_value": 1.7568068, "di_benchmark_quota_value": 1.76049545, "quota_percentage": 99.79, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-11-01", "quota_value": 1.74121452, "di_benchmark_quota_value": 1.75502225, "quota_percentage": 99.21, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-10-03", "quota_value": 1.72167143, "di_benchmark_quota_value": 1.75002091, "quota_percentage": 98.38, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-09-03", "quota_value": 1.70128747, "di_benchmark_quota_value": 1.74445962, "quota_percentage": 97.52, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2024-06-05", "quota_value": 1.63380383, "di_benchmark_quota_value": 1.7178922, "quota_percentage": 95.1, "di_benchmark_percentage": 100.0, "type": "monthly" }, { "reference_date": "2023-12-08", "quota_value": 1.52421994, "di_benchmark_quota_value": 1.68553599, "quota_percentage": 90.43, "di_benchmark_percentage": 100.0, "type": "daily" } ] } ], "assets": [ { "asset_key": "34f42521-f27f-424a-958f-8b53f15cc80d", "asset_type": "fixed_income_fund_quota", "purchase_date": "2024-11-27", "total_purchase_value": 1009320, "bad_debt_percentage": 0, "bad_debt_value": 0, "overdue_accounting_value": 0, "current_accounting_value": 1234335, "current_fair_accounting_value": 1234335 } ], "consolidated_assets": [ { "asset_type": "ccb", "asset_category": "credit", "total_units": 175623, "bad_debt_value": 0, "overdue_accounting_value": 75642, "current_accounting_value": 187762590, "current_fair_accounting_value": 187762590, "post_maturity_interest_value": 0, "delay_interest_value": 0, "delay_fine_value": 0 } ], "receivables": [ { "origin_key": "a60f9226-edac-488e-9a58-6205a334e6ba", "origin_type": "expense", "description": "Taxa CVM - 2024", "total_value": 711515, "recognized_value": 654125, "start_date": "2024-01-09", "end_date": "2024-12-31", "payment_date": "2024-05-10" } ], "payables": [ { "origin_key": "19b83b17-d36c-4edd-97fe-99af6a0a4a63", "origin_type": "expense", "description": "Taxa de Gestão - 2024/12", "total_value": 14586, "recognized_value": 14586, "start_date": "2024-12-02", "end_date": "2024-12-31", "payment_date": "2025-01-08" }, ], "cash_accounts": [ { "account_key": "a41e4fa8-6950-485e-9a5b-70f21cc6774a", "balance": 100000, "unconcilied_cash_in": 0, "unconcilied_cash_out": 0, "account_branch": "0001", "account_digit": "1", "account_number": "372832", "accounting_identification": 1, "financial_institution": { "code": "329", "ispb": "32402502", "name": "QI Sociedade de Crédito Direto" } } ] } ``` ### Composition Completo | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------------------| | `composition_key` | string | Chave única de identificação da carteira | | `status` | string | O status daquela carteira | | `composition_type` | string | O tipo daquela carteira, pre_quota/final_quota | | `composition_date` | string | Data de referência da carteira | | `fund_class` | object | Objeto de **[Fund Class](#fund_class)** | | `issuance_series` | array | Lista de objetos de **[Issuance Series](#issuance_serie)** | | `assets` | array | Lista de objetos de **[Assets](#composition)** | | `consolidated_assets` | array | Lista de objetos de **[Consolidated Assets](#composition)** | | `receivables` | array | Lista de objetos de **[Receivables](#composition)** | | `payables` | array | Lista de objetos de **[Paybles](#composition)** | | `cash_accounts` | array | Lista de objetos de **[Cash Accounts](#composition)** | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------------------| | `issuance_serie_key` | string | Chave única de identificação da série de emissão | | `name` | string | O nome daquela série | | `gross_net_worth` | float | O PL Bruto daquela série | | `net_net_worth` | float | O PL Líquido daquela série | | `gross_quota_value` | float | Valor da Cota Bruta | | `net_quota_value` | float | Valor da Cota Líquida | | `number_of_quotas` | float | Número Total de Cotas | | `applied_value` | float | Valor total aplicado no período (opcional) | | `applied_quotas` | float | Quantidade de cotas aplicadas no período (opcional) | | `redeemed_value` | float | Valor total resgatado no período (opcional) | | `redeemed_quotas` | float | Quantidade de cotas resgatadas no período (opcional) | | `amortized_value` | float | Valor total amortizado no período (opcional) | | `tax_anticipated_value` | float | Valor do imposto antecipado (opcional) | | `tax_anticipated_quotas` | float | Quantidade de cotas do imposto antecipado (opcional) | | `isin_code` | string | Código ISIN da série (opcional) | | `profitabilities` | array | Lista de objetos de **[Profitability](#profitability)** | ### Profitability | Campo | Tipo | Descrição | |-----------------------------|--------|----------------------------------------------------------------------| | `reference_date` | string | Data de Referência no qual a performance é analisada | | `quota_value` | float | O valor da Cota da Série na Data de Referência | | `di_benchmark_quota_value` | float | O valor da Cota hoje caso a Cota de referência rodasse a 100% do DI | | `quota_percentage` | float | Rentabilidade acumulada da cota no período (%) | | `di_benchmark_percentage` | float | Rentabilidade acumulada do benchmark DI no período (%) | | `type` | string | Tipo do período de rentabilidade | ### Assets | Campo | Tipo | Descrição | |---------------------------------|---------|-------------------------------------------------------| | `asset_key` | string | Chave única de identificação do ativo | | `asset_type` | string | O Tipo do ativo | | `purchase_date` | string | Data de Aquisição do ativo | | `total_purchase_value` | string | Valor Total de Aquisição do Ativo | | `bad_debt_percentage` | string | % de PDD aplicado | | `bad_debt_value` | integer | Valor total de PDD considerado - Inteiro em centavos | | `overdue_accounting_value` | integer | Valor vencido do Ativo - Inteiro em centavos | | `current_accounting_value` | integer | Valor total do Ativo - Inteiro em centavos | | `current_fair_accounting_value` | integer | Valor total do Ativo - Inteiro em centavos | ### Consolidated Assets | Campo | Tipo | Descrição | |---------------------------------|---------|----------------------------------------------------------------------| | `asset_type` | string | O Tipo do ativo | | `asset_category` | string | A categoria do ativo | | `total_units` | integer | O número total de Ativos consolidados desse tipo | | `bad_debt_value` | integer | Valor total de PDD considerado - Inteiro em centavos | | `overdue_accounting_value` | integer | Valor vencido do Ativo - Inteiro em centavos | | `current_accounting_value` | integer | Valor total do Ativo - Inteiro em centavos | | `current_fair_accounting_value` | integer | Valor justo total do Ativo - Inteiro em centavos | | `post_maturity_interest_value` | integer | Juros pós-vencimento - Inteiro em centavos | | `delay_interest_value` | integer | Juros de mora - Inteiro em centavos | | `delay_fine_value` | integer | Multa por atraso - Inteiro em centavos | ### Receivables | Campo | Tipo | Descrição | |-----------------------------|--------|----------------------------------------------------------------------| | `origin_key` | string | Chave única de identificação do recurso que origina esse A Receber | | `origin_type` | string | O Tipo do recurso que origina esse A Receber | | `description` | string | Descrição do item | | `total_value` | float | O valor Total A Receber | | `recognized_value` | float | O valor que já foi apropriado | | `start_date` | string | A data de início de apropriação | | `end_date` | string | O data de fim da apropriação | | `payment_date` | string | A data de Liquidação | ### Payables | Campo | Tipo | Descrição | |-----------------------------|--------|----------------------------------------------------------------------| | `origin_key` | string | Chave única de identificação do recurso que origina esse A Pagar | | `origin_type` | string | O Tipo do recurso que origina esse A Pagar | | `description` | string | Descrição do item | | `total_value` | float | O valor Total A Pagar | | `recognized_value` | float | O valor que já foi apropriado | | `start_date` | string | A data de início de apropriação | | `end_date` | string | O data de fim da apropriação | | `payment_date` | string | A data de Liquidação | ### Cash Accounts | Campo | Tipo | Descrição | |-----------------------------|---------|-------------------------------------------------------------------| | `account_key` | string | Chave única de identificação da conta | | `balance` | integer | O saldo da conta - Inteiro em centavos | | `unconcilied_cash_in` | integer | O valor de Entradas A Conciliar nessa conta - Inteiro em centavos | | `unconcilied_cash_out` | integer | O valor de Saídas A Conciliar nessa conta - Inteiro em centavos | | `account_branch` | string | A Agência da conta | | `account_digit` | string | O Dígito da conta | | `account_number` | string | O número da conta | | `accounting_identification` | integer | O identificador contábil daquela conta | | `financial_institution` | object | Objetos de **[Financial Institution](#financial_institution)** | | `account_data` | object | Objeto com os dados da conta (contém os mesmos campos acima) | ### Financial Institution {#financial_institution} | Campo | Tipo | Descrição | |-----------------------------|--------|-----------------------| | `code` | string | Código COMPE da IF | | `ispb` | string | O ISPB da IF | | `name` | string | O nome da IF | --- # Consulta de Aplicações Financeiras por Classe de Fundo URL: /documentation/iaas/cotas_de_fundo/consulta_paginada_aplicacoes_financeiras :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de **Gestor**. ::: ### Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_applications MÉTODO GET #### Query Params | Parâmetro | Tipo | Descrição | | ---------------------------------- | ------ | --------------------------------------------- | | `quotation_date` | data | Data de cotização da aplicação | | `financial_application_status` | string | Filtra as aplicações por um status específico | | `not_financial_application_status` | string | Exclui as aplicações com um status específico | | `document_number` | string | CNPJ da classe do fundo investido | ### Response STATUS 200 Caso 01: Retorno com uma aplicação ```json { "data": [ { "amount": 0.00, "financial_application_key": "UUID", "asset_key": "UUID", "quotation_date": "YYYY-MM-DD", "status": "confirmed", "issuance_serie": { "issuance_serie_key": "UUID", "name": "Invested Issuance Serie Name", "subclass_name": "Invested Sub Class Name", "serie": 1, "quota_calculation_method": "quota_value", "internal_code": "Internal Code", "fund_class_name": "Invested Fund Class Name", "fund_class_short_name": "Invested Fund Class short name", "fund_class_document_number": "00.000.000/0000-00", "minimum_share_capital": 0.0, "investment_category": "multi_market", "payment_type": "transfer", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "YYYY-MM-DD", "administrator": { "administrator_key": "UUID", "name": "Administrator Name", "document_number": "00.000.000/0000-00" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "amortization_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "isin_code": "BR000000000" }, "fund_class": { "fund_class_key": "UUID", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "YYYY-MM-DD", "distributor": { "name": "Distributor Name", "distributor_key": "UUID", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "UUID", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Page | Campo | Tipo | Descrição | |---------------|--------|------------------------------------------------------------------------------| | `data` | array | Lista de objetos de **[Financial Application](#financial_application)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última | ### Financial Application {#financial_application} | Campo | Tipo | Descrição | | ------------------------------------ | ------ | ----------------------------------------------- | | amount | float | Valor aplicado | | financial_application_key | string | Chave única da aplicação financeira | | asset_key | string | Chave do ativo relacionado | | quotation_date | string | Data de cotização (YYYY-MM-DD) | | status | string | Status da aplicação | | external_financial_application_key | string | Identificador externo da aplicação financeira | | issuance_serie | JSON | Objeto de **[Issuance Serie](#issuance-serie)** | | fund_class | JSON | Objeto de **[Fund Class](#fund-class)** | ### Issuance Serie | Campo | Tipo | Descrição | | ----------------------------- | ------ | ----------------------------------------------------- | | issuance_serie_key | string | Chave única da série de emissão | | name | string | Nome da série de emissão | | subclass_name | string | Nome da subclasse (ex: SUBORDINADA) | | serie | int | Número da série | | quota_calculation_method | string | Método de cálculo da cota (ex: quota_value) | | internal_code | string | Código interno da série | | fund_class_name | string | Nome da classe do fundo associado à série | | fund_class_short_name | string | Nome curto da classe do fundo | | fund_class_document_number | string | CNPJ da classe do fundo | | minimum_share_capital | float | Valor mínimo para aplicação | | investment_category | string | Categoria do investimento (ex: multi_market) | | payment_type | string | Tipo de pagamento (ex: transfer) | | account_data | JSON | Objeto de **[Account Data](#account-data)** | | last_updated_date | string | Última data de atualização (YYYY-MM-DD) | | administrator | JSON | Objeto de **[Administrator](#administrator)** | | operation_periods | JSON | Objeto de **[Operation Periods](#operation-periods)** | | isin_code | string | Código ISIN da série | ### Administrator | Campo | Tipo | Descrição | | ------------------ | ------ | ---------------------------- | | administrator_key | string | Chave única do administrador | | name | string | Nome do administrador | | document_number | string | CNPJ do administrador | ### Operation Periods | Campo | Tipo | Descrição | | ---------------------- | ---- | -------------------------------------------------------------------------------------- | | redemption_request | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** para resgates| | amortization_request | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** amortizações | | financial_application | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** aplicações | ### Quotation and Payment | Campo | Tipo | Descrição | | -------------- | ------ | ------------------------------------------------ | | days | int | Quantidade de dias | | type | string | Tipo de contagem (ex: fixed, until) | | calendar_base | string | Base de calendário (ex: workdays, calendar_365) | ### Account Data | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------------------- | | account_digit | string | Dígito da conta bancária | | account_branch | string | Número da agência bancária | | account_number | string | Número da conta bancária | | financial_institution_code | string | Código da instituição financeira | | financial_institution_ispb | string | ISPB da instituição financeira (Sistema de Pagamentos Brasileiro) | ### Fund Class | Campo | Tipo | Descrição | | ---------------- | ------ | ----------------------------------------- | | fund_class_key | string | Chave única da classe de fundo | | name | string | Nome completo da classe de fundo | | short_name | string | Nome curto da classe de fundo | | document_number | string | CNPJ da classe de fundo | | accounting_date | string | Data contábil mais recente | | distributor | JSON | Objeto de **[Distributor](#distributor)** | | manager | JSON | Objeto de **[Manager](#manager)** | ### Distributor | Campo | Tipo | Descrição | | ---------------- | ------ | --------------------------- | | name | string | Nome do distribuidor | | distributor_key | string | Chave única do distribuidor | | document_number | string | CNPJ do distribuidor | ### Manager | Campo | Tipo | Descrição | | ---------------- | ------ | --------------------------------- | | manager_key | string | Chave única do gestor | | manager_name | string | Nome do gestor da classe de fundo | | document_number | string | CNPJ do gestor | --- # Consulta de Resgates por Classe de Fundo URL: /documentation/iaas/cotas_de_fundo/consulta_paginada_resgates :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de Gestor. ::: ### Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_requests MÉTODO GET #### Query Params | Parâmetro | Tipo | Descrição | | ------------------------------- | ------ | ------------------------------------------- | | `quotation_date` | data | Data de cotização do resgate | | `redemption_request_status` | string | Filtra os resgates por um status específico | | `not_redemption_request_status` | string | Exclui os resgates com um status específico | | `document_number` | string | CNPJ da classe do fundo investido | ### Response STATUS 200 Caso 01: Retorno com um resgate ```json { "data": [ { "redemption_request_key": "UUID", "status": "confirmed", "quotation_date": "YYYY-MM-DD", "payment_date": "YYYY-MM-DD", "amount": 0.00, "issuance_serie": { "issuance_serie_key": "UUID", "name": "Issuance Serie Name", "subclass_name": "SUBORDINADA", "serie": 1, "quota_calculation_method": "quota_value", "internal_code": "Internal Code", "fund_class_name": "Fund Class Name", "fund_class_short_name": "Fund Class Short Name", "fund_class_document_number": "00.000.000/0000-00", "minimum_share_capital": 0.0, "investment_category": "fixed_income", "payment_type": "automatic_debit", "financial_institution_code": "341", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "YYYY-MM-DD", "administrator": { "administrator_key": "UUID", "name": "Administrator Name", "document_number": "00.000.000/0000-00" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "amortization_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "issuance_serie_data": { "name": "Issuance Serie Name", "serie": 1, "payment_type": "automatic_debit", "remuneration": "residual", "internal_code": "Internal Code", "subclass_name": "SUBORDINADA", "fund_class_name": "Fund Class Name", "issuance_serie_key": "UUID", "tax_classification": "long_term", "investment_category": "fixed_income", "fund_class_short_name": "Fund Class Short Name", "minimum_share_capital": 0.00, "quota_calculation_method": "quota_value", "financial_institution_code": "329", "fund_class_document_number": "00.000.000/0000-00", "administrator_document_number": "00.000.000/0000-00" } }, "fund_class": { "fund_class_key": "UUID", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "YYYY-MM-DD", "distributor": { "name": "Distributor Name", "distributor_key": "UUID", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "UUID", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Page | Campo | Tipo | Descrição | | -------------- | ------- | ----------------------------------------------------------------- | | `data` | array | Lista de objetos de **[Redemption Request](#redemption-request)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page` | boolean | Informação que indica se a página recuperada é a última | ### Redemption Request | Campo | Tipo | Descrição | | ---------------------------------- | ------ | ----------------------------------------------- | | redemption_request_key | string | Chave única do pedido de resgate | | external_redemption_request_key | string | Chave externa de controle (opcional) | | status | string | Status do resgate (ex: confirmed) | | quotation_date | string | Data da cotização do resgate | | payment_date | string | Data do pagamento do resgate | | amount | float | Valor resgatado | | issuance_serie | JSON | Objeto de **[Issuance Serie](#issuance-serie)** | | fund_class | JSON | Objeto de **[Fund Class](#fund-class)** | ### Issuance Serie | Campo | Tipo | Descrição | | ----------------------------- | ------ | ----------------------------------------------------- | | issuance_serie_key | string | Chave única da série de emissão | | name | string | Nome da série de emissão | | subclass_name | string | Nome da subclasse (ex: SUBORDINADA) | | serie | int | Número da série | | quota_calculation_method | string | Método de cálculo da cota (ex: quota_value) | | internal_code | string | Código interno da série | | fund_class_name | string | Nome da classe do fundo associado à série | | fund_class_short_name | string | Nome curto da classe do fundo | | fund_class_document_number | string | CNPJ da classe do fundo | | minimum_share_capital | float | Valor mínimo para aplicação | | investment_category | string | Categoria do investimento (ex: multi_market) | | payment_type | string | Tipo de pagamento (ex: transfer) | | account_data | JSON | Objeto de **[Account Data](#account-data)** | | last_updated_date | string | Última data de atualização (YYYY-MM-DD) | | administrator | JSON | Objeto de **[Administrator](#administrator)** | | operation_periods | JSON | Objeto de **[Operation Periods](#operation-periods)** | | isin_code | string | Código ISIN da série | ### Administrator | Campo | Tipo | Descrição | | ------------------ | ------ | ---------------------------- | | administrator_key | string | Chave única do administrador | | name | string | Nome do administrador | | document_number | string | CNPJ do administrador | ### Operation Periods | Campo | Tipo | Descrição | | ---------------------- | ---- | -------------------------------------------------------------------------------------- | | redemption_request | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** para resgates| | amortization_request | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** amortizações | | financial_application | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** aplicações | ### Quotation and Payment | Campo | Tipo | Descrição | | -------------- | ------ | ------------------------------------------------ | | days | int | Quantidade de dias | | type | string | Tipo de contagem (ex: fixed, until) | | calendar_base | string | Base de calendário (ex: workdays, calendar_365) | ### Account Data | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------------------- | | account_digit | string | Dígito da conta bancária | | account_branch | string | Número da agência bancária | | account_number | string | Número da conta bancária | | financial_institution_code | string | Código da instituição financeira | | financial_institution_ispb | string | ISPB da instituição financeira (Sistema de Pagamentos Brasileiro) | ### Fund Class | Campo | Tipo | Descrição | | ---------------- | ------ | ----------------------------------------- | | fund_class_key | string | Chave única da classe de fundo | | name | string | Nome completo da classe de fundo | | short_name | string | Nome curto da classe de fundo | | document_number | string | CNPJ da classe de fundo | | accounting_date | string | Data contábil mais recente | | distributor | JSON | Objeto de **[Distributor](#distributor)** | | manager | JSON | Objeto de **[Manager](#manager)** | ### Distributor | Campo | Tipo | Descrição | | ---------------- | ------ | --------------------------- | | name | string | Nome do distribuidor | | distributor_key | string | Chave única do distribuidor | | document_number | string | CNPJ do distribuidor | ### Manager | Campo | Tipo | Descrição | | ---------------- | ------ | --------------------------------- | | manager_key | string | Chave única do gestor | | manager_name | string | Nome do gestor da classe de fundo | | document_number | string | CNPJ do gestor | --- # Consulta de Séries de Emissão URL: /documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de **Gestor**. ::: ### Request ENDPOINT /trade_fund_quota/issuance_series MÉTODO GET #### Query Params | Parâmetro | Tipo | Descrição | | ---------------------------- | ------ | ---------------------------------- | | `fund_class_document_number` | string | CNPJ do fundo (00.000.000/0001-00) | ### Response STATUS 200 Caso 01: Retorno com uma série ```json { "data": [ { "issuance_serie_key": "UUID", "name": "Invested Issuance Serie Name", "subclass_name": "Invested Sub Class Name", "serie": 1, "quota_calculation_method": "quota_value", "internal_code": "Internal Code", "fund_class_name": "Invested Fund Class Name", "fund_class_short_name": "Invested Fund Class short name", "fund_class_document_number": "00.000.000/0000-00", "minimum_share_capital": 0.0, "investment_category": "multi_market", "payment_type": "transfer", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "YYYY-MM-DD", "administrator": { "administrator_key": "UUID", "name": "Administrator Name", "document_number": "00.000.000/0000-00" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "amortization_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "isin_code": "BR000000000" } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Page | Campo | Tipo | Descrição | |---------------|--------|------------------------------------------------------------------------------| | `data` | array | Lista de objetos de **[Issuance Serie](#issuance_serie)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | | ----------------------------- | ------ | ----------------------------------------------------- | | issuance_serie_key | string | Chave única da série de emissão | | name | string | Nome da série de emissão | | subclass_name | string | Nome da subclasse (ex: SUBORDINADA) | | serie | int | Número da série | | quota_calculation_method | string | Método de cálculo da cota (ex: quota_value) | | internal_code | string | Código interno da série | | fund_class_name | string | Nome da classe do fundo associado à série | | fund_class_short_name | string | Nome curto da classe do fundo | | fund_class_document_number | string | CNPJ da classe do fundo | | minimum_share_capital | float | Valor mínimo para aplicação | | investment_category | string | Categoria do investimento (ex: multi_market) | | payment_type | string | Tipo de pagamento (ex: transfer) | | account_data | JSON | Objeto de **[Account Data](#account-data)** | | last_updated_date | string | Última data de atualização (YYYY-MM-DD) | | administrator | JSON | Objeto de **[Administrator](#administrator)** | | operation_periods | JSON | Objeto de **[Operation Periods](#operation-periods)** | | isin_code | string | Código ISIN da série | ### Administrator | Campo | Tipo | Descrição | | ------------------ | ------ | ---------------------------- | | administrator_key | string | Chave única do administrador | | name | string | Nome do administrador | | document_number | string | CNPJ do administrador | ### Operation Periods | Campo | Tipo | Descrição | | ---------------------- | ---- | -------------------------------------------------------------------------------------- | | redemption_request | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** para resgates| | amortization_request | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** amortizações | | financial_application | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** aplicações | ### Quotation and Payment | Campo | Tipo | Descrição | | -------------- | ------ | ------------------------------------------------ | | days | int | Quantidade de dias | | type | string | Tipo de contagem (ex: fixed, until) | | calendar_base | string | Base de calendário (ex: workdays, calendar_365) | ### Account Data | Campo | Tipo | Descrição | | ---------------------------- | ------ | ----------------------------------------------------------------- | | account_digit | string | Dígito da conta bancária | | account_branch | string | Número da agência bancária | | account_number | string | Número da conta bancária | | financial_institution_code | string | Código da instituição financeira | | financial_institution_ispb | string | ISPB da instituição financeira (Sistema de Pagamentos Brasileiro) | --- # Consulta de Posições em Cotas de Fundo URL: /documentation/iaas/cotas_de_fundo/consulta_posicoes_cotas_de_fundo --- :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de **Gestor**. ::: Retorna, para cada fundo investido, **quanto o seu fundo tem aplicado**: o valor atualizado da posição em reais, a quantidade de cotas e a data da última marcação. Diferente da consulta de aplicações financeiras, que lista operação por operação, aqui a resposta já vem consolidada por série de emissão do fundo investido. É a consulta indicada para saber o saldo aplicado em um **fundo de zeragem** — veja [Consultando a posição em um fundo de zeragem](#fundo-de-zeragem). ### Request ENDPOINT /wallet/fund_class/FUND_CLASS_KEY/fund_quota_positions MÉTODO GET Onde `FUND_CLASS_KEY` é a chave da **sua** classe de fundo, aquela que detém as cotas. #### Query Params | Parâmetro | Tipo | Descrição | Obrigatório | | --------------------- | ------ | ------------------------------------------------------------------------------------------- | ----------- | | `page` | int | Número da página. Começa em `0`. Padrão: `0`. | Não | | `limit` | int | Quantidade de registros por página. Máximo: `50`. Padrão: `10`. | Não | | `document_number` | string | CNPJ da classe do fundo investido, com pontuação. Correspondência exata. | Não | | `internal_code` | string | Código interno da série investida. Correspondência parcial. | Não | | `internal_codes` | lista | Lista de códigos internos. Correspondência exata. | Não | | `fund_class_name` | string | Nome da classe do fundo investido. Correspondência parcial. | Não | | `subclass_name` | lista | Senioridade da subclasse investida: `senior`, `mezzanine`, `subordinate`. | Não | | `investment_category` | lista | Categoria do fundo investido: `fidc`, `fiagro`, `multi_market`, `fixed_income`, `private_equity`, `equity`, `real_state`. | Não | | `asset_types` | lista | Tipo do ativo: `fidc_fund_quota`, `fiagro_fund_quota`, `multi_market_fund_quota`, `fixed_income_fund_quota`, `private_equity_fund_quota`. | Não | ```python title="Exemplo de chamada" GET /wallet/fund_class/{fund_class_key}/fund_quota_positions?document_number=64.289.387/0001-20 ``` :::note **Atenção** Somente posições em ativos **ativos** entram no resultado. Cotas totalmente resgatadas ou baixadas não aparecem. ::: ### Response STATUS 200 ```json title='Response Body' { "data": [ { "quota_fund_class": { "name": "Série Única", "quota_fund_class_key": "UUID", "document_number": "00.000.000/0000-00", "fund_class_name": "Invested Fund Class Name", "fund_class_short_name": "Invested Fund Class Short Name", "investment_category": "fixed_income", "tax_classification": "long_term", "internal_code": "Internal Code", "subclass_name": "senior", "entity_category": "fund", "fund_term_target": "undetermined", "fund_regime": "open_ended", "operation_periods": { "redemption_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "isin_code": "BR000000000" }, "total_current_value": 1234567.89, "total_current_units": 1180000.0, "last_mtm_date": "YYYY-MM-DD", "lag": { "reference": "daily", "amount": 1 } } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Response Fields | Campo | Tipo | Descrição | | -------------- | ------- | ---------------------------------------------------------------- | | `data` | array | Lista de objetos de **[Posição](#posicao)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page` | boolean | Indica se a página recuperada é a última | ### Posição {#posicao} | Campo | Tipo | Descrição | | --------------------- | ------ | ------------------------------------------------------------------------------------------------ | | `quota_fund_class` | JSON | Objeto de **[Fundo investido](#fundo-investido)** | | `total_current_value` | float | **Valor atualizado da posição, em reais.** Soma do valor corrente dos ativos da série | | `total_current_units` | float | Quantidade atual de cotas detidas na série | | `last_mtm_date` | string | Data da marcação **mais antiga** entre as posições agregadas, no formato `YYYY-MM-DD` | | `lag` | JSON | Configuração de defasagem de precificação da série. Omitido quando a série não tem defasagem | :::caution **Atenção** Diferente da API de Visibilidade de Caixa, onde os saldos vêm em centavos, aqui `total_current_value` é um número decimal em reais. Ex.: `1234.56` = R$ 1.234,56. O `last_mtm_date` é o **mínimo** entre as datas de marcação das posições agregadas, e não a mais recente. Use-o para saber até quando o valor está garantidamente atualizado. ::: ### Fundo investido {#fundo-investido} | Campo | Tipo | Descrição | | ------------------------ | ------ | ------------------------------------------------------------------------ | | `name` | string | Nome da série de emissão investida | | `quota_fund_class_key` | string | Chave única da série de emissão investida | | `document_number` | string | CNPJ da classe do fundo investido | | `fund_class_name` | string | Nome da classe do fundo investido | | `fund_class_short_name` | string | Nome curto da classe do fundo investido | | `investment_category` | string | Categoria de investimento do fundo investido | | `tax_classification` | string | Classificação tributária do fundo investido | | `internal_code` | string | Código interno da série investida | | `subclass_name` | string | Senioridade da subclasse investida | | `entity_category` | string | Categoria da entidade investida | | `fund_term_target` | string | Prazo alvo do fundo investido | | `fund_regime` | string | Regime do fundo investido | | `operation_periods` | JSON | Prazos de cotização e liquidação das operações da série | | `isin_code` | string | Código ISIN da série. Omitido quando a série não tem ISIN cadastrado | ## Consultando a posição em um fundo de zeragem {#fundo-de-zeragem} Fundos de zeragem são fundos de liquidez usados para aplicar o caixa ocioso da sua classe, com aplicação e resgate por débito automático. A operação é feita pelos endpoints de [Criar Aplicação Financeira](/documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras) e [Criar Pedido de Resgate](/documentation/iaas/cotas_de_fundo/operacao_resgates), enviando o `source_account_key`. Para consultar quanto a sua classe tem aplicado em um fundo de zeragem específico, filtre pelo CNPJ dele: ```python title="Posição no QI Cash III" GET /wallet/fund_class/{fund_class_key}/fund_quota_positions?document_number=64.289.387/0001-20 ``` O `total_current_value` da resposta é o saldo aplicado, em reais, na data indicada por `last_mtm_date`. :::note **Atenção** Uma mesma classe de fundo investida pode ter mais de uma série de emissão. Nesse caso a resposta traz **uma linha por série**, todas com o mesmo `document_number`, e o saldo total no fundo é a soma dos `total_current_value` retornados. ::: Para conhecer o saldo em **conta bancária** — que é o caixa ainda não aplicado — use os endpoints de [Visibilidade de Caixa](/documentation/iaas/visibildade_de_caixa/get_accounts). ## Possíveis erros STATUS 404 **Classe de fundo não encontrada** ```json { "title": " Fund Class not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "A Fund Class com chave {fund_class_key} não foi encontrado.", "code": "WLT000001" } ``` **Gestor não encontrado** ```json { "title": "Not Found Manager", "description": "Manager with the key {manager_key} was not found.", "translation": "O gestor com a chave {manager_key} não foi encontrado.", "code": "WLT000066" } ``` STATUS 403 **Classe de fundo não pertence ao gestor da integração** ```json { "title": "Forbidden Agent", "description": "The agent with agent key ({agent_key}) can't access this resource.", "translation": "O agente com chave ({agent_key}) não pode acessar esse recurso.", "code": "WLT000098" } ``` --- # Introdução URL: /documentation/iaas/cotas_de_fundo/inicio O sistema de Cotas de Fundo é uma solução que permite a compra, venda e consulta relacionado a cotas de outros fundos. Este módulo oferece funcionalidades essenciais para: - Gerenciar aportes e resgates em outros fundos - Criar operações Esta documentação fornece uma visão detalhada sobre como utilizar o sistema de cotas de fundo, incluindo seus principais recursos e fluxos. Aqui você encontrará informações sobre: - Compra, venda e consulta relacionadas a cotas de outros fundos - Endpoints e payloads Para começar a utilizar o sistema, navegue pelos tópicos disponíveis nesta documentação para entender melhor cada aspecto do módulo de cotas de fundo. --- # Criar Aplicação Financeira URL: /documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras --- :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de Gestor. ::: ### Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_application MÉTODO POST STATUS 201 ```json title='Request Body' { "issuance_serie_key": "UUID", "source_account_key": "UUID", "amount": 0.00, "quotation_date": "YYYY-MM-DD", "payment_method": "string" } ``` :::note **Atenção**. Sempre que a operação for em uma série que o "payment_type" é "automatic_debit" (normalmente fundos de zeragem) é preciso enviar o source_account_key. Esta operação não resultará em uma aplicação de fato, apenas na criação das expectativas e transferência para a conta de sua titularidade para que seja efetuado a operação na sequência. Você pode recuperar essa chave através do endpoint: [`Recuperando Informações da Conta`](/documentation/iaas/visibildade_de_caixa/get_accounts) Onde o source_account_key é a account_key da instituição onde você deseja realizar a aplicação. Caso contrário não envie este campo. ::: ### Body params | Campo | Tipo | Descrição | Obrigatório | | -------------------- | ------ | ------------------------------------------------ | ----------- | | `issuance_serie_key` | string | Chave única de identificação da série de emissão | Sim | | `amount` | float | Valor da aplicação | Sim | | `source_account_key` | string | Chave da conta bancária de destino dos recursos | Não | | `quotation_date` | string | Data da cotização no formato `YYYY-MM-DD` | Não | | `payment_method` | string | Método de pagamento (`wire_transfer`, `pix`) | Não | ### Response Response Body ```json { "amount": 0.00, "financial_application_key": "UUID", "asset_key": "UUID", "quotation_date": "YYYY-MM-DD", "status": "confirmed", "issuance_serie": { "issuance_serie_key": "UUID", "name": "Invested Issuance Serie Name", "subclass_name": "Invested Sub Class Name", "serie": 1, "quota_calculation_method": "quota_value", "internal_code": "Internal Code", "fund_class_name": "Invested Fund Class Name", "fund_class_short_name": "Invested Fund Class short name", "fund_class_document_number": "00.000.000/0000-00", "minimum_share_capital": 0.0, "investment_category": "multi_market", "payment_type": "transfer", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "YYYY-MM-DD", "administrator": { "administrator_key": "UUID", "name": "Administrator Name", "document_number": "00.000.000/0000-00" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "amortization_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "isin_code": "BR000000000" }, "fund_class": { "fund_class_key": "UUID", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "YYYY-MM-DD", "distributor": { "name": "Distributor Name", "distributor_key": "UUID", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "UUID", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ``` # Aprovar Aplicação Financeira --- ### Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_application/FINANCIAL_APPLICATION_KEY MÉTODO PUT STATUS 202 ```json title='Request Body' { "status": "pending_payment" } ``` ### Body params | Campo | Tipo | Descrição | | -------- | ------ | -------------------------------------------------------------------- | | `status` | string | Novo status do pedido de resgate. Veja abaixo os valores permitidos. | ### Response Response Body ```json { "amount": 0.00, "financial_application_key": "UUID", "asset_key": "UUID", "quotation_date": "YYYY-MM-DD", "status": "confirmed", "issuance_serie": { "issuance_serie_key": "UUID", "name": "Invested Issuance Serie Name", "subclass_name": "Invested Sub Class Name", "serie": 1, "quota_calculation_method": "quota_value", "internal_code": "Internal Code", "fund_class_name": "Invested Fund Class Name", "fund_class_short_name": "Invested Fund Class short name", "fund_class_document_number": "00.000.000/0000-00", "minimum_share_capital": 0.0, "investment_category": "multi_market", "payment_type": "transfer", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "YYYY-MM-DD", "administrator": { "administrator_key": "UUID", "name": "Administrator Name", "document_number": "00.000.000/0000-00" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "amortization_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "isin_code": "BR000000000" }, "fund_class": { "fund_class_key": "UUID", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "YYYY-MM-DD", "distributor": { "name": "Distributor Name", "distributor_key": "UUID", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "UUID", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ``` # Cancelar Aplicação Financeira --- ### Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_application/FINANCIAL_APPLICATION_KEY/cancel MÉTODO PUT STATUS 202 :::note **Atenção**. Você poderá cancelar um pedido de aplicação caso ele esteja em algum destes status: - pending_manager_approval - pending_distributor_approval Caso contrário você vai receber um erro com o seguinte código: TFQ000073 ::: ### Response Response Body ```json { "amount": 0.00, "financial_application_key": "UUID", "asset_key": "UUID", "quotation_date": "YYYY-MM-DD", "status": "confirmed", "issuance_serie": { "issuance_serie_key": "UUID", "name": "Invested Issuance Serie Name", "subclass_name": "Invested Sub Class Name", "serie": 1, "quota_calculation_method": "quota_value", "internal_code": "Internal Code", "fund_class_name": "Invested Fund Class Name", "fund_class_short_name": "Invested Fund Class short name", "fund_class_document_number": "00.000.000/0000-00", "minimum_share_capital": 0.0, "investment_category": "multi_market", "payment_type": "transfer", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "YYYY-MM-DD", "administrator": { "administrator_key": "UUID", "name": "Administrator Name", "document_number": "00.000.000/0000-00" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "amortization_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "isin_code": "BR000000000" }, "fund_class": { "fund_class_key": "UUID", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "YYYY-MM-DD", "distributor": { "name": "Distributor Name", "distributor_key": "UUID", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "UUID", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ``` --- # Criar Pedido de Resgate URL: /documentation/iaas/cotas_de_fundo/operacao_resgates --- :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de Gestor. ::: ### Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request MÉTODO POST STATUS 201 ```json title='Request Body' { "issuance_serie_key": "UUID", "external_id": "UUID", "amount": 0.00, "source_account_key": "UUID", "redeem_all": false } ``` :::note **Atenção**. Sempre que a operação for em uma série que o "payment_type" é "automatic_debit" (normalmente fundos de zeragem) é preciso enviar o source_account_key. Esta operação não resultará em um resgate de fato, apenas na criação das expectativas e transferência para a conta de sua titularidade para que seja efetuado a operação na sequência. Você pode recuperar essa chave através do endpoint: [`Recuperando Informações da Conta`](/documentation/iaas/visibildade_de_caixa/get_accounts) Onde o source_account_key é a account_key da instituição onde você deseja realizar o resgate. Caso contrário não envie este campo. ::: ### Body params | Campo | Tipo | Descrição | Obrigatório | | -------------------- | ------- | ------------------------------------------------------------ | ----------- | | `issuance_serie_key` | string | Chave única da Série de Emissão | Sim | | `external_id` | string | Identificador externo único do pedido de resgate | Sim | | `amount` | float | Valor bruto do resgate (ignorado se `redeem_all` for `true`) | Não | | `source_account_key` | string | Chave da conta bancária de origem do fundo classe | Não | | `redeem_all` | boolean | Indica se o resgate deve ser total | Não | ### Response Response Body ```json { "redemption_request_key": "UUID", "status": "confirmed", "quotation_date": "YYYY-MM-DD", "payment_date": "YYYY-MM-DD", "amount": 0.00, "issuance_serie": { "issuance_serie_key": "UUID", "name": "Issuance Serie Name", "subclass_name": "SUBORDINADA", "serie": 1, "quota_calculation_method": "quota_value", "internal_code": "Internal Code", "fund_class_name": "Fund Class Name", "fund_class_short_name": "Fund Class Short Name", "fund_class_document_number": "00.000.000/0000-00", "minimum_share_capital": 0.0, "investment_category": "fixed_income", "payment_type": "automatic_debit", "financial_institution_code": "341", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "YYYY-MM-DD", "administrator": { "administrator_key": "UUID", "name": "Administrator Name", "document_number": "00.000.000/0000-00" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "amortization_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "issuance_serie_data": { "name": "Issuance Serie Name", "serie": 1, "payment_type": "automatic_debit", "remuneration": "residual", "internal_code": "Internal Code", "subclass_name": "SUBORDINADA", "fund_class_name": "Fund Class Name", "issuance_serie_key": "UUID", "tax_classification": "long_term", "investment_category": "fixed_income", "fund_class_short_name": "Fund Class Short Name", "minimum_share_capital": 0.00, "quota_calculation_method": "quota_value", "financial_institution_code": "329", "fund_class_document_number": "00.000.000/0000-00", "administrator_document_number": "00.000.000/0000-00" } }, "fund_class": { "fund_class_key": "UUID", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "YYYY-MM-DD", "distributor": { "name": "Distributor Name", "distributor_key": "UUID", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "UUID", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ``` # Aprovar um Pedido de Resgate --- ### Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request/REDEMPTION_REQUEST_KEY MÉTODO PUT STATUS 202 ```json title='Request Body' { "status": "pending_external_approval" } ``` ### Body params | Campo | Tipo | Descrição | | -------- | ------ | -------------------------------------------------------------------- | | `status` | string | Novo status do pedido de resgate. Veja abaixo os valores permitidos. | ### Response Response Body ```json { "redemption_request_key": "UUID", "status": "pending_external_approval", "quotation_date": "YYYY-MM-DD", "payment_date": "YYYY-MM-DD", "amount": 0.00, "issuance_serie": { "issuance_serie_key": "UUID", "name": "Issuance Serie Name", "subclass_name": "SUBORDINADA", "serie": 1, "quota_calculation_method": "quota_value", "internal_code": "Internal Code", "fund_class_name": "Fund Class Name", "fund_class_short_name": "Fund Class Short Name", "fund_class_document_number": "00.000.000/0000-00", "minimum_share_capital": 0.0, "investment_category": "fixed_income", "payment_type": "automatic_debit", "financial_institution_code": "341", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "YYYY-MM-DD", "administrator": { "administrator_key": "UUID", "name": "Administrator Name", "document_number": "00.000.000/0000-00" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "amortization_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "issuance_serie_data": { "name": "Issuance Serie Name", "serie": 1, "payment_type": "automatic_debit", "remuneration": "residual", "internal_code": "Internal Code", "subclass_name": "SUBORDINADA", "fund_class_name": "Fund Class Name", "issuance_serie_key": "UUID", "tax_classification": "long_term", "investment_category": "fixed_income", "fund_class_short_name": "Fund Class Short Name", "minimum_share_capital": 0.00, "quota_calculation_method": "quota_value", "financial_institution_code": "329", "fund_class_document_number": "00.000.000/0000-00", "administrator_document_number": "00.000.000/0000-00" } }, "fund_class": { "fund_class_key": "UUID", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "YYYY-MM-DD", "distributor": { "name": "Distributor Name", "distributor_key": "UUID", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "UUID", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ``` # Cancelar um Pedido de Resgate --- ### Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request/REDEMPTION_REQUEST_KEY/cancel MÉTODO PUT STATUS 202 :::note **Atenção**. Você poderá cancelar um pedido de resgate caso ele esteja em algum destes status: - pending_manager_approval - pending_distributor_approval Caso contrário você vai receber um erro com o seguinte código: TFQ000078 ::: ### Response Response Body ```json { "redemption_request_key": "UUID", "status": "canceled", "quotation_date": "YYYY-MM-DD", "payment_date": "YYYY-MM-DD", "amount": 0.00, "issuance_serie": { "issuance_serie_key": "UUID", "name": "Issuance Serie Name", "subclass_name": "SUBORDINADA", "serie": 1, "quota_calculation_method": "quota_value", "internal_code": "Internal Code", "fund_class_name": "Fund Class Name", "fund_class_short_name": "Fund Class Short Name", "fund_class_document_number": "00.000.000/0000-00", "minimum_share_capital": 0.0, "investment_category": "fixed_income", "payment_type": "automatic_debit", "financial_institution_code": "341", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "YYYY-MM-DD", "administrator": { "administrator_key": "UUID", "name": "Administrator Name", "document_number": "00.000.000/0000-00" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "amortization_request": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } }, "issuance_serie_data": { "name": "Issuance Serie Name", "serie": 1, "payment_type": "automatic_debit", "remuneration": "residual", "internal_code": "Internal Code", "subclass_name": "SUBORDINADA", "fund_class_name": "Fund Class Name", "issuance_serie_key": "UUID", "tax_classification": "long_term", "investment_category": "fixed_income", "fund_class_short_name": "Fund Class Short Name", "minimum_share_capital": 0.00, "quota_calculation_method": "quota_value", "financial_institution_code": "329", "fund_class_document_number": "00.000.000/0000-00", "administrator_document_number": "00.000.000/0000-00" } }, "fund_class": { "fund_class_key": "UUID", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "YYYY-MM-DD", "distributor": { "name": "Distributor Name", "distributor_key": "UUID", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "UUID", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ``` --- # Consulta de despesas consolidadas URL: /documentation/iaas/despesas/despesa_consolidada/consulta_despesas Endpoints para consultar as despesas de uma classe de fundo. Existem dois modos de consulta: a **listagem paginada** de todas as despesas de uma classe de fundo, e a **consulta individual** de uma despesa específica. :::tip Quando utilizar Utilize estes endpoints para acompanhar o status das despesas cadastradas, verificar valores provisionados e consolidados, e consultar os dados de pagamento de cada despesa. ::: ## Listagem de despesas Retorna a lista paginada de todas as despesas de uma classe de fundo, com suporte a diversos filtros. ### Request ENDPOINT /expense/fund_class/{fund_class_key}/expenses MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Mínimo: `0`. Máximo: `100`. Padrão: `10`. | | `reference_date` | string | opcional | Filtra despesas pela data de referência exata, no formato `YYYY-MM-DD`. | | `from_end_deferral_date` | string | opcional | Filtra despesas com data de encerramento de diferimento maior ou igual à data informada, no formato `YYYY-MM-DD`. | | `to_end_deferral_date` | string | opcional | Filtra despesas com data de encerramento de diferimento menor ou igual à data informada, no formato `YYYY-MM-DD`. | | `status` | string | opcional | Filtra pelo status da despesa. Aceita múltiplos valores separados por vírgula (ex: `paid,consolidated`). Veja [enumeradores de `status`](#enumeradores-de-status). | | `expense_type` | string | opcional | Filtra pelo tipo da despesa. Aceita múltiplos valores separados por vírgula (ex: `management_tax,custody_tax`). Veja [enumeradores de `type`](#enumeradores-de-type). | | `expense_status_to_ignore` | string | opcional | Exclui da listagem despesas com o status informado. | | `expense_type_to_ignore` | string | opcional | Exclui da listagem despesas com o tipo informado. | | `ignore_paid_on_future` | boolean | opcional | Quando `true`, exclui despesas que já foram pagas mas com data de confirmação posterior à data de referência. | ```python title="Exemplo de chamada" GET /expense/fund_class/{fund_class_key}/expenses?page=0&limit=10&status=consolidated,paid ``` ### Response STATUS 200 ```json title="Response Body" { "data": [ { "expense_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class": { "name": "Fundo de Investimento XYZ", "manager": { "name": "Gestora ABC", "manager_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "document_number": "12.345.678/0001-90" }, "fund_class_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "document_number": "98.765.432/0001-10", "accounting_date": "2025-06-10" }, "status": "consolidated", "type": "management_tax", "reference_date": "2025-06-10", "start_deferral_date": "2025-06-01", "end_deferral_date": "2025-06-30", "consolidated_value": 1500.00, "provisioned_value": 1500.00, "recognized_value": 1500.00, "payment": null, "expense_datetime": "2025-06-01T00:00:00Z", "description": "Taxa de gestão referente ao mês de junho/2025", "payment_method": "transfer", "payment_date": "2025-06-30", "payment_confirmation": { "confirmation_date": "2025-06-30" } } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de objetos de despesa. Veja [Atributos de cada despesa](#atributos-de-cada-despesa-objetos-dentro-de-data). | | `page` | integer | Número da página atual. | | `limit` | integer | Quantidade de registros por página. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada despesa (objetos dentro de `data`) | Campo | Tipo | Descrição | |---|---|---| | `expense_key` | string | Identificador único da despesa (UUID). | | `fund_class` | object | Dados da classe de fundo à qual a despesa pertence. Veja [Atributos de `fund_class`](#atributos-de-fund_class). | | `status` | string | Status atual da despesa. Veja [enumeradores de `status`](#enumeradores-de-status). | | `type` | string | Tipo da despesa. Veja [enumeradores de `type`](#enumeradores-de-type). | | `reference_date` | string | Data de referência da despesa no formato `YYYY-MM-DD`. | | `start_deferral_date` | string | Data de início do diferimento no formato `YYYY-MM-DD`. | | `end_deferral_date` | string | Data de encerramento do diferimento no formato `YYYY-MM-DD`. | | `consolidated_value` | number | Valor consolidado da despesa. Pode ser `null` quando a despesa ainda não foi consolidada. | | `provisioned_value` | number | Valor provisionado da despesa. Pode ser `null` quando ainda não há provisão. | | `recognized_value` | number | Valor reconhecido da despesa. | | `payment` | object | Dados do pagamento associado à despesa. Pode ser `null` quando não há pagamento vinculado. | | `expense_datetime` | string | Data e hora de criação da despesa no formato ISO 8601 (ex: `2025-06-01T00:00:00Z`). | | `description` | string | Descrição textual da despesa. | | `payment_method` | string | Método de pagamento da despesa. Veja [enumeradores de `payment_method`](#enumeradores-de-payment_method). | | `payment_date` | string | Data de pagamento no formato `YYYY-MM-DD`. Presente somente quando a despesa possui data de pagamento definida. | | `payment_confirmation` | object | Dados de confirmação de pagamento. Presente somente quando o pagamento foi confirmado. Veja [Atributos de `payment_confirmation`](#atributos-de-payment_confirmation). | #### Atributos de `fund_class` | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome da classe de fundo. | | `fund_class_key` | string | Identificador único da classe de fundo (UUID). | | `document_number` | string | CNPJ da classe de fundo. | | `accounting_date` | string | Data de contabilização da classe de fundo no formato `YYYY-MM-DD`. | | `manager` | object | Dados do gestor responsável. Veja [Atributos de `manager`](#atributos-de-manager). | #### Atributos de `manager` | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome do gestor. | | `manager_key` | string | Identificador único do gestor (UUID). | | `document_number` | string | CNPJ do gestor. | #### Atributos de `payment_confirmation` | Campo | Tipo | Descrição | |---|---|---| | `confirmation_date` | string | Data de confirmação do pagamento no formato `YYYY-MM-DD`. | --- ## Consulta de despesa específica Retorna os dados completos de uma despesa específica de uma classe de fundo. ### Request ENDPOINT /expense/fund_class/{fund_class_key}/expense/{expense_key} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Identificador único (UUID) da classe de fundo à qual a despesa pertence. | | `expense_key` | string | Identificador único (UUID) da despesa a ser consultada. | ```python title="Exemplo de chamada" GET /expense/fund_class/{fund_class_key}/expense/{expense_key} ``` ### Response STATUS 200 ```json title="Response Body" { "expense_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class": { "name": "Fundo de Investimento XYZ", "manager": { "name": "Gestora ABC", "manager_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "document_number": "12.345.678/0001-90" }, "fund_class_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "document_number": "98.765.432/0001-10", "accounting_date": "2025-06-10" }, "status": "consolidated", "type": "management_tax", "reference_date": "2025-06-10", "start_deferral_date": "2025-06-01", "end_deferral_date": "2025-06-30", "consolidated_value": 1500.00, "provisioned_value": 1500.00, "recognized_value": 1500.00, "payment": null, "expense_datetime": "2025-06-01T00:00:00Z", "description": "Taxa de gestão referente ao mês de junho/2025", "payment_method": "transfer", "payment_date": "2025-06-30", "payment_confirmation": { "confirmation_date": "2025-06-30" } } ``` ### Atributos da resposta A resposta possui a mesma estrutura de cada objeto do array `data` retornado pela [listagem de despesas](#atributos-de-cada-despesa-objetos-dentro-de-data). --- ## Possíveis erros STATUS 404 **Despesa não encontrada** O `expense_key` informado não corresponde a nenhuma despesa cadastrada para esta classe de fundo. Verifique se os identificadores estão corretos. ```json { "title": "Expense not Found", "description": "The Expense with key {expense_key} was not found in Fund Class with key {fund_class_key}.", "translation": "A Despesa com a chave {expense_key} nao foi encontrada na classe de fundos com a chave {fund_class_key}.", "code": "EXP000010" } ``` --- ## Enumeradores de `status` | Valor | Descrição | |---|---| | `created` | Despesa criada, ainda não iniciou o processo de provisionamento. | | `in_provision` | Despesa em processo de provisionamento diário. | | `on_demand_recognition` | Despesa com reconhecimento sob demanda (manual). | | `consolidated` | Despesa consolidada — valor total reconhecido e pronto para pagamento. | | `paid` | Despesa paga. | | `canceled` | Despesa cancelada. | | `completed` | Despesa encerrada. | ## Enumeradores de `type` | Valor | Descrição | |---|---| | `administration_tax` | Taxa de administração. | | `management_tax` | Taxa de gestão. | | `performance_fee` | Taxa de performance. | | `custody_tax` | Taxa de custódia. | | `distribution_fee` | Taxa de distribuição. | | `consulting_fee` | Taxa de consultoria. | | `audit_tax` | Taxa de auditoria. | | `cvm_tax` | Taxa CVM. | | `cetip_tax` | Taxa CETIP. | | `anbima_tax` | Taxa ANBIMA. | | `selic_tax` | Taxa SELIC. | | `notary` | Cartório. | | `bank_account` | Conta bancária. | | `bankslip_fee` | Taxa de boleto. | | `sale_commission_tax` | Taxa de comissão de venda. | | `certifier_fee` | Taxa de certificadora. | | `rating_agency_fee` | Taxa de agência de rating. | | `lawyer_fee` | Honorários advocatícios. | | `bookkeeping_fee` | Taxa de escrituração. | | `insurance_fee` | Taxa de seguro. | | `collection_agent_fee` | Taxa de agente cobrador. | | `servicing_fee` | Taxa de serviços. | | `fund_structuring_fee` | Taxa de estruturação do fundo. | | `credit_rights_registration_fee` | Taxa de registro de direitos creditórios. | | `origination_fee` | Taxa de originação. | ## Enumeradores de `payment_method` | Valor | Descrição | |---|---| | `transfer` | Transferência bancária. | | `automatic_debit` | Débito automático. | | `bank_slip` | Boleto bancário. | --- # Atualização do Contrato URL: /documentation/iaas/despesas/submissao_despesa/contrato/atualizacao Edite os dados de um contrato enquanto ele ainda estiver no status `created`. Após a [submissão](/documentation/iaas/despesas/submissao_despesa/contrato/submissao), o contrato não pode mais ser alterado. :::info Somente contratos com status `created` podem ser atualizados. ::: ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | ```json title="Request Body" { "name": "Contrato de Auditoria - Exercício 2026 (revisado)", "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "expense_type": "audit_tax", "submission_nature": "manual_submission", "contract_value": 60000.00, "validity_date": "2026-12-31" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | opcional | Novo nome do contrato. Máximo de 255 caracteres. | | `vendor_key` | string | opcional | Nova chave do fornecedor. | | `expense_type` | string | opcional | Novo tipo de despesa. Ver [Tipos de despesa](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#tipos-de-despesa). | | `submission_nature` | string | opcional | Nova natureza de submissão: `manual_submission` ou `rebate`. | | `contract_value` | number | opcional | Novo valor máximo do contrato. Mínimo: `0`. | | `validity_date` | string | opcional | Nova data de validade no formato `YYYY-MM-DD`. | ## Response STATUS 200 ```json title="Response Body" { "name": "Contrato de Auditoria - Exercício 2026 (revisado)", "contract_key": "contrato-auditoria-2026", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": "True" }, "expense_type": "audit_tax", "status": "created", "contract_value": 60000.00, "validity_date": "2026-12-31", "submission_nature": "manual_submission" } ``` Os atributos da resposta seguem a mesma estrutura da [criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#atributos-da-resposta). ## Possíveis erros STATUS 404 **Contrato não encontrado** O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado. ```json { "title": "Contract Not Found", "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.", "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.", "code": "ESB000011" } ``` STATUS 400 **Contrato não pode ser editado neste status** O contrato não está no status `created` e não pode ser editado. ```json { "title": "Cannot Update Contract In This Status", "description": "Contract {contract_key} cannot be updated with status {current_status}.", "translation": "O contrato {contract_key} não pode ser atualizado com o status {current_status}.", "code": "ESB000022" } ``` ## Próximos passos 1. **[Submeter o contrato](/documentation/iaas/despesas/submissao_despesa/contrato/submissao)** — envie o contrato para análise quando estiver pronto. 2. **[Cancelar o contrato](/documentation/iaas/despesas/submissao_despesa/contrato/cancelamento)** — cancele o contrato caso não seja mais necessário. --- # Cancelamento do Contrato URL: /documentation/iaas/despesas/submissao_despesa/contrato/cancelamento Cancele um contrato que não seja mais necessário. O cancelamento é uma operação irreversível. :::caution Atenção Um contrato cancelado não pode ser reativado. Despesas que estejam sob um contrato cancelado também são impactadas. Certifique-se de que o cancelamento é realmente necessário antes de prosseguir. ::: ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/cancel MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | Este endpoint não requer body na requisição. ## Response STATUS 200 ```json title="Response Body" { "name": "Contrato de Auditoria - Exercício 2026", "contract_key": "contrato-auditoria-2026", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": "True" }, "expense_type": "audit_tax", "status": "canceled", "contract_value": 50000.00, "validity_date": "2026-12-31", "submission_nature": "manual_submission" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Novo status do contrato. Sempre retorna `canceled` após o cancelamento bem-sucedido. | Os demais campos seguem a mesma estrutura da [criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#atributos-da-resposta). ## Possíveis erros STATUS 404 **Contrato não encontrado** O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado. ```json { "title": "Contract Not Found", "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.", "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.", "code": "ESB000011" } ``` STATUS 400 **Contrato já em status final** O contrato já está em um status final (`approved` ou `rejected`) e não pode ser cancelado. ```json { "title": "Already In Final Contract Status", "description": "The contract {contract_key} is already in a final status: {current_status}.", "translation": "O contrato {contract_key} já está em um status final: {current_status}.", "code": "ESB000020" } ``` --- # Criação do Contrato URL: /documentation/iaas/despesas/submissao_despesa/contrato/criacao Este é o **primeiro passo** do fluxo de submissão de despesas pelo agente integrador. O contrato define a relação comercial entre o fundo e um fornecedor, estabelecendo o tipo de despesa e as condições de pagamento. :::info Pré-requisitos Antes de criar um contrato, você precisa ter em mãos: - `fund_class_key` — chave única do fundo, fornecida pela QI Tech - `vendor_key` — chave do fornecedor cadastrado. Consulte a [listagem de fornecedores](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem) para obtê-la Para mais detalhes sobre o fluxo completo, consulte a [página de introdução](/documentation/iaas/despesas/submissao_despesa/inicio). ::: :::caution Atenção O campo `submission_nature = rebate` só pode ser utilizado em conjunto com `expense_type = distribution_fee`. Para todos os demais tipos de despesa, use `submission_nature = manual_submission`. ::: ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | ```json title="Request Body" { "name": "Contrato de Auditoria - Exercício 2026", "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "expense_type": "audit_tax", "submission_nature": "manual_submission", "contract_value": 50000.00, "validity_date": "2026-12-31", "contract_key": "contrato-auditoria-2026" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do contrato. Máximo de 255 caracteres. | | `vendor_key` | string | obrigatório | Chave única do fornecedor (máximo 255 caracteres). | | `expense_type` | string | obrigatório | Tipo de despesa. Ver [Tipos de despesa](#tipos-de-despesa). | | `submission_nature` | string | obrigatório | Natureza de submissão: `manual_submission` ou `rebate`. | | `contract_value` | number | opcional | Valor máximo do contrato. Quando informado, a soma das despesas não pode exceder este valor. Mínimo: `0`. | | `validity_date` | string | opcional | Data de validade do contrato no formato `YYYY-MM-DD`. Após esta data, nenhuma nova despesa pode ser criada. | | `contract_key` | string | opcional | Identificador personalizado do contrato no sistema do parceiro. Máximo de 255 caracteres. Quando não informado, um UUID é gerado automaticamente. | ### Tipos de despesa | Valor | Descrição | |---|---| | `cvm_tax` | Taxa CVM | | `cetip_tax` | Taxa CETIP | | `anbima_tax` | Taxa ANBIMA | | `notary` | Cartório | | `audit_tax` | Taxa de auditoria | | `administration_tax` | Taxa de administração | | `management_tax` | Taxa de gestão | | `bank_account` | Conta bancária | | `selic_tax` | Taxa SELIC | | `consulting_fee` | Honorários de consultoria | | `custody_tax` | Taxa de custódia | | `performance_fee` | Taxa de performance | | `bankslip_fee` | Taxa de boleto | | `sale_commission_tax` | Comissão de venda | | `certifier_fee` | Honorários de certificador | | `rating_agency_fee` | Taxa de agência de rating | | `lawyer_fee` | Honorários advocatícios | | `bookkeeping_fee` | Taxa de escrituração | | `distribution_fee` | Taxa de distribuição | | `insurance_fee` | Taxa de seguro | | `collection_agent_fee` | Honorários de agente de cobrança | | `servicing_fee` | Taxa de serviços | | `fund_structuring_fee` | Taxa de estruturação do fundo | | `credit_rights_registration_fee` | Taxa de registro de direitos creditórios | | `origination_fee` | Taxa de originação | ## Response STATUS 201 ```json title="Response Body" { "name": "Contrato de Auditoria - Exercício 2026", "contract_key": "contrato-auditoria-2026", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": "True" }, "expense_type": "audit_tax", "status": "created", "contract_value": 50000.00, "validity_date": "2026-12-31", "submission_nature": "manual_submission" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome do contrato. | | `contract_key` | string | Chave única do contrato. Guarde este valor para as próximas etapas. | | `fund_class` | object | Dados do fundo associado. Veja [Atributos de `fund_class`](#atributos-de-fund_class). | | `vendor` | object | Dados do fornecedor. Veja [Atributos de `vendor`](#atributos-de-vendor). | | `expense_type` | string | Tipo de despesa do contrato. | | `status` | string | Status inicial do contrato. Sempre retorna `created`. | | `contract_value` | number | Valor máximo do contrato, ou `null` quando não informado. | | `validity_date` | string | Data de validade no formato `YYYY-MM-DD`, ou `null` quando não informada. | | `submission_nature` | string | Natureza de submissão do contrato. | #### Atributos de `fund_class` | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome do fundo. | | `manager` | object | Dados do gestor do fundo. | | `manager.name` | string | Nome do gestor. | | `manager.manager_key` | string | Chave única do gestor (UUID). | | `manager.document_number` | string | CNPJ do gestor. | | `fund_class_key` | string | Chave única do fundo (UUID). | | `document_number` | string | CNPJ do fundo. | #### Atributos de `vendor` | Campo | Tipo | Descrição | |---|---|---| | `vendor_key` | string | Chave única do fornecedor. | | `name` | string | Nome do fornecedor. | | `document_number` | string | CPF ou CNPJ do fornecedor. | | `requires_invoice` | string | Indica se o fornecedor exige nota fiscal (`"True"` ou `"False"`). | ## Possíveis erros STATUS 404 **Fundo não encontrado** A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado. ```json { "title": "Fund Class Not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "O Fundo com chave {fund_class_key} nao foi encontrado.", "code": "ESB000005" } ``` **Fornecedor não encontrado** A `vendor_key` informada no body não corresponde a nenhum fornecedor cadastrado. ```json { "title": "Vendor Not Found", "description": "Vendor with key {vendor_key} was not found.", "translation": "O fornecedor com a chave {vendor_key} nao foi encontrado.", "code": "ESB000008" } ``` STATUS 409 **Contract key duplicada** Já existe um contrato com a `contract_key` informada neste fundo. Use um identificador diferente ou omita o campo para gerar um UUID automaticamente. ```json { "title": "Contract Key Already Exists", "description": "A Contract with key {contract_key} already exists.", "translation": "Um contrato com a chave {contract_key} já existe.", "code": "ESB000012" } ``` STATUS 400 **Tipo de despesa incompatível com a natureza de submissão** O valor `rebate` em `submission_nature` só é válido quando `expense_type` é `distribution_fee`. ```json { "title": "Invalid Expense Type", "description": "The expense type {expense_type} is not valid for submission nature {submission_nature}.", "translation": "O tipo de despesa {expense_type} não é válido para a natureza de submissão {submission_nature}.", "code": "ESB000031" } ``` ## Próximos passos Após criar o contrato, o fluxo continua com: 1. **[Submissão do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/submissao)** — envie o contrato para análise e aprovação pela QI Tech. 2. **[Atualização do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao)** — edite os dados do contrato enquanto ele ainda estiver em status `created`. --- # Listagem de Contratos URL: /documentation/iaas/despesas/submissao_despesa/contrato/listagem Liste os contratos de um fundo com filtros opcionais por tipo de despesa, status ou natureza de submissão. ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contracts MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `expense_type` | string | opcional | Filtra por tipo de despesa. Ver [tipos de despesa](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#tipos-de-despesa). | | `status` | string | opcional | Filtra por status do contrato (`created`, `pending_adm_approval`, `approved`, `rejected`, `canceled`). | | `submission_nature` | string | opcional | Filtra por natureza: `manual_submission` ou `rebate`. | | `limit` | integer | opcional | Número de itens por página. Mínimo: `1`. Máximo: `1000`. Padrão: `10`. | | `page` | integer | opcional | Número da página (base zero). Padrão: `0`. | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "name": "Contrato de Auditoria - Exercício 2026", "contract_key": "contrato-auditoria-2026", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": "True" }, "expense_type": "audit_tax", "status": "approved", "contract_value": 50000.00, "validity_date": "2026-12-31", "submission_nature": "manual_submission" } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de contratos. Cada item segue a estrutura da [consulta individual](/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao). | | `limit` | integer | Número de itens por página utilizado na consulta. | | `page` | integer | Número da página atual. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | ## Possíveis erros STATUS 404 **Fundo não encontrado** A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado. ```json { "title": "Fund Class Not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "O Fundo com chave {fund_class_key} nao foi encontrado.", "code": "ESB000005" } ``` --- # Consulta de Contrato URL: /documentation/iaas/despesas/submissao_despesa/contrato/recuperacao Recupere os dados e o status atual de um contrato específico. ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | ## Response STATUS 200 ```json title="Response Body" { "name": "Contrato de Auditoria - Exercício 2026", "contract_key": "contrato-auditoria-2026", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": "True" }, "expense_type": "audit_tax", "status": "approved", "contract_value": 50000.00, "validity_date": "2026-12-31", "submission_nature": "manual_submission" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome do contrato. | | `contract_key` | string | Chave única do contrato. | | `fund_class` | object | Dados do fundo associado. | | `vendor` | object | Dados do fornecedor. | | `expense_type` | string | Tipo de despesa do contrato. | | `status` | string | Status atual do contrato. Ver tabela de [status do contrato](/documentation/iaas/despesas/submissao_despesa/inicio#status-do-contrato). | | `contract_value` | number | Valor máximo do contrato, ou `null` quando não informado. | | `validity_date` | string | Data de validade no formato `YYYY-MM-DD`, ou `null` quando não informada. | | `submission_nature` | string | Natureza de submissão do contrato. | ## Possíveis erros STATUS 404 **Contrato não encontrado** O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado. ```json { "title": "Contract Not Found", "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.", "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.", "code": "ESB000011" } ``` --- # Submissão do Contrato URL: /documentation/iaas/despesas/submissao_despesa/contrato/submissao Após criar o contrato, submeta-o para análise da QI Tech. A submissão encaminha o contrato para revisão manual e muda seu status para `pending_adm_approval`. :::caution Atenção Após a submissão, o contrato não pode mais ser editado. Verifique todos os dados antes de prosseguir. Caso precise fazer alterações, utilize o endpoint de [atualização](/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao) enquanto o status ainda for `created`. ::: ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/submit MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | Este endpoint não requer body na requisição. ## Response STATUS 200 ```json title="Response Body" { "name": "Contrato de Auditoria - Exercício 2026", "contract_key": "contrato-auditoria-2026", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": "True" }, "expense_type": "audit_tax", "status": "pending_adm_approval", "contract_value": 50000.00, "validity_date": "2026-12-31", "submission_nature": "manual_submission" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Novo status do contrato. Sempre retorna `pending_adm_approval` após a submissão bem-sucedida. | Os demais campos seguem a mesma estrutura da [criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#atributos-da-resposta). ## Possíveis erros STATUS 404 **Contrato não encontrado** O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado. ```json { "title": "Contract Not Found", "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.", "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.", "code": "ESB000011" } ``` STATUS 400 **Transição de status inválida** O contrato não pode ser submetido a partir do status atual. A submissão só é permitida quando o contrato está no status `created`. ```json { "title": "Invalid Contract Status Change", "description": "It is not possible to change the contract status from {current_status} to {new_status}.", "translation": "Não é possível alterar o status do contrato de {current_status} para {new_status}.", "code": "ESB000013" } ``` ## Próximos passos Após submeter o contrato, aguarde a análise da QI Tech. Enquanto isso, você pode: 1. **[Consultar o contrato](/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao)** — acompanhe o status do contrato. 2. **[Criar despesas](/documentation/iaas/despesas/submissao_despesa/despesa/criacao)** — despesas podem ser criadas mesmo enquanto o contrato aguarda aprovação (exceto contratos com status `rejected`). --- # Atualização da Despesa URL: /documentation/iaas/despesas/submissao_despesa/despesa/atualizacao Edite os dados de uma despesa enquanto ela ainda estiver no status `created`. Após a submissão ou após a criação com documentos (status `pending_adm_approval`), a despesa não pode mais ser alterada. :::info Somente despesas com status `created` podem ser atualizadas. ::: ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | | `expense_key` | string | Chave única da despesa (UUID) | ```json title="Request Body" { "payment_method": "transfer", "start_deferral_date": "2026-06-02", "end_deferral_date": "2026-06-30", "description": "Honorários de auditoria - 1º semestre 2026 (corrigido)", "payment_value": 16000.00, "payment_date": "2026-07-01", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341" }, "transfer_type": "wire_transfer", "source_account": { "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e" } } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `payment_method` | string | opcional | Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. | | `start_deferral_date` | string | opcional | Data início da competência no formato `YYYY-MM-DD`. Deve ser dia útil. | | `end_deferral_date` | string | opcional | Data fim da competência no formato `YYYY-MM-DD`. Deve ser dia útil. | | `description` | string | opcional | Nova descrição da despesa. Máximo de 200 caracteres. | | `payment_value` | number | opcional | Novo valor da despesa. Mínimo: `0`. | | `payment_date` | string | opcional | Nova data de pagamento no formato `YYYY-MM-DD`. Deve ser dia útil. | | `payment` | object | opcional | Novos dados do pagamento. Mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-de-payment). | ## Response STATUS 200 A resposta segue a mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-da-resposta), com os campos atualizados. ## Possíveis erros STATUS 404 **Despesa não encontrada** O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada. ```json { "title": "Expense Not Found", "description": "Expense with key {expense_key} was not found.", "translation": "A despesa com chave {expense_key} não foi encontrada.", "code": "ESB000016" } ``` STATUS 400 **Despesa não pode ser editada neste status** A despesa não está no status `created` e não pode ser editada. ```json { "title": "Cannot Update Expense In This Status", "description": "Expense {expense_key} cannot be updated with status {current_status}.", "translation": "A despesa {expense_key} não pode ser atualizada com o status {current_status}.", "code": "ESB000023" } ``` ## Próximos passos 1. **[Submeter a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** — encaminhe para análise quando estiver pronto. 2. **[Cancelar a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/cancelamento)** — cancele caso não seja mais necessária. --- # Cancelamento da Despesa URL: /documentation/iaas/despesas/submissao_despesa/despesa/cancelamento Cancele uma despesa que não seja mais necessária. O cancelamento é uma operação irreversível. :::caution Atenção Uma despesa cancelada não pode ser reativada. Certifique-se de que o cancelamento é realmente necessário antes de prosseguir. Despesas nos status `approved` ou `rejected` não podem ser canceladas. ::: ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/cancel MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | | `expense_key` | string | Chave única da despesa (UUID) | Este endpoint não requer body na requisição. ## Response STATUS 200 ```json title="Response Body" { "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567", "contract_key": "contrato-auditoria-2026", "status": "canceled", "payment_method": "transfer", "start_deferral_date": "2026-06-02", "end_deferral_date": "2026-06-30", "description": "Honorários de auditoria referente ao 1º semestre de 2026", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341" } }, "payment_value": 15000.00, "payment_date": "2026-07-01", "rebate_expense_key": null, "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" } } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Novo status da despesa. Sempre retorna `canceled` após o cancelamento bem-sucedido. | Os demais campos seguem a mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-da-resposta). ## Possíveis erros STATUS 404 **Despesa não encontrada** O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada. ```json { "title": "Expense Not Found", "description": "Expense with key {expense_key} was not found.", "translation": "A despesa com chave {expense_key} não foi encontrada.", "code": "ESB000016" } ``` STATUS 400 **Despesa já em status final** A despesa já está em um status final (`approved` ou `rejected`) e não pode ser cancelada. ```json { "title": "Already In Final Expense Status", "description": "Expense {expense_key} is already in a final status: {current_status}.", "translation": "A despesa {expense_key} já está em um status final: {current_status}.", "code": "ESB000021" } ``` --- # Criação da Despesa URL: /documentation/iaas/despesas/submissao_despesa/despesa/criacao Crie uma despesa individual sob um contrato existente. A despesa contém os dados de pagamento, o período de competência e os documentos comprobatórios. :::info Pré-requisitos - O contrato referenciado deve existir e não pode estar no status `rejected`. - As datas (`payment_date`, `start_deferral_date`, `end_deferral_date`) devem ser **dias úteis** (sem fins de semana ou feriados nacionais). - `start_deferral_date` não pode ser posterior a `end_deferral_date`. - Quando o contrato possui `contract_value`, a soma dos valores de todas as despesas não pode ultrapassar esse limite. ::: :::tip Atalho para submissão Se os documentos comprobatórios forem incluídos no campo `documents` durante a criação, a despesa é **automaticamente encaminhada para revisão** (status `pending_adm_approval`), sem necessidade de chamar o endpoint de submissão separadamente. ::: ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | ```json title="Request Body — Pagamento por transferência (TED/PIX)" { "payment_method": "transfer", "start_deferral_date": "2026-06-02", "end_deferral_date": "2026-06-30", "description": "Honorários de auditoria referente ao 1º semestre de 2026", "payment_value": 15000.00, "payment_date": "2026-07-01", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341" }, "transfer_type": "wire_transfer", "source_account": { "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e" } }, "documents": [ { "name": "NF-e 001234", "document_type": "invoice", "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..." } ] } ``` ```json title="Request Body — Pagamento por boleto" { "payment_method": "bank_slip", "start_deferral_date": "2026-06-02", "end_deferral_date": "2026-06-30", "description": "Taxa de custódia - junho/2026", "payment_value": 3500.00, "payment_date": "2026-07-01", "payment": { "target": { "name": "CUSTODIANTE EXEMPLO S.A.", "document_number": "98.765.432/0001-10" }, "bank_slip": { "digitable_line": "34191.09008 63521.510047 91020.150008 1 10010000035000" }, "source_account": { "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e" } } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `payment_method` | string | obrigatório | Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. | | `start_deferral_date` | string | obrigatório | Data início da competência no formato `YYYY-MM-DD`. Deve ser dia útil. | | `end_deferral_date` | string | obrigatório | Data fim da competência no formato `YYYY-MM-DD`. Deve ser dia útil e ≥ `start_deferral_date`. | | `description` | string | obrigatório | Descrição da despesa. Máximo de 200 caracteres. | | `payment_value` | number | obrigatório | Valor da despesa. Mínimo: `0`. | | `payment_date` | string | obrigatório | Data de pagamento no formato `YYYY-MM-DD`. Deve ser dia útil. | | `payment` | object | obrigatório | Dados do pagamento. Ver [Atributos de `payment`](#atributos-de-payment). | | `documents` | array | opcional | Lista de documentos comprobatórios. Quando informado, a despesa é automaticamente encaminhada para revisão. Ver [Atributos de `documents`](#atributos-de-documents). | #### Atributos de `payment` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `target` | object | obrigatório | Dados do beneficiário. | | `target.name` | string | obrigatório | Nome do beneficiário. | | `target.document_number` | string | obrigatório | CPF (`###.###.###-##`) ou CNPJ (`##.###.###/####-##`) do beneficiário. | | `target_account` | object | condicional | Dados da conta bancária de destino. Obrigatório para `payment_method = transfer`. | | `target_account.account_number` | string | obrigatório | Número da conta (1-20 dígitos, não pode ser todos zeros). | | `target_account.account_branch` | string | obrigatório | Agência (exatamente 4 dígitos, não pode ser todos zeros). | | `target_account.account_digit` | string | obrigatório | Dígito verificador (1 dígito). | | `target_account.financial_institution_code` | string | obrigatório | Código do banco (exatamente 3 dígitos, não pode ser todos zeros). | | `target_account.financial_institution_ispb` | string | opcional | ISPB do banco (exatamente 8 dígitos). | | `target_account.account_type` | string | opcional | Tipo da conta bancária. | | `transfer_type` | string | condicional | Tipo de transferência: `pix` ou `wire_transfer`. Necessário para `payment_method = transfer`. | | `target_pix_key` | string | condicional | Chave PIX do beneficiário (1-77 caracteres). Obrigatório quando `transfer_type = pix`. | | `pix_qrcode` | string | opcional | QR Code PIX (1-255 caracteres). | | `bank_slip` | object | condicional | Dados do boleto. Obrigatório para `payment_method = bank_slip`. | | `bank_slip.digitable_line` | string | obrigatório | Linha digitável do boleto (47-48 caracteres). | | `source_account` | object | opcional | Conta de débito de origem do pagamento. | | `source_account.account_key` | string | obrigatório | Chave única da conta de origem (UUID). | | `conciliation_metadata` | object | opcional | Metadados de conciliação. | | `conciliation_metadata.fee_type` | string | opcional | Tipo de taxa para conciliação. | | `conciliation_metadata.conciliation_value` | string | opcional | Valor de conciliação. | | `conciliation_metadata.conciliation_field` | string | opcional | Campo de conciliação. | #### Atributos de `documents` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do documento. Máximo de 255 caracteres. | | `document_type` | string | obrigatório | Tipo do documento: `invoice` (NF), `calculation_memory` (memória de cálculo), `contract` (contrato) ou `bank_slip` (boleto). | | `document_b64` | string | obrigatório | Conteúdo do documento codificado em Base64. | ## Response STATUS 201 ```json title="Response Body" { "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567", "contract_key": "contrato-auditoria-2026", "status": "pending_adm_approval", "payment_method": "transfer", "start_deferral_date": "2026-06-02", "end_deferral_date": "2026-06-30", "description": "Honorários de auditoria referente ao 1º semestre de 2026", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341" }, "transfer_type": "wire_transfer", "source_account": { "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e" } }, "payment_value": 15000.00, "payment_date": "2026-07-01", "rebate_expense_key": null, "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" } } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `expense_key` | string | Chave única da despesa (UUID). Guarde este valor para as próximas etapas. | | `contract_key` | string | Chave do contrato ao qual a despesa pertence. | | `status` | string | Status da despesa. Será `pending_adm_approval` se documentos foram incluídos na criação, ou `created` caso contrário. | | `payment_method` | string | Método de pagamento da despesa. | | `start_deferral_date` | string | Data início de competência no formato `YYYY-MM-DD`. | | `end_deferral_date` | string | Data fim de competência no formato `YYYY-MM-DD`. | | `description` | string | Descrição da despesa. | | `payment` | object | Dados do pagamento conforme enviado na criação. | | `payment_value` | number | Valor da despesa. | | `payment_date` | string | Data de pagamento no formato `YYYY-MM-DD`. | | `rebate_expense_key` | string | Chave da despesa original quando se tratar de um rebate, ou `null`. | | `fund_class` | object | Dados do fundo associado. | ## Possíveis erros STATUS 404 **Contrato não encontrado** O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado. ```json { "title": "Contract Not Found", "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.", "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.", "code": "ESB000011" } ``` STATUS 400 **Contrato rejeitado** Não é possível criar despesas em um contrato com status `rejected`. ```json { "title": "Cannot Create Expense On Rejected Contract", "description": "Cannot create expense on rejected contract {contract_key}.", "translation": "Não é possível criar despesa no contrato rejeitado {contract_key}.", "code": "ESB000035" } ``` **Contrato vencido** A data de validade do contrato já passou. Não é possível criar novas despesas. ```json { "title": "Contract Expired", "description": "Contract {contract_key} has expired.", "translation": "O contrato {contract_key} está vencido.", "code": "ESB000029" } ``` **Soma das despesas excede o valor do contrato** A soma dos valores de todas as despesas ultrapassaria o `contract_value` definido no contrato. ```json { "title": "Expense Value Sum Greater Than Contract", "description": "The sum of expense values exceeds the contract value for {contract_name}.", "translation": "A soma dos valores das despesas excede o valor do contrato {contract_name}.", "code": "ESB000030" } ``` **Data inválida (não é dia útil)** A data informada em `payment_date`, `start_deferral_date` ou `end_deferral_date` não é um dia útil. ```json { "title": "Date Invalid For Expense Creation", "description": "The date {date} is not a valid workday for expense creation.", "translation": "A data {date} não é um dia útil válido para criação de despesa.", "code": "ESB000032" } ``` **Data início posterior à data fim de competência** O campo `start_deferral_date` é posterior ao `end_deferral_date`. ```json { "title": "Start Deferral Date Greater Than End Deferral Date", "description": "The start deferral date {start_date} is greater than the end deferral date {end_date}.", "translation": "A data de início de competência {start_date} é maior que a data de fim de competência {end_date}.", "code": "ESB000033" } ``` ## Próximos passos - Se os documentos foram incluídos na criação (status `pending_adm_approval`): aguarde a análise da QI Tech. - Se os documentos **não** foram incluídos (status `created`): 1. **[Upload de documentos](/documentation/iaas/despesas/submissao_despesa/documentos/upload)** — adicione ao menos um documento antes de submeter. 2. **[Submeter a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** — encaminhe para análise da QI Tech. --- # Listagem de Despesas URL: /documentation/iaas/despesas/submissao_despesa/despesa/listagem Liste as despesas submetidas de um contrato ou de um fundo com filtros opcionais. ## Listar por contrato ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expenses MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `payment_method` | string | opcional | Filtra por método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. | | `payment_date` | string | opcional | Filtra pela data de pagamento no formato `YYYY-MM-DD`. | | `start_deferral_date` | string | opcional | Filtra pela data início de competência no formato `YYYY-MM-DD`. | | `end_deferral_date` | string | opcional | Filtra pela data fim de competência no formato `YYYY-MM-DD`. | | `status` | string | opcional | Filtra por status (`created`, `pending_adm_approval`, `approved`, `rejected`, `canceled`). | | `limit` | integer | opcional | Número de itens por página. Mínimo: `1`. Máximo: `1000`. Padrão: `10`. | | `page` | integer | opcional | Número da página (base zero). Padrão: `0`. | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567", "contract_key": "contrato-auditoria-2026", "status": "approved", "payment_method": "transfer", "start_deferral_date": "2026-06-02", "end_deferral_date": "2026-06-30", "description": "Honorários de auditoria referente ao 1º semestre de 2026", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341" } }, "payment_value": 15000.00, "payment_date": "2026-07-01", "rebate_expense_key": null, "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" } } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de despesas. Cada item segue a estrutura da [consulta individual](/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao). | | `limit` | integer | Número de itens por página utilizado na consulta. | | `page` | integer | Número da página atual. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | --- ## Listar por fundo Para consultar todas as despesas de um fundo, independentemente do contrato: ENDPOINT /expense_submission/fund_class/{fund_class_key}/expenses MÉTODO GET Aceita os mesmos query params da listagem por contrato, com os parâmetros adicionais: | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `rebate` | boolean | opcional | Filtra apenas despesas do tipo rebate (`true`) ou apenas despesas regulares (`false`). | | `description` | string | opcional | Filtra pela descrição da despesa (busca parcial). | ## Possíveis erros STATUS 404 **Fundo ou contrato não encontrado** O `fund_class_key` ou `contract_key` informado não corresponde a nenhum registro cadastrado. ```json { "title": "Contract Not Found", "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.", "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.", "code": "ESB000011" } ``` --- # Consulta de Despesa URL: /documentation/iaas/despesas/submissao_despesa/despesa/recuperacao Recupere os dados e o status atual de uma despesa no fluxo de submissão. :::tip Este endpoint retorna o status da despesa **dentro do processo de submissão** (ex: `created`, `pending_adm_approval`, `approved`). Para consultar despesas já consolidadas no ledger do fundo, utilize a [API de consulta de despesas](/documentation/iaas/despesas/despesa_consolidada/consulta_despesas). ::: ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | | `expense_key` | string | Chave única da despesa (UUID) | ## Response STATUS 200 ```json title="Response Body" { "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567", "contract_key": "contrato-auditoria-2026", "status": "approved", "payment_method": "transfer", "start_deferral_date": "2026-06-02", "end_deferral_date": "2026-06-30", "description": "Honorários de auditoria referente ao 1º semestre de 2026", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341" }, "transfer_type": "wire_transfer", "source_account": { "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e" } }, "payment_value": 15000.00, "payment_date": "2026-07-01", "rebate_expense_key": null, "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" } } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `expense_key` | string | Chave única da despesa (UUID). | | `contract_key` | string | Chave do contrato ao qual a despesa pertence. | | `status` | string | Status atual no fluxo de submissão. Ver tabela de [status da despesa](/documentation/iaas/despesas/submissao_despesa/inicio#status-da-despesa). | | `payment_method` | string | Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. | | `start_deferral_date` | string | Data início de competência no formato `YYYY-MM-DD`. | | `end_deferral_date` | string | Data fim de competência no formato `YYYY-MM-DD`. | | `description` | string | Descrição da despesa. | | `payment` | object | Dados do pagamento conforme cadastrados. | | `payment_value` | number | Valor da despesa. | | `payment_date` | string | Data de pagamento no formato `YYYY-MM-DD`. | | `rebate_expense_key` | string | Chave da despesa original quando se tratar de um rebate, ou `null`. | | `fund_class` | object | Dados do fundo associado. | ## Possíveis erros STATUS 404 **Despesa não encontrada** O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada. ```json { "title": "Expense Not Found", "description": "Expense with key {expense_key} was not found.", "translation": "A despesa com chave {expense_key} não foi encontrada.", "code": "ESB000016" } ``` --- # Submissão da Despesa URL: /documentation/iaas/despesas/submissao_despesa/despesa/submissao Encaminhe uma despesa para análise da QI Tech. A submissão só é necessária quando a despesa foi criada **sem documentos** — caso contrário, a despesa já é automaticamente encaminhada durante a criação. :::caution Atenção - É obrigatório ter ao menos um documento anexado à despesa antes de submeter. - Somente despesas no status `created` podem ser submetidas por este endpoint. Despesas que já passaram pela criação com documentos estarão no status `pending_adm_approval` e não precisam ser submetidas novamente. ::: ## Request ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/submit MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | | `expense_key` | string | Chave única da despesa (UUID) | Este endpoint não requer body na requisição. ## Response STATUS 200 ```json title="Response Body" { "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567", "contract_key": "contrato-auditoria-2026", "status": "pending_adm_approval", "payment_method": "transfer", "start_deferral_date": "2026-06-02", "end_deferral_date": "2026-06-30", "description": "Honorários de auditoria referente ao 1º semestre de 2026", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341" }, "transfer_type": "wire_transfer", "source_account": { "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e" } }, "payment_value": 15000.00, "payment_date": "2026-07-01", "rebate_expense_key": null, "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" } } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Novo status da despesa. Sempre retorna `pending_adm_approval` após a submissão bem-sucedida. | Os demais campos seguem a mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-da-resposta). ## Possíveis erros STATUS 404 **Despesa não encontrada** O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada. ```json { "title": "Expense Not Found", "description": "Expense with key {expense_key} was not found.", "translation": "A despesa com chave {expense_key} não foi encontrada.", "code": "ESB000016" } ``` STATUS 400 **Despesa sem documentos** Não há documentos anexados à despesa. Faça o [upload de ao menos um documento](/documentation/iaas/despesas/submissao_despesa/documentos/upload) antes de submeter. ```json { "title": "Submission Must Have At Least One Pending Analysis Document", "description": "Expense {expense_key} must have at least one document in pending_adm_approval or approved status.", "translation": "A despesa {expense_key} deve ter ao menos um documento em status pending_adm_approval ou approved.", "code": "ESB000025" } ``` **Transição de status inválida** A despesa não está no status `created` e não pode ser submetida por este endpoint. ```json { "title": "Cannot Update Expense In This Status", "description": "Expense {expense_key} cannot be updated with status {current_status}.", "translation": "A despesa {expense_key} não pode ser atualizada com o status {current_status}.", "code": "ESB000023" } ``` ## Próximos passos Após submeter a despesa, aguarde a análise da QI Tech. Você pode acompanhar o status via: **[Consultar a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao)** — verifique o status atual da despesa. --- # Listagem de Documentos URL: /documentation/iaas/despesas/submissao_despesa/documentos/listagem Liste todos os documentos vinculados a uma despesa ou a um contrato. --- ## Listar documentos de uma despesa ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/documents MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | | `expense_key` | string | Chave única da despesa (UUID) | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "name": "NF-e 001234 - Auditoria jun/2026", "expense_document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567", "document_type": "invoice", "status": "approved" }, { "name": "Memória de Cálculo - jun/2026", "expense_document_key": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12", "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567", "document_type": "calculation_memory", "status": "pending_adm_approval" } ] } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de documentos. | | `data[].name` | string | Nome do documento. | | `data[].expense_document_key` | string | Chave única do documento (UUID). | | `data[].expense_key` | string | Chave da despesa à qual o documento pertence. | | `data[].document_type` | string | Tipo do documento: `invoice`, `calculation_memory`, `contract` ou `bank_slip`. | | `data[].status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. | --- ## Listar documentos de um contrato ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/documents MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "name": "Contrato de Prestação de Serviços - Auditoria 2026", "contract_document_key": "f6a7b8c9-d0e1-2345-fa67-890abcdef123", "contract_key": "contrato-auditoria-2026", "document_type": "contract", "status": "approved" } ] } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de documentos. | | `data[].name` | string | Nome do documento. | | `data[].contract_document_key` | string | Chave única do documento de contrato (UUID). | | `data[].contract_key` | string | Chave do contrato ao qual o documento pertence. | | `data[].document_type` | string | Tipo do documento. | | `data[].status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. | ## Possíveis erros STATUS 404 **Despesa ou contrato não encontrado** As chaves informadas na URL não correspondem a nenhum registro cadastrado. ```json { "title": "Expense Not Found", "description": "Expense with key {expense_key} was not found.", "translation": "A despesa com chave {expense_key} não foi encontrada.", "code": "ESB000016" } ``` --- # Upload de Documentos URL: /documentation/iaas/despesas/submissao_despesa/documentos/upload Adicione documentos comprobatórios a uma despesa ou contrato. Os documentos passam por análise da QI Tech e são obrigatórios para a submissão da despesa. :::tip Atalho na criação Você pode incluir documentos diretamente no body da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao) — nesse caso, a despesa já entra em `pending_adm_approval` sem precisar chamar este endpoint separadamente. ::: :::info Tipos de documento aceitos - `invoice` — Nota fiscal eletrônica (NF-e) - `calculation_memory` — Memória de cálculo ou planilha de apuração - `contract` — Contrato do serviço prestado - `bank_slip` — Boleto bancário ::: --- ## Upload de documento em despesa ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/document MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | | `expense_key` | string | Chave única da despesa (UUID) | ```json title="Request Body" { "name": "NF-e 001234 - Auditoria jun/2026", "document_type": "invoice", "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..." } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do documento. Máximo de 255 caracteres. | | `document_type` | string | obrigatório | Tipo do documento: `invoice`, `calculation_memory`, `contract` ou `bank_slip`. | | `document_b64` | string | obrigatório | Conteúdo do arquivo codificado em Base64. | ## Response STATUS 201 ```json title="Response Body" { "name": "NF-e 001234 - Auditoria jun/2026", "expense_document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567", "document_type": "invoice", "status": "pending_adm_approval" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome do documento. | | `expense_document_key` | string | Chave única do documento (UUID). | | `expense_key` | string | Chave da despesa à qual o documento pertence. | | `document_type` | string | Tipo do documento. | | `status` | string | Status inicial do documento. Sempre retorna `pending_adm_approval`. | --- ## Upload de documento em contrato Documentos também podem ser vinculados diretamente ao contrato (ex: o contrato do serviço prestado). ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/document MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID) | | `contract_key` | string | Chave única do contrato | O body e os atributos da resposta seguem a mesma estrutura do upload em despesa, com os campos `contract_document_key` e `contract_key` no lugar de `expense_document_key` e `expense_key`. ```json title="Response Body" { "name": "Contrato de Prestação de Serviços - Auditoria 2026", "contract_document_key": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12", "contract_key": "contrato-auditoria-2026", "document_type": "contract", "status": "pending_adm_approval" } ``` --- ## Consultar documento por chave Recupere os dados de um documento e acesse o link para download do arquivo. ### Documento de despesa ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/document/{document_key} MÉTODO GET ```json title="Response Body" { "name": "NF-e 001234 - Auditoria jun/2026", "expense_document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567", "document_type": "invoice", "status": "approved", "document_url": "https://storage.example.com/documents/NF-001234.pdf?X-Amz-Expires=3600&..." } ``` | Campo | Tipo | Descrição | |---|---|---| | `document_url` | string | URL pré-assinada para download do arquivo. Válida por tempo limitado. | | `status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. | ## Possíveis erros STATUS 404 **Despesa não encontrada** O conjunto de chaves na URL não corresponde a nenhuma despesa cadastrada. ```json { "title": "Expense Not Found", "description": "Expense with key {expense_key} was not found.", "translation": "A despesa com chave {expense_key} não foi encontrada.", "code": "ESB000016" } ``` **Documento não encontrado** O `document_key` informado não corresponde a nenhum documento cadastrado para esta despesa. ```json { "title": "Document Not Found", "description": "Document with key {document_key} was not found.", "translation": "O documento com chave {document_key} não foi encontrado.", "code": "ESB000015" } ``` STATUS 400 **Formato do documento inválido** O conteúdo em `document_b64` não é um Base64 válido ou o formato do arquivo não é suportado. ```json { "title": "Invalid Document Format", "description": "The document format is invalid.", "translation": "Formato do documento invalido.", "code": "ESB000014" } ``` ## Próximos passos Com ao menos um documento em `pending_adm_approval` ou `approved`, a despesa está pronta para ser submetida: **[Submeter a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** — encaminhe para análise da QI Tech. --- # Fluxo de submissão de despesas URL: /documentation/iaas/despesas/submissao_despesa/fluxo_despesas Esta página oferece uma visão holística do fluxo de submissão de despesas: desde a criação do contrato até a aprovação das despesas individuais pela QI Tech. Acompanhe a evolução dos **status do contrato**, dos **status de cada despesa** e as ações esperadas em cada etapa. :::tip Como usar este fluxograma Passe o mouse sobre cada etapa para ver os detalhes do endpoint e acessar a documentação completa. As trilhas coloridas mostram simultaneamente o que acontece com o contrato e com cada despesa. ::: {` .cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px} .cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600} .cf-legend-dot{width:12px;height:12px;border-radius:3px} .cf-step{position:relative;margin-bottom:4px} .cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)} .cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))} .cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)} .cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap} .cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0} .cf-num-int{background:#3b82f6} .cf-num-qi{background:#8b5cf6} .cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)} .cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto} .cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb} .cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed} .cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px} .cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px} .cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid} .cf-track-contrato{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)} .cf-track-despesa{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)} .cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)} .cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em} .cf-new{font-weight:700} .cf-unchanged{opacity:0.5} .cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px} .cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)} .cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap} .cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem} .cf-method-post{background:#f97316;color:#fff} .cf-method-put{background:#3b82f6;color:#fff} .cf-method-get{background:#22c55e;color:#fff} .cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px} .cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none} .cf-link:hover{text-decoration:underline} .cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap} .cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed} .cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)} .cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)} .cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px} .cf-branch-label-ok{color:#16a34a} .cf-branch-label-err{color:#dc2626} html[data-theme='dark'] .cf-track-contrato{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)} html[data-theme='dark'] .cf-track-despesa{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)} html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)} html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)} html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)} html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa} html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa} `} ## Legenda Agente Integrador QI Tech (análise manual) Status do Contrato Status da Despesa ## Fluxograma 1 Criação do contrato Agente Integrador Cria um contrato vinculando o fundo a um fornecedor e definindo o tipo de despesa ( expense_type ) e a natureza de submissão ( submission_nature ). Contrato: created POST /expense_submission/fund_class/{fund_class_key}/contract O contrato fica pronto para ser atualizado ou submetido para aprovação. Ver documentação completa → 2 Submissão do contrato para aprovação Agente Integrador Sinaliza que o contrato está pronto para análise da QI Tech. Após a submissão, o contrato não pode mais ser editado. Contrato: pending_adm_approval PUT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/submit O contrato aguarda revisão manual pela equipe da QI Tech. Ver documentação completa → 3 Análise e aprovação do contrato QI Tech A equipe da QI Tech analisa o contrato. Em caso de dúvidas, podem criar anotações que o agente integrador poderá responder. Contrato aprovado approved Despesas podem ser criadas e submetidas. Contrato rejeitado rejected Nenhuma despesa poderá ser criada neste contrato. Use o endpoint de consulta para acompanhar o status do contrato. GET /expense_submission/fund_class/{fund_class_key}/contract/{contract_key} Ver documentação completa → 4 Criação da despesa Agente Integrador Cria uma despesa individual sob o contrato aprovado, informando dados de pagamento, período de competência e documentos comprobatórios. Ao incluir documentos na criação, a despesa é automaticamente encaminhada para revisão. Contrato: approved Despesa: created → pending_adm_approval* POST /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense *Se documentos forem incluídos no body da criação, a despesa vai diretamente para pending_adm_approval . Caso contrário, fica em created . Ver documentação completa → 5 Upload de documentos (quando necessário) Agente Integrador Se os documentos não foram enviados na criação da despesa, faça o upload separadamente antes de submeter. Ao menos um documento é obrigatório para submissão. Despesa: created POST /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/document Envie os documentos comprobatórios (NF, memória de cálculo, contrato ou boleto) em Base64. Ver documentação completa → 6 Submissão da despesa para aprovação Agente Integrador Encaminha a despesa para análise da QI Tech. Obrigatório ter ao menos um documento anexado. Despesa: pending_adm_approval PUT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/submit Somente aplicável quando a despesa foi criada sem documentos ( status = created ). Caso contrário, a despesa já estará em pending_adm_approval . Ver documentação completa → 7 Análise e aprovação da despesa QI Tech A QI Tech analisa os dados de pagamento e os documentos comprobatórios. Após aprovação, a despesa é processada internamente e registrada na carteira do fundo. Despesa aprovada approved Despesa registrada. Fluxo encerrado com sucesso. Despesa rejeitada rejected Verifique as anotações da QI Tech para entender o motivo da rejeição. Use o endpoint de consulta para acompanhar o status da despesa. GET /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key} Ver documentação completa → --- # Anotações da Análise URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes Durante a revisão, a equipe da QI Tech pode abrir **anotações** — solicitações de esclarecimento ou correção sobre os dados do fornecedor ou os documentos enviados. O agente integrador deve responder a essas anotações para que a análise prossiga. :::info Status das anotações | Status | Descrição | |---|---| | `created` | Anotação criada pela QI Tech | | `opened` | Anotação aberta, aguardando resposta | | `closed` | Anotação respondida ou encerrada | ::: --- ## Listar anotações de uma análise ENDPOINT /vendor_registry/analysis/{analysis_key}/annotations MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `status` | string (lista) | opcional | Filtra anotações pelo status. Valores: `created`, `opened`, `closed`. Aceita múltiplos valores. | | `limit` | integer | opcional | Número de itens por página. Mínimo: `0`. Máximo: `1000`. Padrão: `10`. | | `page` | integer | opcional | Número da página (base zero). Padrão: `0`. | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "annotation_key": "f6a7b8c9-d0e1-2345-f678-90abcdef1234", "annotation_message": "Por favor, envie o contrato social atualizado com as últimas alterações societárias.", "annotation_response": null, "annotation_datetime": "2026-06-10 14:32:00", "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "opened" } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de anotações. | | `limit` | integer | Número de itens por página utilizado na consulta. | | `page` | integer | Número da página atual. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada anotação em `data` | Campo | Tipo | Descrição | |---|---|---| | `annotation_key` | string | Chave única da anotação (UUID). | | `annotation_message` | string | Mensagem da anotação criada pela QI Tech. | | `annotation_response` | string \| null | Resposta do agente integrador, ou `null` se ainda não respondida. | | `annotation_datetime` | string | Data e hora em que a anotação foi criada. | | `analysis_key` | string | Chave da análise à qual a anotação pertence. | | `status` | string | Status da anotação: `created`, `opened` ou `closed`. | --- ## Consultar anotação por chave ENDPOINT /vendor_registry/analysis/{analysis_key}/annotation/{annotation_key} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | | `annotation_key` | string | Chave única da anotação (UUID) | ## Response STATUS 200 ```json title="Response Body" { "annotation_key": "f6a7b8c9-d0e1-2345-f678-90abcdef1234", "annotation_message": "Por favor, envie o contrato social atualizado com as últimas alterações societárias.", "annotation_response": null, "annotation_datetime": "2026-06-10 14:32:00", "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "opened" } ``` --- ## Responder a uma anotação ENDPOINT /vendor_registry/analysis/{analysis_key}/annotation/{annotation_key}/respond MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | | `annotation_key` | string | Chave única da anotação (UUID) | ```json title="Request Body" { "annotation_response": "O contrato social atualizado foi enviado no documento 'Contrato Social - AUDITORES EXEMPLO S.A.'." } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `annotation_response` | string | obrigatório | Resposta à anotação. Máximo de 200 caracteres. | ## Response STATUS 202 ```json title="Response Body" { "annotation_key": "f6a7b8c9-d0e1-2345-f678-90abcdef1234", "annotation_message": "Por favor, envie o contrato social atualizado com as últimas alterações societárias.", "annotation_response": "O contrato social atualizado foi enviado no documento 'Contrato Social - AUDITORES EXEMPLO S.A.'.", "annotation_datetime": "2026-06-10 14:32:00", "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "closed" } ``` --- ## Possíveis erros STATUS 404 **Anotação não encontrada** A `annotation_key` informada na URL não corresponde a nenhuma anotação desta análise. ```json { "title": "Annotation not found", "description": "Annotation with the key {annotation_key} was not found.", "translation": "A anotação com a chave {annotation_key} não foi encontrada.", "code": "VRG0000012" } ``` STATUS 409 **Anotação já respondida** A anotação informada já possui uma resposta registrada. ```json { "title": "Annotation Already Responded", "description": "Annotation with key {annotation_key} is already responded.", "translation": "Anotação com chave {annotation_key} está respondida.", "code": "VRG0000013" } ``` --- ## Próximos passos Após responder às anotações, aguarde a QI Tech retomar a análise. Acompanhe o status via: **[Consultar análise por chave](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem#consultar-análise-por-chave)** — monitore o andamento da análise. --- # Atualização de Dados da Análise URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao Enquanto a análise estiver no status `pending_submission`, é possível atualizar os dados de pagamento e a flag `requires_invoice`. Após submeter para `pending_adm_approval`, a edição não é mais permitida. :::caution Restrição de status Este endpoint só aceita atualizações quando a análise está no status `pending_submission`. Se a análise foi retornada pela QI Tech para este status, também é possível editar antes de reenviar. ::: --- ## Request ENDPOINT /vendor_registry/analysis/{analysis_key}/update MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | ```json title="Request Body" { "requires_invoice": false, "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_pix_key": "12345678000190", "transfer_type": "pix" } } ``` ### Atributos do body Ao menos um campo deve ser informado. | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `requires_invoice` | boolean | opcional | Indica se esta análise exige nota fiscal. | | `payment_method` | string | opcional | Método de pagamento padrão. Atualmente suporta apenas `transfer`. Obrigatório quando `payment` é informado. | | `payment` | object | opcional | Dados bancários do fornecedor. Consulte os [atributos de `payment`](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao#atributos-de-payment). Obrigatório quando `payment_method` é informado. | :::info Limpeza dos dados de pagamento Se apenas um dos campos `payment` ou `payment_method` for informado (sem o outro), ambos serão removidos da análise. ::: --- ## Response STATUS 200 ```json title="Response Body" { "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "pending_submission", "requires_invoice": false, "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": true, "status": "pending_analysis" }, "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_pix_key": "12345678000190", "transfer_type": "pix" } } ``` --- ## Possíveis erros STATUS 409 **Análise não editável** A análise está em um status que não permite edição. Somente análises no status `pending_submission` podem ser editadas via este endpoint. ```json { "title": "Analysis Not Editable", "description": "Analysis with key {analysis_key} is on status '{current_status}' and cannot be edited.", "translation": "A análise com chave {analysis_key} está no status '{current_status}' e não pode ser editada.", "code": "VRG000032" } ``` STATUS 404 **Análise não encontrada** A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada. ```json { "title": "Analysis not found", "description": "Analysis with the key {analysis_key} was not found.", "translation": "A análise com a chave {analysis_key} não foi encontrada.", "code": "VRG000007" } ``` --- ## Próximos passos Após atualizar os dados, prossiga para: **[Submeter a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)** — encaminhe para revisão da QI Tech. --- # Cancelamento da Análise URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento Cancele uma análise de cadastro de fornecedor que ainda esteja em andamento. Após o cancelamento, nenhuma alteração adicional pode ser feita nessa análise. :::info Quando é possível cancelar O cancelamento está disponível enquanto a análise estiver nos status `pending_submission` ou `pending_adm_approval`. Análises já `approved`, `rejected` ou `canceled` não podem ser canceladas. ::: --- ## Request ENDPOINT /vendor_registry/analysis/{analysis_key}/cancel MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | Este endpoint não requer body. ## Response STATUS 202 ```json title="Response Body" { "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "canceled" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise. | | `status` | string | Novo status da análise. Sempre retorna `canceled`. | --- ## Possíveis erros STATUS 409 **Transição de status não permitida** A análise está em um status que não permite cancelamento (por exemplo, já foi aprovada ou rejeitada). ```json { "title": "Analysis Status Transition Denied", "description": "Analysis with key {analysis_key} is not allowed to switch status from {current_status} to canceled.", "translation": "Análise com chave {analysis_key} não pode trocar de status de {current_status} para canceled.", "code": "VRG000008" } ``` STATUS 404 **Análise não encontrada** A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada. ```json { "title": "Analysis not found", "description": "Analysis with the key {analysis_key} was not found.", "translation": "A análise com a chave {analysis_key} não foi encontrada.", "code": "VRG000007" } ``` --- ## Próximos passos Para cadastrar o fornecedor novamente, inicie um novo processo via: **[Criação de análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao)** — submeta os dados do fornecedor novamente. --- # Cadastro de Fornecedor URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/criacao O cadastro de fornecedores é o **pré-requisito** para a criação de contratos de despesa. O processo é realizado pelo próprio agente integrador via API e passa por análise e aprovação da QI Tech antes de o fornecedor ser ativado na plataforma. :::info Fluxo de cadastro O cadastro de um fornecedor segue as seguintes etapas: 1. **Criação da análise** — envio dos dados do fornecedor (esta página) 2. **Upload de documentos** — anexar documentos comprobatórios 3. **Submissão para revisão** — encaminhar para análise da QI Tech 4. **Resposta a anotações** (se solicitado) — responder às solicitações da equipe de análise 5. **Aprovação** — o fornecedor é ativado e a `vendor_key` fica disponível para uso em contratos Para detalhes sobre as etapas seguintes, consulte: - [Upload de documentos](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos) - [Submissão para análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao) - [Anotações](/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes) ::: --- ## Request ENDPOINT /vendor_registry/analysis MÉTODO POST ```json title="Request Body" { "vendor_document_number": "12.345.678/0001-90", "vendor_name": "AUDITORES EXEMPLO S.A.", "requires_invoice": true, "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341" } } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `vendor_document_number` | string | obrigatório | CPF ou CNPJ do fornecedor com pontuação. Mínimo 14, máximo 18 caracteres. | | `vendor_name` | string | obrigatório | Nome completo do fornecedor. Máximo de 255 caracteres. | | `requires_invoice` | boolean | opcional | Indica se o fornecedor exige nota fiscal para pagamento. Padrão: `false`. | | `payment_method` | string | opcional | Método de pagamento padrão do fornecedor. Atualmente suporta apenas `transfer`. Obrigatório quando `payment` é informado. | | `payment` | object | opcional | Dados bancários padrão do fornecedor. Ver [Atributos de `payment`](#atributos-de-payment). Obrigatório quando `payment_method` é informado. | #### Atributos de `payment` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `target` | object | obrigatório | Dados do beneficiário do pagamento. | | `target.name` | string | obrigatório | Nome do beneficiário. | | `target.document_number` | string | obrigatório | CPF ou CNPJ do beneficiário com pontuação. | | `target_account` | object | opcional | Dados da conta bancária de destino (TED/DOC). Obrigatório quando `transfer_type` não é informado ou é `wire_transfer`. | | `target_account.account_number` | string | obrigatório | Número da conta (1–20 dígitos, não pode ser zeros). | | `target_account.account_branch` | string | obrigatório | Agência bancária (exatamente 4 dígitos, não pode ser zeros). | | `target_account.account_digit` | string | obrigatório | Dígito verificador da conta (1 dígito). | | `target_account.financial_institution_code` | string | obrigatório | Código do banco (exatamente 3 dígitos, não pode ser zeros). | | `target_account.financial_institution_ispb` | string | opcional | ISPB do banco (exatamente 8 dígitos). Quando não informado, é preenchido automaticamente com base no `financial_institution_code`. | | `target_account.account_type` | string | opcional | Tipo da conta bancária. | | `transfer_type` | string | opcional | Tipo de transferência. Informe `pix` para pagamento via Pix. Quando omitido, o pagamento é via TED/DOC. | | `target_pix_key` | string | opcional | Chave Pix do destinatário (máx. 77 caracteres). Obrigatório quando `transfer_type` é `pix` e `target_account` não é informado. A chave Pix deve pertencer ao CPF/CNPJ de `target.document_number`. | --- ## Response STATUS 201 ```json title="Response Body" { "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "pending_submission", "requires_invoice": true, "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": true, "status": "pending_analysis" }, "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341", "financial_institution_ispb": "60701190" } } } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID). Guarde este valor para as próximas etapas. | | `status` | string | Status inicial da análise. Sempre retorna `pending_submission`. | | `requires_invoice` | boolean | Indica se esta análise exige nota fiscal. | | `manager` | object | Dados do gestor autenticado. | | `manager.name` | string | Nome do gestor. | | `manager.manager_key` | string | Chave única do gestor (UUID). | | `manager.document_number` | string | CNPJ do gestor. | | `vendor` | object | Dados do fornecedor. | | `vendor.vendor_key` | string | Chave única do fornecedor. Disponível após aprovação para uso em contratos. | | `vendor.name` | string | Nome do fornecedor. | | `vendor.document_number` | string | CPF ou CNPJ do fornecedor. | | `vendor.requires_invoice` | boolean | Indica se o fornecedor exige nota fiscal. | | `vendor.status` | string | Status do fornecedor: `pending_analysis` enquanto a análise estiver em curso. | | `payment_method` | string | Método de pagamento, quando informado. | | `payment` | object | Dados bancários, quando informados. | --- ## Possíveis erros STATUS 409 **Fornecedor já ativo** Já existe um fornecedor ativo (`status = active`) com o CNPJ/CPF informado. Utilize a [listagem de fornecedores](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem) para obter a `vendor_key`. ```json { "title": "Vendor already exists", "description": "Already exists an active vendor with the document number {vendor_document_number}.", "translation": "Já existe um fornecedor ativo com o cnpj {vendor_document_number}.", "code": "VRG000015" } ``` STATUS 404 **Gestor não encontrado** O `manager_key` do agente autenticado não corresponde a nenhum gestor cadastrado na plataforma. ```json { "title": "Manager not found", "description": "Manager with the key {manager_key} was not found.", "translation": "O gestor com a chave {manager_key} não foi encontrado.", "code": "VRG000001" } ``` STATUS 400 **Número de documento inválido** O CPF ou CNPJ informado em `vendor_document_number` não é válido. ```json { "title": "Invalid document number", "description": "The document number {vendor_document_number} is invalid.", "translation": "O documento {vendor_document_number} é inválido.", "code": "VRG000002" } ``` --- ## Próximos passos Com a análise criada (status `pending_submission`), as próximas etapas são: 1. **[Upload de documentos](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos)** — anexe o contrato social e documentos dos representantes. 2. **[Submissão para análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)** — encaminhe a análise para revisão da QI Tech. --- # Documentos da Análise URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/documentos Após [criar a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao), faça o upload dos documentos comprobatórios do fornecedor. É obrigatório ter ao menos um documento antes de [submeter a análise para revisão](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao). :::info Tipos de documento aceitos - `vendor_bylaws` — Contrato social do fornecedor - `representative_document` — Documento de identificação do representante legal ::: :::info Status inicial Documentos enviados via API entram automaticamente com status `pending_adm_approval`, aguardando revisão da QI Tech. ::: --- ## Upload de documento ENDPOINT /vendor_registry/analysis/{analysis_key}/document MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | ```json title="Request Body" { "name": "Contrato Social - AUDITORES EXEMPLO S.A.", "document_type": "vendor_bylaws", "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..." } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do documento. Máximo de 255 caracteres. | | `document_type` | string | obrigatório | Tipo do documento: `vendor_bylaws` ou `representative_document`. | | `document_b64` | string | obrigatório | Conteúdo do arquivo codificado em Base64. | ## Response STATUS 201 ```json title="Response Body" { "document_name": "Contrato Social - AUDITORES EXEMPLO S.A.", "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "document_type": "vendor_bylaws", "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "pending_adm_approval" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `document_name` | string | Nome do documento. | | `document_key` | string | Chave única do documento (UUID). | | `document_type` | string | Tipo do documento: `vendor_bylaws` ou `representative_document`. | | `analysis_key` | string | Chave da análise à qual o documento pertence. | | `status` | string | Status do documento. Sempre retorna `pending_adm_approval`. | --- ## Listar documentos de uma análise ENDPOINT /vendor_registry/analysis/{analysis_key}/documents MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "document_name": "Contrato Social - AUDITORES EXEMPLO S.A.", "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "document_type": "vendor_bylaws", "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "pending_adm_approval" }, { "document_name": "RG - João da Silva", "document_key": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12", "document_type": "representative_document", "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "approved" } ] } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de documentos da análise. | | `data[].document_name` | string | Nome do documento. | | `data[].document_key` | string | Chave única do documento (UUID). | | `data[].document_type` | string | Tipo do documento. | | `data[].analysis_key` | string | Chave da análise. | | `data[].status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. | --- ## Consultar documento por chave Recupere os dados de um documento específico, incluindo URL de download. ENDPOINT /vendor_registry/analysis/{analysis_key}/documents/{document_key} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | | `document_key` | string | Chave única do documento (UUID) | ## Response STATUS 200 ```json title="Response Body" { "document_name": "Contrato Social - AUDITORES EXEMPLO S.A.", "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "document_type": "vendor_bylaws", "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "approved", "document_url": "https://storage.example.com/documents/d4e5f6a7-b8c9-0123-def4-567890abcdef?X-Amz-Expires=86400&..." } ``` ### Atributos adicionais | Campo | Tipo | Descrição | |---|---|---| | `document_url` | string | URL pré-assinada para download do arquivo. Válida por 24 horas. | --- ## Possíveis erros STATUS 404 **Análise não encontrada** A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada. ```json { "title": "Analysis not found", "description": "Analysis with the key {analysis_key} was not found.", "translation": "A análise com a chave {analysis_key} não foi encontrada.", "code": "VRG000007" } ``` **Documento não encontrado** A `document_key` informada na URL não corresponde a nenhum documento desta análise. ```json { "title": "Document not found", "description": "Document with the key {document_key} was not found.", "translation": "O documento com a chave {document_key} não foi encontrada.", "code": "VRG000003" } ``` STATUS 400 **Formato do documento inválido** O conteúdo em `document_b64` não é um Base64 válido. ```json { "title": "Invalid document format", "description": "Invalid Document format", "translation": "Formato do documento invalido", "code": "VRG000004" } ``` --- ## Próximos passos Com ao menos um documento enviado, prossiga para: **[Submeter a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)** — encaminhe para revisão da QI Tech. --- # Consulta de Fornecedores e Análises URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/listagem Recupere os fornecedores ativos e acompanhe o andamento das análises de cadastro em curso. --- ## Listar fornecedores ENDPOINT /vendor_registry/vendors MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | opcional | Filtra fornecedores cujo nome contenha o valor informado (busca parcial, sem distinção de maiúsculas/minúsculas). | | `document_number` | string | opcional | Filtra pelo CPF ou CNPJ exato do fornecedor. | | `status` | string (lista) | opcional | Filtra pelo status do fornecedor. Valores: `pending_analysis`, `active`, `inactive`. Aceita múltiplos valores. | | `limit` | integer | opcional | Número de itens por página. Mínimo: `0`. Máximo: `1000`. Padrão: `10`. | | `page` | integer | opcional | Número da página (base zero). Padrão: `0`. | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": true, "status": "active", "payment_method": "transfer" }, { "vendor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "CVM", "document_number": "29.507.878/0001-08", "requires_invoice": true, "status": "active" } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de fornecedores. | | `limit` | integer | Número de itens por página utilizado na consulta. | | `page` | integer | Número da página atual. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada fornecedor em `data` | Campo | Tipo | Descrição | |---|---|---| | `vendor_key` | string | Chave única do fornecedor. Use este valor na criação de contratos. | | `name` | string | Nome do fornecedor. | | `document_number` | string | CPF ou CNPJ do fornecedor. | | `requires_invoice` | boolean | Indica se o fornecedor exige nota fiscal. | | `status` | string | Status do fornecedor: `pending_analysis`, `active` ou `inactive`. | | `payment_method` | string | Método de pagamento padrão, quando cadastrado. | | `payment` | object | Dados bancários padrão, quando cadastrados. | #### Status do fornecedor | Status | Descrição | |---|---| | `pending_analysis` | Fornecedor com análise de cadastro em andamento | | `active` | Fornecedor aprovado e disponível para uso em contratos | | `inactive` | Fornecedor inativo | --- ## Consultar fornecedor por chave ENDPOINT /vendor_registry/vendor/{vendor_key} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `vendor_key` | string | Chave única do fornecedor (UUID, 36 caracteres) | ## Response STATUS 200 ```json title="Response Body" { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": true, "status": "active", "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341", "financial_institution_ispb": "60701190" } } } ``` ## Possíveis erros STATUS 404 **Fornecedor não encontrado** A `vendor_key` informada não corresponde a nenhum fornecedor cadastrado. ```json { "title": "Vendor not found", "description": "Vendor with the key {vendor_key} was not found.", "translation": "O fornecedor com a chave {vendor_key} não foi encontrada.", "code": "VRG000014" } ``` --- ## Listar análises ENDPOINT /vendor_registry/analyses MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `status` | string (lista) | opcional | Filtra pelo status da análise. Valores: `pending_submission`, `pending_adm_approval`, `approved`, `rejected`, `canceled`, `other_analysis_approved`. Aceita múltiplos valores. | | `manager_key` | string | opcional | Filtra as análises de um gestor específico. | | `vendor_key` | string | opcional | Filtra as análises de um fornecedor específico. | | `limit` | integer | opcional | Número de itens por página. Mínimo: `0`. Máximo: `1000`. Padrão: `10`. | | `page` | integer | opcional | Número da página (base zero). Padrão: `0`. | ## Response STATUS 200 ```json title="Response Body" { "data": [ { "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "pending_adm_approval", "requires_invoice": true, "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": true, "status": "pending_analysis" } } ], "limit": 10, "page": 0, "is_last_page": true } ``` --- ## Consultar análise por chave ENDPOINT /vendor_registry/analysis/{analysis_key} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | ## Response STATUS 200 ```json title="Response Body" { "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "pending_adm_approval", "requires_invoice": true, "manager": { "name": "EXEMPLO GESTORA LTDA", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90", "requires_invoice": true, "status": "pending_analysis" }, "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "12.345.678/0001-90" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341", "financial_institution_ispb": "60701190" } } } ``` ## Possíveis erros STATUS 404 **Análise não encontrada** A `analysis_key` informada não corresponde a nenhuma análise cadastrada. ```json { "title": "Analysis not found", "description": "Analysis with the key {analysis_key} was not found.", "translation": "A análise com a chave {analysis_key} não foi encontrada.", "code": "VRG000007" } ``` --- ## Próximos passos Com a `vendor_key` de um fornecedor `active` em mãos, prossiga para: **[Criar contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao)** — vincule o fornecedor ao fundo e defina o tipo de despesa. --- # Submissão para Análise URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/submissao Após [criar a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao) e [fazer upload dos documentos](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos), submeta a análise para revisão da QI Tech alterando o status para `pending_adm_approval`. :::caution Pré-requisito É obrigatório ter ao menos um documento com status `pending_adm_approval` ou `approved` antes de submeter a análise. Caso contrário, a requisição será rejeitada com erro `VGR000030`. ::: --- ## Submeter a análise ENDPOINT /vendor_registry/analysis/{analysis_key} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise (UUID) | ```json title="Request Body" { "status": "pending_adm_approval" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Valores aceitos | Descrição | |---|---|---|---|---| | `status` | string | obrigatório | `pending_adm_approval`, `pending_submission` | Novo status da análise. Use `pending_adm_approval` para submeter para revisão, ou `pending_submission` para retornar ao rascunho. | ## Response STATUS 202 ```json title="Response Body" { "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "pending_adm_approval" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `analysis_key` | string | Chave única da análise. | | `status` | string | Novo status da análise. | --- ## Ciclo de vida da análise A tabela abaixo descreve todas as transições de status possíveis e quem as executa: | Status | Descrição | Quem transita | |---|---|---| | `pending_submission` | Análise criada, aguardando submissão | Estado inicial; agente retorna para edição | | `pending_adm_approval` | Submetida, aguardando revisão da QI Tech | Agente integrador | | `approved` | Aprovada pela QI Tech; fornecedor ativado | QI Tech (interno) | | `rejected` | Rejeitada pela QI Tech | QI Tech (interno) | | `canceled` | Cancelada pelo agente integrador | Agente integrador via [endpoint de cancelamento](/documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento) | | `other_analysis_approved` | Outra análise do mesmo fornecedor foi aprovada primeiro | Automático | ### Transições permitidas pelo agente integrador ``` pending_submission ──→ pending_adm_approval (submissão para revisão) pending_submission ──→ canceled (cancelamento) pending_adm_approval ──→ pending_submission (retorno para edição) pending_adm_approval ──→ canceled (cancelamento) ``` :::info Edição após retorno Quando a QI Tech retorna a análise para `pending_submission`, é possível atualizar os dados de pagamento e a flag `requires_invoice` antes de submeter novamente. Consulte a página de [atualização de dados](/documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao). ::: --- ## Possíveis erros STATUS 400 **Análise sem documentos** A análise não possui nenhum documento com status `pending_adm_approval` ou `approved`. Faça o [upload de ao menos um documento](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos) antes de submeter. ```json { "title": "Analysis Submission Must Have At Least One Pending Analysis Document", "description": "Analysis with key {analysis_key} must have at least one pending analysis document to be submitted.", "translation": "A análise com a chave {analysis_key} deve ter pelo menos um documento de análise pendente para ser enviada.", "code": "VGR000030" } ``` STATUS 409 **Transição de status não permitida** A transição de status solicitada não é permitida para o status atual da análise. ```json { "title": "Analysis Status Transition Denied", "description": "Analysis with key {analysis_key} is not allowed to switch status from {current_status} to {new_status}.", "translation": "Análise com chave {analysis_key} não pode trocar de status de {current_status} para {new_status}.", "code": "VRG000008" } ``` **Análise já rejeitada** Análises rejeitadas não podem ter o status alterado. ```json { "title": "Canceled Analysis", "description": "Analysis with key {analysis_key} is already rejected, it can't be updated.", "translation": "Análise com chave {analysis_key} está rejeitada, não pode ser atualizada.", "code": "VRG0000009" } ``` **Análise já aprovada** Análises aprovadas não podem ter o status alterado. ```json { "title": "Completed Analysis", "description": "Analysis with key {analysis_key} is already completed, it can't be updated.", "translation": "Análise com chave {analysis_key} está finalizada, não pode ser atualizada.", "code": "VRG0000010" } ``` STATUS 404 **Análise não encontrada** A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada. ```json { "title": "Analysis not found", "description": "Analysis with the key {analysis_key} was not found.", "translation": "A análise com a chave {analysis_key} não foi encontrada.", "code": "VRG000007" } ``` --- ## Próximos passos Após submeter a análise, o processo de revisão da QI Tech se inicia. Durante este período: - **[Acompanhar o status](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem#consultar-análise-por-chave)** — verifique o progresso da análise. - **[Responder anotações](/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes)** — responda eventuais solicitações da equipe de análise. Após aprovação, a `vendor_key` do fornecedor estará disponível para uso em contratos de despesa. --- # Submissão de Despesas URL: /documentation/iaas/despesas/submissao_despesa/inicio Esta seção documenta as APIs que viabilizam o processo de Submissão de Despesas para Fundos de Investimento administrados pela QI CTVM. Por meio dessas APIs, é possível registrar contratos com fornecedores, submeter despesas individuais e acompanhar o ciclo de aprovação de cada lançamento. ## Fluxo de submissão O diagrama abaixo ilustra as etapas do fluxo: ![Etapas do fluxo de submissão de despesas](/img/diagrams/iaas-despesas-inicio.svg) ## Passo a passo ### 0. Cadastro do Fornecedor (pré-requisito) Antes de criar um contrato, o fornecedor que prestará serviços ao fundo deve estar cadastrado na plataforma. Esse cadastro é realizado pela equipe de operações da QI Tech. Após o cadastro, a `vendor_key` é disponibilizada para uso nos contratos. **[Acessar documentação do cadastro de fornecedor](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao)** | **[Consultar fornecedores cadastrados](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem)** ### 1. Criação do Contrato Crie um contrato vinculando o fundo a um fornecedor e definindo o tipo de despesa. O contrato é o contêiner que agrupa todas as despesas de uma mesma relação comercial. **[Acessar documentação da criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao)** ### 2. Submissão do Contrato para Aprovação Após criar e revisar o contrato, submeta-o para análise da QI Tech. O contrato passará para o status `pending_adm_approval` até ser aprovado ou rejeitado. **[Acessar documentação da submissão do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/submissao)** ### 3. Criação da Despesa Com o contrato aprovado, crie as despesas individuais informando os dados de pagamento, período de competência e documentos comprobatórios. Ao incluir documentos na criação, a despesa é automaticamente encaminhada para revisão. **[Acessar documentação da criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao)** ### 4. Upload de Documentos (quando não incluídos na criação) Caso os documentos não tenham sido incluídos na criação da despesa, faça o upload separadamente antes de submeter. **[Acessar documentação de upload de documentos](/documentation/iaas/despesas/submissao_despesa/documentos/upload)** ### 5. Submissão da Despesa para Aprovação Submeta a despesa para análise da QI Tech. É obrigatório que ao menos um documento esteja anexado antes da submissão. **[Acessar documentação da submissão da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** :::info Processamento interno Após a aprovação da despesa pela QI Tech, o lançamento é processado internamente e registrado na carteira do fundo de forma automática. ::: ## Status do contrato | Status | Descrição | |---|---| | `created` | Contrato criado, aguardando submissão | | `pending_adm_approval` | Submetido, aguardando análise da QI Tech | | `approved` | Aprovado pela QI Tech | | `rejected` | Rejeitado pela QI Tech | | `canceled` | Cancelado pelo agente integrador | ## Status da despesa | Status | Descrição | |---|---| | `created` | Despesa criada, aguardando documentos ou submissão | | `pending_adm_approval` | Submetida (ou criada com documentos), aguardando análise da QI Tech | | `approved` | Aprovada pela QI Tech | | `rejected` | Rejeitada pela QI Tech | | `canceled` | Cancelada pelo agente integrador | --- # Emissões - Integralização URL: /documentation/iaas/emissoes/cadastrar_boleta --- ## Integralização Utilizando o endpoint a seguir, é possível iniciar a integralização em uma emissão. ### Request ENDPOINT /trade_security/fund_class/FUND_CLASS_KEY/integralization MÉTODO POST ```json title="Request Body" { "security_external_id": "a23c006c-befd-40e0-bc3d-fbd2dfbbea5d", "bookkeeper_document_number": "00.000.000/0000-00", "security_key": "272a394a-e3d0-4484-b00e-e18a4e22bb5e", "unit_price": "2.00", "number_of_units": "100.00", "external_id": "90b679c0-2674-4cad-917a-5c786b0bf992", "integralization_date": "2025-05-27", "payment": { "target_account": { "account_branch": "0001", "account_digit": "0", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "32402502" } } } ``` ### Definições #### Operação de Compra | Campo | Tipo | Descrição | Obrigatório | | ------------------------------| ------ | ------------------------------------------------ | ----------- | | `security_external_id` | string | Identificador externo do ativo | Sim* | | `bookkeeper_document_number` | string | Número do CNPJ do escriturador | Sim* | | `security_key` | string | Chave interna do ativo | Sim* | | `unit_price` | float | Valor unitário na integralização | Sim | | `number_of_units` | float | Número de unidades compradas | Sim | | `external_id` | string | Identificador externo da operação de compra | Sim | | `integralization_date` | string | Data da integralização | Sim | | `payment` | dict | Objeto de [pagamento](#pagamento) para liquidação| Sim | :::note ⚠️ **Importante** ( * ) A identificação do ativo estruturado pode ser feita de duas formas: 1. Informando o campo `security_key` **(chave interna)**; **ou** 2. Informando **ambos** os campos `security_external_id` e `bookkeeper_document_number`. Pelo menos **uma das formas de identificação** deve estar presente no payload. Caso ambas estejam presentes, será considerada a chave interna como prioritária. ::: ##### Pagamento | Campo | Tipo | Descrição | Obrigatório | | ---------------------------- | ------ | --------------------------------------------------- | ----------- | | `target_account` | string | Objeto de [conta bancária](#conta-bancária) para liquidação | Sim | ##### Conta bancária | Campo | Tipo | Descrição | Obrigatório | | ---------------------------- | ------ | --------------------------------------------------- | ----------- | | `account_branch` | string | Agência da conta bancária | Sim | | `account_digit` | string | Dígito verificador da conta | Sim | | `account_number` | string | Número da conta bancária | Sim | | `financial_institution_code` | string | Código da instituição financeira | Sim | | `financial_institution_ispb` | string | Código ISPB da instituição financeira | Sim | ### Response STATUS 201 ```json title='Response Body' { "integralization_key": "1568b67b-088e-43be-938b-0f817b805f7a", "external_id": "90b679c0-2674-4cad-917a-5c786b0bf992", "status": "pending_administrator_approval", } ``` --- # Cadastro de Ativos - Emissões URL: /documentation/iaas/emissoes/cadastro_ativo --- ## Criação - Nota Comercial Utilizando o endpoint a seguir, é possível cadastrar uma nova nota no orquestrador de ativos estruturados. Os ativos cadastrados surgem no status **pre_operational** para que sejam submetidos os documentos relacionados ao ativo. Deste modo, é possível pré cadastrar um ativo e habilitá-lo para operação somente após as devidas formalizações estarem concluídas, como detalhado no próximo segmento. A seguir consta uma listagem explicativa dos campos, e o detalhamento de suas obrigatoriedades e tipos. ### Request ENDPOINT /security/security MÉTODO POST ```json title='Request Body' { "external_id": "string", "asset_type": "commercial_paper", "b3_code":"25M000000", "isin_code":"BR00ABCDE000", "contract_number": "SCR12345", "ipoc_code": "string", "maturity_date": "YYYY-MM-DD", "allowed_managers": ["00.000.000/0000-00", "00.000.000/0000-00", "00.000.000/0000-00"], "allowed_consultants": ["00.000.000/0000-00", "00.000.000/0000-00", "00.000.000/0000-00"], "issuer_document_number": "00.000.000/0000-00", "bookkeeper_document_number": "00.000.000/0000-00", "number_of_units": 1, "principal_unit_price": 1000000.00, "issue_value": 1000000.00, "issue_unit_price": 1000000.00, "issue_date": "YYYY-MM-DD", "amortization_type": "sac", "installments": [ { "installment_number": 1, "maturity_date": "YYYY-MM-DD", "principal_unit_price": 1000000.00, "face_unit_price": 1010000.00, "amortization_percentage": 1 } ], "delay": { "fine": { "fine_type": "percentage", "percentage_value": 0.0 }, "interest": { "method": "compound", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360" } } }, "pre_fixed": { "monthly_rate": 0.01, "calendar_base": "calendar_360" }, "post_fixed": { "lag": { "amount": 1, "reference": "daily" }, "rate": 1, "indexer": "di", "calendar_base": "workdays" } } ``` ## Definições ### Objeto Ativo (Request Body) | Campo | Tipo | Descrição | Obrigatório | | ------------------------------| ------ | ------------------------------------------------ | ----------- | | `asset_type` | string | Enumerador que determina o [Tipo de Ativo](#enumerador-tipo-de-ativo) | Sim | | `external_id` | string | Identificador externo do ativo; Chave utilizada para acessar a entidade | Sim | | `b3_code` | string | Código cetip do ativo | Não | | `isin_code` | string | Código ISIN (International Securities Identification Number) | Não | | `ipoc_code` | string | Código IPOC do ativo | Não | | `allowed_managers` | list | Lista com CNPJ's de gestores com permissão de operar na emissão | Não | | `allowed_consultants` | list | Lista com CNPJ's de consultores com permissão de operar na emissão | Não | | `issuer_document_number` | string | Número do CNPJ ou CPF do emissor | Sim | | `bookkeeper_document_number` | string | Número do CNPJ do escriturador | Sim | | `number_of_units` | float | Número de unidades | Sim | | `issue_unit_price` | float | Preço unitário na emissão | Sim | | `issue_value` | float | Valor do ativo na emissão | Sim | | `principal_unit_price` | float | Valor unitário de princial do ativo na emissão | Sim | | `issue_date` | string | Data de emissão no formato `YYYY-MM-DD` | Sim | | `disbursement_date` | string | Data de emissão no formato `YYYY-MM-DD` | Sim | | `amortization_type` | string | Enumerador de [Tipo de Amortização](#enumerador-tipo-de-amortização) | Sim | | `contract_number` | string | Número do contrato | Sim | | `maturity_date` | string | Data de vencimento do ativo | Sim | | `installments` | dict | Objeto de [parcelas](#objeto-de-parcela) | Sim | | `delay` | dict | Objeto de [atraso](#objeto-atraso) | Sim | | `pre_fixed` | dict | Objeto de [pré fixado](#objeto-pré-fixado) | Sim | | `post_fixed` | dict | Objeto de [pós fixado](#objeto-pós-fixado) | Não | #### Enumerador Tipo de Ativo | Enumerador | Descrição | |--------------|---------------| | **commercial_paper** | Ativo do tipo Nota Comercial | | **debenture** | Ativo do tipo Debênture | | **cri** | Ativo do tipo CRI | | **cra** | Ativo do tipo CRA | #### Enumerador Tipo de Amortização | Enumerador | Descrição | |--------------|---------------| | **sac** | Amortização do tipo SAC | | **price** | Amortização do tipo Price | #### Objeto de Parcela | Campo | Tipo | Descrição | Obrigatório | | ------------------------------- | ------ | -------------------------------------------| ----------- | | `installment_number` | int | Número da Parcela | Sim | | `maturity_date` | string | Data de Vencimento no formato `YYYY-MM-DD` | Sim | | `principal_unit_price` | float | Valor de principal unitário do ativo | Sim | | `face_unit_price` | float | Valor de face unitário do ativo | Sim | | `amortization_percentage` | float | Porcentagem de Amortização | Não | #### Objeto Atraso | Campo | Tipo | Descrição | Obrigatório | |-|-|-|-| | `fine` | object | Objeto da multa no vencimento. Ver **[Objeto Multa de Atraso](#objeto-multa-de-atraso)**. | Sim | | `interest` | object | Objeto do juros de mora. Ver **[Objeto Juros de Mora](#objeto-juros-de-mora)**. | Sim | #### Objeto Multa de Atraso | Campo | Tipo | Descrição | Obrigatório | |-|-|-|-| | `fine_type` | string | Tipo de Multa. | Sim | | `percentage_value` | number | Valor da Multa, se tipo da multa for `percentage`. Unidade de medida: de 0 à 1, considerando 0 à 100% | Sim | | `amount` | number | Valor da Multa, se tipo de multa for `fixed`. | Sim | ##### Enumerador Tipo da Multa | Enumerador | Descrição | |----------------|-------------------------------------------| | **percentage** | Multa percentual sobre o valor da parcela | | **fixed** | Valor fixo de Multa | #### Objeto Juros de Mora | Campo | Tipo | Descrição | Obrigatório | |-|-|-|-| | `method` * | string | Ver **[Enumerador Método do Juros de Mora](#enumerador-método-do-juros-de-mora)**. | Sim | | `pre_fixed` * | object | Ver **[Objeto de Pré Fixado](#objeto-pré-fixado)**. | Sim | ##### Enumerador Método do Juros de Mora | Enumerador | Descrição | |--------------|-----------------------------| | **compound** | Para juros de mora composto | | **simple** | Para juros de mora simples | #### Objeto Pré Fixado | Campo | Tipo | Descrição | Obrigatório | |-|-|-|-| | `calendar_base` *| string | A base de cálculo utilizada. | enumerator | | `monthly_rate` * | number | A taxa mensal do contrato. Para 1% usar 0.01 | Até 8 casas decimais | #### Objeto Pós Fixado | Campo | Tipo | Descrição | Obrigatório | |---------------|--------|-----------------------------------------------------|-------------| | rate | int | Taxa fixa aplicada | Sim | | indexer | string | Índice de referência da correção (di, ipca) | Sim | | calendar_base | string | Tipo de calendário considerado | Sim | #### Objeto de Lag | Campo | Tipo | Descrição | Obrigatório | |-----------|--------|------------------------------------------------|-------------| | amount | int | Quantidade de unidades de defasagem | Sim | | reference | string | Unidade de tempo de defasagem | Sim | #### Enumerador Base de Cálculo | Enumerador | Descrição | |--------------|---------------| | **daily** | Para valores diários de atraso | | **monthly** | Para valores mensais de atraso | #### Enumerador Referência de Atraso | Enumerador | Descrição | |--------------|---------------| | **workdays** | Para base de cálculo dias úteis (252) | | **calendar_365** | Para base de cálculos 365 | | **calendar_360** | Para base de cálculos 360 | ### Response STATUS 201 ```json title='Response Body' { "security_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "pre_operational", } ``` --- # Confirmação de Emissão URL: /documentation/iaas/emissoes/confirmacao_emissao ## Confirmação - Nota Comercial Após ter finalizado todas formalizações, e registrar os devidos documentos no ativo, é possível aprová-lo, sinalizando que está pronto para seguir com operações. Vale ressaltar que operações de compra podem ser lançadas em ativos pré operacionais, mas estas não poderão ser liquidadas até que a emissão do ativo esteja confirmada. ### Request ENDPOINT /security/security/EXTERNAL_ID/confirm MÉTODO PUT ```json title="Request Body" { "bookkeeper_document_number": "00.000.000/0000-00" } ``` | Campo | Tipo | Descrição | Obrigatório | | ------------------------------| ------ | ---------------------------------------------------- | ----------- | | `bookkeeper_document_number` | string | CNPJ do escriturador para a identificação da emissão | Sim | #### Definição ### Response STATUS 202 ```json title='Response Body' { "security_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "active", } ``` --- # Introdução URL: /documentation/iaas/emissoes/inicio O ecossistema de emissões é o responsável pela criação, compra, venda e pagamentos de ativos como Notas Comerciais, Debêntures, CRIs e CRAs. As funcionalidades disponíveis para utilização são: - Cadastrar um novo ativo pré operacional; - Confirmar a emissão; - Criar boleta de compra ou venda; Esta documentação fornece uma visão detalhada sobre como utilizar o sistema de emissões, incluindo seus principais recursos e fluxos. Para começar a utilizar o sistema, navegue pelos tópicos disponíveis nesta documentação para entender melhor cada aspecto do módulo de cotas de fundo. --- # Apontamentos de Compliance URL: /documentation/iaas/homologacao_cedente/cadastro/apontamentos Durante o processo de análise cadastral do Cedente, as equipes de Compliance, Risco ou de validação interna podem registrar **apontamentos** (também chamados de *annotations*). Um apontamento é uma solicitação ou questionamento direcionado ao agente responsável pelo cadastro, que precisa ser respondido para que a análise prossiga. Sempre que um apontamento é criado, ele nasce no status `open` e, caso configurado, é disparado um [Webhook de Apontamento](/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise#webhooks-de-apontamento) notificando a abertura. Também é enviado um e-mail aos destinatários configurados para o agente. Após o agente responder ao apontamento, ele passa para o status `closed` e um novo webhook é disparado. :::info Apontamentos só existem enquanto a análise estiver em um dos status `in_manual_analysis`, `pending_internal_validation` ou `in_risk_analysis`. Cada apontamento aceita apenas **uma** resposta. ::: --- ## Consulta Paginada de Apontamentos Recupera a lista de apontamentos de uma análise, permitindo ao agente identificar o que precisa ser respondido. ### Request ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotations MÉTODO GET ### Query params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `limit` | integer | Limite de objetos por página (padrão 10, máximo 50). | - | | `page` | integer | Página desejada (inicia em 0). | - | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "open", "origin_type": "compliance", "annotation_datetime": "2025-01-22T20:30:23Z", "message": "Anexar detalhes do processo XXXXXXXXXXX." } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. | --- ## Consulta de Apontamento por Chave ### Request ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "closed", "origin_type": "compliance", "annotation_datetime": "2025-01-22T20:30:23Z", "message": "Anexar detalhes do processo XXXXXXXXXXX.", "response": "Segue autos do processo.", "response_datetime": "2025-01-23T14:05:11Z", "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a" } ``` :::info Os campos `response`, `response_datetime` e `attached_document_key` só são retornados quando o apontamento já foi respondido e/ou possui um documento anexado. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. | | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000043 | 404 | Apontamento não encontrado para o `annotation_key` informado. | Verificar se o `annotation_key` pertence à análise indicada. | --- ## Resposta ao Apontamento Envia a resposta do agente a um apontamento. Opcionalmente, é possível anexar um documento em PDF que comprove ou complemente a resposta. ### Request ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY MÉTODO PUT ```json title='Request Body' { "response": "Segue autos do processo.", "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==" } ``` ### Objeto de Resposta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `response` * | string | Texto de resposta ao apontamento. | 1 - 3000 | | `document_b64` | string | Binário do arquivo em PDF, codificado em Base64. | - | *Campos obrigatórios. ### Response STATUS 202 ```json title='Response Body' { "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "closed", "origin_type": "compliance", "annotation_datetime": "2025-01-22T20:30:23Z", "message": "Anexar detalhes do processo XXXXXXXXXXX.", "response": "Segue autos do processo.", "response_datetime": "2025-01-23T14:05:11Z", "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a" } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. | | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000043 | 404 | Apontamento não encontrado para o `annotation_key` informado. | Verificar se o `annotation_key` pertence à análise indicada. | | ASR000045 | 400 | O apontamento não está mais em status `open` e não aceita mais respostas. | Só é possível responder apontamentos com status `open`. | | ASR000044 | 400 | O apontamento já foi respondido. | Cada apontamento aceita apenas uma resposta. | | ASR000005 | 400 | Formato de arquivo inválido. | Enviar `document_b64` como string em base64 válida. | | ASR000060 | 400 | O arquivo enviado não é um PDF válido. | O conteúdo decodificado de `document_b64` deve ser um PDF. | | ASR000059 | 400 | Tamanho do arquivo excede o limite. | Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). | --- ## Consulta de Documento do Apontamento Recupera uma URL temporária para download do documento anexado a um apontamento. ### Request ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/document/DOCUMENT_KEY MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { "document_url": "https://assignor-bucket.s3.amazonaws.com/8e515a17-8b4d-49a3-aed6-47c9574e426a?..." } ``` :::info A `document_url` retornada é uma URL pré-assinada com validade de 24 horas. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. | | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000043 | 404 | Apontamento não encontrado para o `annotation_key` informado. | Verificar se o `annotation_key` pertence à análise indicada. | | ASR000006 | 404 | Documento não encontrado para o `document_key` informado. | Verificar se o `document_key` corresponde ao documento anexado ao apontamento. | --- ## Objeto de Apontamento | Campo | Tipo | Descrição | |-------|------|-----------| | `annotation_key` | string | Identificador único do apontamento. | | `analysis_key` | string | Chave da análise à qual o apontamento pertence. | | `assignor_registry_key` | string | Chave do cedente. | | `status` | string | Status atual do apontamento. Ver **[Annotation Status](#annotation-status)**. | | `origin_type` | string | Origem do apontamento. Ver **[Annotation Origin Type](#annotation-origin-type)**. | | `annotation_datetime` | string | Data e hora de criação do apontamento (ISO 8601). | | `message` | string | Mensagem do apontamento registrada pela equipe da QI DTVM. | | `response` | string | Resposta enviada pelo agente (presente após a resposta). | | `response_datetime` | string | Data e hora da resposta (presente após a resposta). | | `attached_document_key` | string | Chave do documento anexado à resposta (quando houver). | ### Annotation Status | Enumerador | Descrição | | ---------- | --------- | | **created** | Apontamento criado, ainda não disponibilizado. | | **open** | Aberto e aguardando resposta do agente. | | **closed** | Respondido e encerrado. | ### Annotation Origin Type | Enumerador | Descrição | | ---------- | --------- | | **compliance** | Apontamento originado pela equipe de Compliance (análise manual). | | **risk_analysis** | Apontamento originado pela equipe de Risco. | | **internal** | Apontamento originado na validação interna. | --- # Atualização de Cadastro URL: /documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro É de responsabilidade do gestor manter os dados dos cedentes atualizados, de acordo com a situação atual da companhia. Este comprometimento é de extrema importancia, tanto para manter as análises de PLD atualizadas quanto para atualizar os grupos de assinantes, que mudam constantemente e expiram, sendo necessária uma nova análise. Além disso, a cada 2 anos, automaticamente é gerada uma nova análise para garantir a atualização periódica dos mesmos. :::warning Aviso É de responsabilidade do gestor manter os dados do cedente atualizados e refletindo a realidade da companhia. ::: Ao atualizar um cadastro, independente de qual campo for alterado, uma nova análise será gerada, a qual exigirá novos documentos de acordo com as alterações relalizadas. As análises seguem um sequencial, e podem falhar inúmeras vezes até serem finalmente aprovadas pelo compliance. As alterações só serão aplicadas após a análise ser concluída com sucesso. Caso as partes relacionadas sejam alteradas, haverá uma etapa de validação dos grupos de assinantes do cedente. Vale ressaltar que caso uma parte relacionada ou um avalista NÃO for enviado, o mesmo será considerado EXCLUÍDO. :::info Caso uma análise esteja em andamento, e uma atualização cadastral seja enviada, a última análise em aberto será automaticamente fechada, sendo recusada, com motivo "assignor_update". ::: --- ## Atualização de Cadastro de Cedente Pessoa Jurídica ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY MÉTODO PUT ```json title='Request Body' { "email": "qidtvm@qitech.com.br", "annual_revenues": 1000000, "is_in_national_financial_system": true, "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "4984037284610", "is_representative": true, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ], "guarantors": [ { "name": "Avalista PF", "document_number": "172.775.419-01", "person_type": "natural_person", "email": "email@avalista.com" }, { "name": "Avalista PJ", "document_number": "65.679.662/0001-85", "person_type": "legal_person", "email": "email@avalista.com", "guarantor_representatives": [ { "name": "Assinante do Avalista", "document_number": "244.412.084-13", "email": "emailrepresentante@avalista.com" } ] }, ] } ``` --- ### Definição do Cedente | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `email` | string | Endereço de e-mail do cedente. | 1 a 255 | | `is_in_national_financial_system` | boolean | Indicador se o cedente é integrante do SFN. | - | | `phone` | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `related_parties` | array | Lista de partes relacionadas da empresa.| Ver **[Definição de Parte Relacionada](#definição-de-parte-relacionada)**. | | `guarantors` | array | Lista de avalistas do cedente.| Ver **[Definição de Avalista](#definição-de-avalista)**. | Caso não deseje alterar um campo, basta não enviá-lo na request. Para listas, como é o caso de `related_parties` e `guarantors`, caso uma lista vazia seja enviada, ou uma parte previamente indicada na lista, e não indicada na nova, será tratado como exclusão. ### Response STATUS 200 ```json title='Response Body' { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "registred", "name": "QI Tech", "document_number": "32.402.502/0001-35", "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 2, "status": "pending_documents", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "passport_number": "C01X00T47", "name": "Maria Vitoria", "documents": [] } ], "documents": [ { "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017", "document_type": "social_contract", "status": "valid", } ], "analysis_data": {} } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. | | `name` | string | Nome do Cedente. | 1 a 255 | | `document_number` | string | Documento do Cedente. | 14 a 18 | | `last_analysis` | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. | :::info É importante armazenar a `analysis_key` e as `analysis_related_party_key` que serão utilizadas para envio de documentos do cedente e das partes relacionadas. ::: --- :::caution Atenção! Ao atualizar o cadastro de um cedente, uma nova análise cadastral é gerada, resultando em uma nova `analysis_key` e novas `analysis_related_party_key`. O cadastro só será efetivamente atualizado após a aprovação desta nova análise. ::: :::caution Importante! Não é possível atualizar dados essenciais do cedente como **Número do Documento**, **Tipo de Pessoa**. Os dados cadastrais passíveis de alteração incluem: - Nome/Razão Social; - Email; - Endereço; - Telefone; - Faturamento; - Participante do SFN; - Partes Relacionadas (inclusão e alteração de vigentes); - Avalistas (inclusão e alteração de vigentes); ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` existe e pertence ao agente autenticado. | | ASR000100 | 400 | Campo enviado não pode ser atualizado em uma filial. | Para filiais, somente `email`, `phone`, `address` e `annual_revenues` podem ser atualizados. Para alterar `name`, `is_in_national_financial_system`, `related_parties` ou `guarantors`, atualizar o cadastro da matriz. | | ASR000056 | 400 | Pessoa física não pode ser participante do Sistema Financeiro Nacional. | Para cedentes pessoa física, enviar `is_in_national_financial_system=false` ou omitir o campo. | | ASR000054 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 parte relacionada. | Garantir que `related_parties` (após a atualização) tenha ao menos um item para cedentes pessoa jurídica. | | ASR000057 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. | Garantir que ao menos uma parte relacionada tenha `is_representative=true`. | | ASR000011 | 400 | Número de documento de parte relacionada duplicado. | Cada `document_number` em `related_parties` deve ser único. | | ASR000041 | 400 | Email obrigatório para representante. | Para partes relacionadas com `is_representative=true`, informar `email`. | | ASR000058 | 400 | Pessoa estrangeira sem CPF não pode ser assinante. | Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. | | ASR000078 | 400 | Número de documento de avalista duplicado. | Cada avalista em `guarantors` deve ter `document_number` único. | | ASR000079 | 400 | Avalista pessoa física não pode receber representantes. | Não enviar `guarantor_representatives` para avalistas com `person_type=natural_person`. | | ASR000080 | 400 | Documento de representante de avalista duplicado. | Cada representante em `guarantor_representatives` deve ter `document_number` único. | | ASR000091 | 400 | Avalista pessoa jurídica deve ter pelo menos um representante. | Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. | --- ## Definições ### Definição de Endereço | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `street` * | string | Nome da rua. | 1 a 255 | | `number` * | string | Número do endereço. | 1 a 4 | | `neighborhood` * | string | Bairro. | 1 a 255 | | `city` * | string | Cidade. | 1 a 255 | | `uf` * | string | Sigla do estado. | 2 | | `complement` | string | Complemento do endereço. | 1 a 255 | | `postal_code` * | string | Código postal. | 9 (formato: XXXXX-XXX) | | `country` * | string | País (sigla). | 3 | *Campos obrigatórios. --- ### Definição de Telefone | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `international_dial_code` * | string | Código internacional de discagem. | 1 a 3 | | `area_code` * | string | Código de área. | 2 | | `number` * | string | Número de telefone. | 8 a 9 | *Campos obrigatórios. --- ### Definição de Parte Relacionada | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `document_number` ** | string | Número de documento do beneficiário (CPF). | 14 a 18 | | `passport_number` ** | string | Número de documento do beneficiário estrangeiro. | 8 a 9 | | `related_party_type` * | string | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `direct_beneficiary` * | boolean | Beneficiário diretamente ou indiretamente ligado ao cedente. | 1 a 255 | | `is_representative` * | boolean | Indicador se a parte relacionada é representante assinante do cedente. | 1 a 255 | | `company_registry_number` *** | string | Caso não seja diretamente ligado ao cedente, à qual companhia o mesmo está ligado. | 1 a 255 | | `company_country` *** | string | País onde a companhia-elo entre o beneficiário e o cedente está registrada. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `email` **** | string | Endereço de e-mail do representante. | 1 a 255 | | `phone` | object | Objeto referenciando as informações do telefone do representante. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil da parte relacionada. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão da parte relacionada. | 1 a 255. | *Campos obrigatórios. **document_number obrigatório para brasileiros, e passport_number para estrangeiros. ***Campos obrigatórios caso a parte relacionada não seja beneficiário diretamente ligada ao cedente. ****Campos exigidos apenas para representantes assinantes. --- ### Definição de Análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_key` * | string | Identificador da análise. | 36 | | `analysis_number` * | integer | Número sequencial da análise. | - | | `status` * | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. | | `analysis_related_parties` * | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. | | `documents` * | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | | `analysis_data` * | object | Payload da request que originou a análise. | - | | `analysis_datetime` * | string | Objeto date time da criação da análise. | - | | `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. | | `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - | *Campos obrigatórios. --- ### Definição de Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Avalista. | 3 - 255 | | `document_number` * | string | Número de documento do avalista. | 14 a 18 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do avalista. | 1 a 255 | | `nationality` | string | País de origem do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `phone` | object | Objeto referenciando as informações do telefone do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `guarantor_representatives` | array | Assinantes do Avalista - Apenas para avalista pessoa jurídica. | Ver **[Definição de Representante do Avalista](#definição-de-representante-do-avalista)**. | | `marital_status` | string | Estado civil do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do avalista. | 1 a 255. | *Campos obrigatórios. Os representantes do avalista devem ser enviados apenas para o avalista pessoa jurídica. :::warning Atenção Tanto o avalista quanto os representantes também serão adicionados à anáise gerada, sendo necessário enviar os documentos padrão de acordo com o tipo de pessoa do mesmo. Também passarão pelo processo de compliance, podendo gerar apontamentos. ::: --- ### Definição de Representante do Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Representante. | 3 - 255 | | `document_number` * | string | Número de documento do representante do avalista - obrigatóriamente pessoa física. | 14 | | `email` * | string | Endereço de e-mail do representante do avalista. | 1 a 255 | | `nationality` | string | País de origem do representante do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil do representante do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do representante do avalista. | 1 a 255. | --- ### Definição de Documentos | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Identificador do documento. | 36 | | `document_type` * | string | Tipo do documento. | Ver **[Enumeradores de tipo de documento](#document-type)**. | | `status` | string | Status do documento. | Ver **[Enumeradores de status de documento](#document-status)**. | | `observation` | string | Observações enviadas. | - | *Campos obrigatórios. --- ### Definição de Partes Relacionadas de análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_representative_key` * | string | Identificador do representante. | 36 | | `document_number` * | string | Número de documento do representante. | 14 a 18 | | `name` | string | Nome do beneficiário. | 1 a 255 | | `documents` * | enumerador | Documentos da anáise do representante. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | *Campos obrigatórios. --- # Enumeradores ### Assignor Registry Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **pending_registry** | Pendente Registro | | **registered** | Registrado | --- ### Analysis Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_documents** | Pendente Documentos | | **sent_to_analysis** | Enviado para Análise | | **pending_internal_validation** | Em Validação de documentos | | **in_manual_analysis** | Em Análise Manual de Compliance | | **approved** | Aprovado | | **reproved** | Reprovado | | **canceled** | Cancelado | --- ### Related Party Type | Enumerador | Descrição | | ----------------------- | ------------- | | **president** | Presidente | | **partner** | Sócio | | **administrator** | Administrador | | **director** | Diretor | | **manager** | Gestor | | **attorney** | Procurador | --- ### Document Status | Enumerador | Descrição | | ----------------------- | ------------- | | **created** | Criado | | **valid** | Válido | | **invalid** | Inválido | | **canceled** | Cancelado | | **accepted** | Aceito, porém não validado | --- ### Document Type | Enumerador | Descrição | | ---------------------------- | -------------------------- | | **cnh** | CNH. | | **rg_back** | RG parte traseira. | | **rg_front** | RG parte frontal. | | **passport** | Passaporte - exclusivo para estrangeiros. | | **national_migration_registry** | Registro Nacional de Migração. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. | | **board_election_record** | Ata de Eleição da Diretoria Vigente. | | **power_of_attorney** | Procuração - obrigatório caso o representante seja um procurador. | | **marital_power_of_attorney** | Procuração Uxória - disponível apenas para cônjuges. | | **compliance_statement** | Parecer de Compliance. | | **financial_statement** | Demonstração Financeira. | | **credit_report** | Ata/Parecer de Crédito. | | **manager_statement** | Parecer/Ficha do Gestor. | | **visit_report** | Relatório de Visita. | | **proof_of_residence** | Comprovante de Residência. | | **credit_agency_consulation** | Consulta aos órgãos de Proteção de Crédito. | | **annual_revenues_declaration** | Declaração de Faturamento. | | **financial_institutions_declaration** | Declaração de Relacionamento Bancário. | | **additional_document** | Documento adicional - livre. | --- ### Analysis Reproval Reason | Enum | Description | |--------------|---------------| | **assignor_update** | Análise cancelada devido à atualização cadastral posterior | | **insuficient_documents** | Documentação mínima para comprovação de poderes não enviada | | **compliance_reproval** | Reprovação de vínculo por análise do time de compliance | | **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado | | **invalid_documents** | Documentação inválida/expirada | | **missing_related_parties** | Parte relacionada obrigatória não enviada | --- ### Marital Status | Enum | Description | |--------------|---------------| | **single** | Solteiro(a) | | **married** | Casado(a) | | **widower** | Viúvo(a) | | **divorced** | Divorciado(a) | | **separated** | Separado(a) | | **stable_union** | Em União Estável | --- ### Property System | Enum | Descrição | | --------------------------------- | -------------------------------------- | | **total_communion_of_goods** | Comunhão Total de Bens | | **partial_communion_of_goods** | Comunhão Parcial de Bens | | **total_separation_of_goods** | Separação Total de Bens | | **final_participation_of_acquisitions** | Participação Final nos Aquestos | | **compulsory_separation_of_goods** | Separação Obrigatória de Bens | --- # Definição de Assinantes URL: /documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes Após o envio do cadastro do cedente, é possível, **opcionalmente**, definir conjuntos customizados de assinantes para a operação. Esses conjuntos determinam quais partes relacionadas (do cedente ou de avalistas) devem assinar cada tipo de documento, com possibilidade de regras por tipo de produto. Caso nenhum conjunto customizado seja enviado, o sistema utiliza os conjuntos padrão definidos pela administradora. :::info Informação Os conjuntos de assinantes (`signer_group_sets`) representam grupos de assinantes vinculados a um proprietário (`owner`), que pode ser o **cedente** (`assignor_registry`) ou uma **parte relacionada de análise** (`analysis_related_party`, de avalistas). A definição customizada permite, por exemplo, exigir múltiplos assinantes, ou restringir quem pode assinar determinado produto. ::: :::warning Atenção A definição de conjuntos customizados deve ocorrer antes da etapa de [Envio para Análise](/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise). Após o envio para análise, os conjuntos vigentes serão utilizados nas assinaturas dos contratos de cessão. ::: --- ## Definição de Conjunto Customizado para o Cedente Permite ao cliente substituir o conjunto padrão de assinantes do cedente por um ou mais conjuntos customizados, organizados por produto. Os assinantes informados devem corresponder a partes relacionadas previamente cadastradas como representantes do cedente. ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/custom_signer_groups MÉTODO POST ```json title='Request Body' { "signer_group_sets": [ { "product": "assignment_contract", "signer_groups": [ { "minimum_required_signers": 2, "signers": [ { "document_number": "883.512.866-80", "is_required_signer": true }, { "document_number": "802.834.257-41", "is_required_signer": false } ], "expiration": "2026-12-31" } ] }, { "product": "commercial_paper", "signer_groups": [ { "minimum_required_signers": 1, "signers": [ { "document_number": "883.512.866-80", "is_required_signer": true } ], "expiration": "2026-12-31" } ] } ] } ``` ### Response STATUS 204 Sem conteúdo no corpo de resposta. :::info Informação A criação de um conjunto customizado para o cedente substitui o conjunto `main` (padrão) vigente para o produto informado. Apenas os conjuntos com `status` igual a `valid` são utilizados nas assinaturas. ::: :::warning Atenção Ao enviar, o grupo de assinantes nasce no status `in_analysis`. Signer groups sets neste status não são enviados para assinatura. Com a aprovação do cadastro, o grupo passa para o status `valid`, e só então, será utilizado para assinaturas acima do `main` signer group. ::: :::warning Atenção Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000066 | 400 | Status da análise não permite definição de grupos customizados. | A análise deve estar em `pending_documents` para receber grupos customizados. | | ASR000109 | 404 | Tipo de produto inválido. | Usar um valor válido para `product` (ver enum [Product Type](#product-type)). | | ASR000118 | 400 | Signatário inválido. | O `document_number` enviado em `signers` deve corresponder a um representante já cadastrado para o cedente, com `is_representative=true`. | --- ## Definição de Conjunto Customizado para Parte Relacionada Permite definir conjuntos customizados para uma parte relacionada específica do cedente — como avalistas (`guarantors`) — utilizando a `analysis_related_party_key` retornada na criação da análise. :::info Informação Lembre-se de que avalistas são representados como `analysis_related_party`. Logo, este endpoint é o ponto único para customizar assinantes de qualquer parte vinculada à análise (representantes do cedente, avalistas e representantes de avalistas). ::: ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/custom_signer_groups MÉTODO POST ```json title='Request Body' { "signer_group_sets": [ { "product": "assignment_contract", "signer_groups": [ { "minimum_required_signers": 1, "signers": [ { "document_number": "244.412.084-13", "is_required_signer": true } ], "expiration": "2026-12-31" } ] } ] } ``` ### Response STATUS 204 Sem conteúdo no corpo de resposta. :::warning Atenção Ao enviar, o grupo de assinantes nasce no status `in_analysis`. Signer groups sets neste status não são enviados para assinatura. Com a aprovação do cadastro, o grupo passa para o status `valid`, e só então, será utilizado para assinaturas acima do `main` signer group. ::: :::warning Atenção Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000035 | 404 | Parte relacionada da análise não encontrada para o `analysis_related_party_key` informado. | Verificar se o `analysis_related_party_key` corresponde a um avalista ou representante de avalista da análise. | | ASR000066 | 400 | Status da análise não permite definição de grupos customizados. | A análise deve estar em `pending_documents` para receber grupos customizados. | | ASR000109 | 404 | Tipo de produto inválido. | Usar um valor válido para `product` (ver enum [Product Type](#product-type)). | | ASR000118 | 400 | Signatário inválido. | O `document_number` enviado em `signers` deve corresponder a um representante já cadastrado para a parte relacionada (avalista ou representante de avalista). | --- ## Consulta de Conjuntos de Assinantes Esse endpoint **paginado** permite ao cliente consultar os conjuntos de assinantes existentes para o cedente e suas partes relacionadas, incluindo os conjuntos padrão gerados automaticamente. É útil para identificar `signer_group_set_key` e estrutura atual antes de criar uma versão customizada. ### Request ENDPOINT /assignor_registry/signer_group_sets MÉTODO GET #### Query Parameters | Campo | Tipo | Descrição | |-------|------|-----------| | `limit` | integer | Quantidade de itens por página (0 a 50). Padrão: 10. | | `page` | integer | Página a ser consultada, iniciando em 0. Padrão: 0. | | `owner_key` | string | Filtra pelo identificador do proprietário (cedente ou parte relacionada). | | `owner_type` | string | Tipo do proprietário. Ver **[Owner Type](#owner-type)**. | | `owner_document_number` | string | Documento do proprietário. Exige `owner_type` para ser utilizado. | | `product_type` | string | Filtra por tipo de produto. Ver **[Product Type](#product-type)**. | | `status` | string | Filtra pelo status do conjunto. Ver **[Signer Group Set Status](#signer-group-set-status)**. | :::tip Dica Para listar apenas os conjuntos que estão efetivamente sendo utilizados nas assinaturas, filtre por `status=valid`. Conjuntos em `in_analysis` ainda dependem da aprovação do cadastro e não são enviados para assinatura. ::: ### Response STATUS 200 ```json title='Response Body' { "data": [ { "signer_group_set_key": "f2c1e4a8-91d2-4f10-8a3b-7e5c9b2d4a6e", "owner_key": "c4295375-4077-4092-a258-5bcdf8875907", "owner_type": "assignor_registry", "product_type": "assignment_contract", "signer_group_set_type": "custom", "status": "valid", "signer_groups": [ { "minimum_required_signers": 2, "signers": [ { "document_number": "883.512.866-80", "is_required_signer": true }, { "document_number": "802.834.257-41", "is_required_signer": false } ], "expiration": null } ] } ], "limit": 10, "page": 0, "is_last_page": true } ``` #### Campos de Paginação | Campo | Tipo | Descrição | |-------|------|-----------| | `data` | array | Lista de conjuntos de assinantes da página atual. Ver **[Definição de Conjunto de Assinantes](#definicao-de-conjunto-de-assinantes-signer-group-set)**. | | `limit` | integer | Quantidade de itens por página utilizada na consulta. | | `page` | integer | Página retornada, iniciando em 0. | | `is_last_page` | boolean | Indica se esta é a última página do resultado. | ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000121 | 400 | `owner_document_number` enviado sem `owner_type`. | Ao filtrar por `owner_document_number`, sempre informar também `owner_type`. | | ASR000120 | 400 | Valor de `status` inválido no filtro. | Usar um valor válido para o filtro `status` (ver enum [Signer Group Set Status](#signer-group-set-status)). | --- ## Definições ### Definição de Conjunto de Assinantes (Signer Group Set) | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `signer_group_set_key` | string | Identificador único do conjunto. | 36 | | `owner_key` | string | Identificador do proprietário. Pode ser `assignor_registry_key` ou `analysis_related_party_key`. | 36 | | `owner_type` | string | Tipo do proprietário. | Ver **[Owner Type](#owner-type)**. | | `product_type` | string | Tipo de produto ao qual o conjunto está associado. | Ver **[Product Type](#product-type)**. | | `signer_group_set_type` | string | Tipo do conjunto (`main` ou `custom`). | Ver **[Signer Group Set Type](#signer-group-set-type)**. | | `status` | string | Status do conjunto. | Ver **[Signer Group Set Status](#signer-group-set-status)**. | | `signer_groups` | array | Lista de grupos de assinantes que compõem o conjunto. | Ver **[Definição de Grupo de Assinantes](#definicao-de-grupo-de-assinantes-signer-group)**. | --- ### Definição de Item de Envio (Signer Group Set Item) Estrutura utilizada no corpo das requisições de criação de conjuntos customizados. | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `product` * | string | Tipo de produto ao qual o conjunto será associado. | Ver **[Product Type](#product-type)**. | | `signer_groups` * | array | Lista de grupos de assinantes (mínimo 1). | Ver **[Definição de Grupo de Assinantes](#definicao-de-grupo-de-assinantes-signer-group)**. | *Campos obrigatórios. --- ### Definição de Grupo de Assinantes (Signer Group) | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `minimum_required_signers` * | number | Quantidade mínima de assinantes do grupo necessários para validar a assinatura. | Mínimo 1 | | `signers` * | array | Lista de assinantes do grupo (mínimo 1). | Ver **[Definição de Assinante](#definicao-de-assinante-signer)**. | | `expiration` | string | Data de expiração do grupo no formato `YYYY-MM-DD`. | 10 | *Campos obrigatórios. --- ### Definição de Assinante (Signer) | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_number` * | string | CPF do assinante no formato `XXX.XXX.XXX-XX`. | 14 | | `is_required_signer` * | boolean | Indica se o assinante é obrigatório no grupo. | - | *Campos obrigatórios. :::info Informação Os `document_number` enviados devem corresponder a partes relacionadas (representantes do cedente, ou representantes do avalista em questão) presentes no cadastro do cedente. Documentos que não estiverem associados ao cedente serão rejeitados. ::: --- # Enumeradores ### Owner Type | Enumerador | Descrição | |------------|-----------| | **assignor_registry** | Conjunto vinculado ao cedente. | | **analysis_related_party** | Conjunto vinculado a uma parte relacionada da análise (avalistas). | --- ### Product Type | Enumerador | Descrição | |------------|-----------| | **assignment_contract** | Contrato de cessão (utilizado por padrão). | | **commercial_paper** | Nota Comercial (Cadastro único com a plataforma de escrituração). | --- ### Signer Group Set Type | Enumerador | Descrição | |------------|-----------| | **main** | Conjunto padrão, gerado da análise da Administradora. | | **custom** | Conjunto customizado, criado pelo cliente sobrepondo o conjunto `main`. | --- ### Signer Group Set Status | Enumerador | Descrição | |------------|-----------| | **in_analysis** | Conjunto enviado e atrelado à análise em aberto. Não é utilizado nas assinaturas. | | **valid** | Conjunto vigente e utilizado nas assinaturas. | | **inactive** | Conjunto substituído por uma versão mais recente ou desativado. | --- # Envio para Análise URL: /documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise Após todos os documentos estarem devidamente anexados, deve ser disparada a análise, a qual enviará todos os dados para nosso sistema de anti-fraude, para análise de compliance. Caso recusada, deverá ser feita uma nova análise, caso aprovada, haverá uma etapa posterior de validação interna de representantes, onde será tambem monstada a estrutura de assinantes do cedente, para finalmente começar a operação com o mesmo, disponibilizando a criação de contratos mãe entre o cedente e o fundo. --- ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY MÉTODO PUT ```json title='Request Body' { "analysis_status":"sent_to_analysis" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_status` * | string | Novo status da análise a ser enviado (deve ser igual a **sent_to_analysis**). | 1 a 50 | *Campo obrigatório. ### Response STATUS 200 ```json title='Response Body' { "analysis_key": "2b1fa466-4d36-48e9-b6e3-776a1b700b9f", "analysis_number": 1, "assignor_registry_key": "d0a93900-457d-496a-8326-480ecaf946c3", "status": "sent_to_analysis" } ``` :::caution Atenção! Uma análise deve ser efetivamente enviada somente após anexar todos os documentos pertinentes. Uma vez enviada a análise, não será mais possível anexar novos documentos. ::: :::warning Não deixe a análise parada Uma análise que fica **1 mês sem movimentação** em `pending_documents` é **cancelada automaticamente** (`canceled`) e não pode mais ser disparada — a tentativa é recusada com `ASR000034`. Nesse caso, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000040 | 400 | A análise não pertence ao cedente informado. | Garantir que `analysis_key` e `assignor_registry_key` correspondam à mesma análise. | | ASR000034 | 400 | A análise não pode receber este status. | A análise só pode ser enviada quando estiver no status `pending_documents`. Verifique o status atual em [Consulta de Análise](/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise). Se estiver `canceled`, ela foi cancelada por inatividade e é preciso gerar uma nova análise. | | ASR000038 | 400 | Status enviado é inválido. | O campo `analysis_status` deve ser exatamente `sent_to_analysis`. | | ASR000009 | 400 | A análise não possui todos os documentos obrigatórios do cedente. | Anexar os documentos exigidos para o tipo de pessoa do cedente antes de disparar a análise. Ver [Envio de Documentos](/documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos). | | ASR000015 | 400 | Uma parte relacionada da análise não possui todos os documentos obrigatórios. | Anexar os documentos exigidos da parte relacionada indicada pela `analysis_related_party_key` no erro antes de disparar a análise. | --- # Envio de Cadastro URL: /documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro Na primeira etapa de cadastro do cedente, são informados os dados do mesmo, conforme definidos abaixo. Vale relembrar que, apenas enviar os dados, não cria um cedente operacional, o mesmo só será ativado após a conclusão bem sucedida das análises dos documentos do mesmo. Obrigatoriamente para pessoas jurídicas, e opcionalmente em pessoas físicas, é possível cadastrar partes relacionadas, que representam os beneficiários finais ligados ao cedente. :::info Informação Um beneficiário final é definido como o indivíduo, ou grupo de indivíduos, com relevância significativa na empresa ou conglomerado, com poder decisório ou participação significativa na grade societária. Para fins de cadastro, devem ser levados em conta quaisquer associados com participação superior a 15% na companhia, ou no conglomerado do qual fazem parte, ou, caso não haja participação tão relevante, os três maiores em ordem decrescente. ::: Caso o beneficiário relevante seja uma outra empresa, deve-se atribuir os seus beneficiários finais, indicados como beneficiários indiretos. Além disso, são considerados partes relacionadas quaisquer procuradores, gestores, e diretores envolvidos na operação, que serão os representantes assinantes do cedente na mesma. Os representantes assinantes são partes relacionadas responsáveis por acompanhar e assinar os documentos direcionados ao cedente pelo nosso sistema, sendo necessária comprovação do vínculo, no caso de empresas, por meio do quadro societário, ou de diretores, ou com uma procuração. Não é possível cadastrar uma parte relacionada que não seja um procurador para um cedente pessoa física. Além disso, é necessário indicar se a parte relacionada considerada beneficiário final tem vínculo direto ou indireto com o cedente. :::info Informação No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início 1: Reprovação automática; CPF/CNPJ com início 8: Pendente Validação Manual; O restante é aprovado automaticamente. ::: --- ## Cadastro de Cedente ### Request ENDPOINT /assignor_registry/assignor_registry MÉTODO POST ```json title='Request Body' { "name": "QI Tech", "document_number": "32.402.502/0001-35", "person_type": "legal_person", "email": "qitech@qitech.com.br", "annual_revenues": 1000000, "is_in_national_financial_system": true, "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "4984037284610", "is_representative": false, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ], "accounts": [ { "account_branch": "0001", "account_number": "7912584", "account_digit": "1", "financial_institution_code": "329", "account_type": "checking_account", "default_account": true }, { "account_branch": "0001", "account_number": "8758931", "account_digit": "5", "financial_institution_code": "329", "account_type": "escrow_account", "default_account": false } ], "guarantors": [ { "name": "Avalista PF", "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "document_number": "172.775.419-01", "person_type": "natural_person", "email": "email@avalista.com" }, { "name": "Avalista PJ", "document_number": "65.679.662/0001-85", "person_type": "legal_person", "email": "email@avalista.com", "guarantor_representatives": [ { "name": "Assinante do Avalista", "document_number": "244.412.084-13", "email": "emailrepresentante@avalista.com", "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" } } ] }, ] } ``` --- ### Definição do Cedente | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do cedente. | 1 a 255 | | `document_number` * | string | Número de documento do cedente (CNPJ). | 14 a 18 | | `annual_revenues` * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do cedente. | 1 a 255 | | `is_in_national_financial_system` * | boolean | Indicador se o cedente é integrante do SFN. | - | | `phone` | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `related_parties` * | array | Lista de partes relacionadas da empresa.| Ver **[Definição de Parte Relacionada](#definição-de-parte-relacionada)**. | | `accounts` * | array | Lista de contas de desembolso do cedente.| Ver **[Definição de Conta](#definição-de-conta)**. | | `guarantors` * | array | Lista de avalistas do cedente.| Ver **[Definição de Avalista](#definição-de-avalista)**. | *Campos obrigatórios. ### Response STATUS 201 ```json title='Response Body' { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_registry", "name": "QI Tech", "document_number": "32.402.502/0001-35", "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "status": "pending_documents", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "passport_number": "C01X00T47", "name": "Maria Vitoria", "documents": [] } ], "documents": [ { "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017", "document_type": "social_contract", "status": "valid", } ], "analysis_data": {} } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. | | `name` | string | Nome do Cedente. | 1 a 255 | | `document_number` | string | Documento do Cedente. | 14 a 18 | | `last_analysis` | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. | :::info É importante armazenar a `assignor_registry_key` pois ela será utilizada em diversos outros processos, assim como a `analysis_key` e as `analysis_related_party_key` que serão utilizadas para envio de documentos do cedente e das partes relacionadas. ::: :::info Na estrutura de análise, um avalista, ou um representante de um avalista, também é representado por um `analysis_related_party`. Importante notar que o mesmo é único por `document_number`, logo, caso a mesma pessoa seja avalista e parte relacionada do cedente, por exemplo, gerará apenas um `analysis_related_party`, com uma `analysis_related_party_key`, que servirá tanto para a parte relacionada, quanto para o avalista. ::: :::info Os representantes de pessoa física se limitam apenas ao procurador que pode assinar por tal. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000032 | 409 | Esse agente já cadastrou esse cedente. | O `document_number` já possui um cadastro; utilize o fluxo de [atualização de cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). | | ASR000054 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 parte relacionada. | Incluir ao menos uma parte relacionada em `related_parties`. | | ASR000056 | 400 | Pessoa física não pode ser participante do Sistema Financeiro Nacional. | Para `person_type=natural_person`, enviar `is_in_national_financial_system=false`. | | ASR000057 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. | Garantir que ao menos uma parte relacionada possua `is_representative=true`. | | ASR000011 | 400 | Número de documento de parte relacionada duplicado. | Cada `document_number` em `related_parties` deve ser único. | | ASR000041 | 400 | Email obrigatório para representante. | Para partes relacionadas com `is_representative=true`, informar `email`. | | ASR000058 | 400 | Pessoa estrangeira sem CPF não pode ser assinante. | Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. | | ASR000071 | 404 | Instituição financeira não encontrada. | Validar o `financial_institution_code` (código bancário) informado para a conta. | | ASR000087 | 400 | Informação de conta deve conter apenas números. | Enviar `account_branch`, `account_number` e `account_digit` apenas com dígitos. | | ASR000081 | 400 | Mais de uma conta padrão foi enviada. | Apenas uma conta deve ter `default_account=true`. | | ASR000078 | 400 | Número de documento de avalista duplicado. | Cada avalista em `guarantors` deve ter `document_number` único. | | ASR000079 | 400 | Avalista pessoa física não pode receber representantes. | Para avalistas com `person_type=natural_person`, o `guarantor_representatives` deve ser do tipo `spouse` | | ASR000080 | 400 | Documento de representante de avalista duplicado. | Cada representante em `guarantor_representatives` deve ter `document_number` único. | | ASR000091 | 400 | Avalista pessoa jurídica deve ter pelo menos um representante. | Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. | --- ## Definições ### Definição de Endereço | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `street` * | string | Nome da rua. | 1 a 255 | | `number` * | string | Número do endereço. | 1 a 4 | | `neighborhood` * | string | Bairro. | 1 a 255 | | `city` * | string | Cidade. | 1 a 255 | | `uf` * | string | Sigla do estado. | 2 | | `complement` | string | Complemento do endereço. | 1 a 255 | | `postal_code` * | string | Código postal. | 9 (formato: XXXXX-XXX) | | `country` * | string | País (sigla). | 3, de acordo com a ISO 3166-1 alpha-3 | *Campos obrigatórios. --- ### Definição de Telefone | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `international_dial_code` * | string | Código internacional de discagem. | 1 a 3 | | `area_code` * | string | Código de área. | 2 | | `number` * | string | Número de telefone. | 8 a 9 | *Campos obrigatórios. --- ### Definição de Parte Relacionada | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `document_number` ** | string | Número de documento do beneficiário (CPF). | 14 a 18 | | `passport_number` ** | string | Número de documento do beneficiário estrangeiro. | 8 a 9 | | `related_party_type` * | string | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `direct_beneficiary` * | boolean | Beneficiário diretamente ou indiretamente ligado ao cedente. | 1 a 255 | | `is_representative` * | boolean | Indicador se a parte relacionada é representante assinante do cedente. | 1 a 255 | | `company_registry_number` *** | string | Caso não seja diretamente ligado ao cedente, à qual companhia o mesmo está ligado. | 1 a 255 | | `company_country` *** | string | País onde a companhia-elo entre o beneficiário e o cedente está registrada. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `email` **** | string | Endereço de e-mail do representante. | 1 a 255 | | `phone` | object | Objeto referenciando as informações do telefone do representante. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil da parte relacionada. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão da parte relacionada. | 1 a 255. | *Campos obrigatórios. **document_number obrigatório para brasileiros, para estrangeiros, caso tenha CPF, é possível utilizar o document_number, caso contrário, pelo menos o passport_number deve ser enviado. ***Campos obrigatórios caso a parte relacionada não seja beneficiário diretamente ligada ao cedente. Caso contrário, não devem ser enviados. ****Campos exigidos apenas para representantes assinantes. :::info Campos não obrigatorios, como `marital_status` e `address`, podem ser enviados caso deseje uma qualificação mais completa no contrato mãe de cessão, nas etapas futuras. ::: --- ### Definição de Análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_key` * | string | Identificador da análise. | 36 | | `analysis_number` * | integer | Número sequencial da análise. | - | | `status` * | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. | | `analysis_related_parties` * | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. | | `documents` * | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | | `analysis_data` * | object | Payload da request que originou a análise. | - | | `analysis_datetime` * | string | Objeto date time da criação da análise. | - | | `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. | | `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - | *Campos obrigatórios. --- ### Definição de Partes Relacionadas de análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_related_party_key` * | string | Identificador da parte relacionada. | 36 | | `document_number` * | string | Número de documento da parte relacionada. | 14 a 18 | | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `documents` * | array | Documentos da anáise da parte relacionada. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | *Campos obrigatórios. --- ### Definição de Documentos | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Identificador do documento. | 36 | | `document_type` * | string | Tipo do documento. | Ver **[Enumeradores de tipo de documento](#document-type)**. | | `status` | string | Status do documento. | Ver **[Enumeradores de status de documento](#document-status)**. | | `observation` | string | Observações enviadas. | - | *Campos obrigatórios. --- ### Definição de Conta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `account_branch` * | string | Agência da conta do cedente. | 4 | | `account_number` * | string | Número da conta do cedente. | 3 - 20 | | `account_digit` * | string | Dígito da conta do cedente. | 1 | | `financial_institution_code` * | string | Código do banco da conta do cedente. | 3 | | `account_type` * | string | Tipo de conta. | Ver **[Enumeradores de tipo de conta](#account-type)**. | | `default_account` * | boolean | Conta padrão de desembolso. | - | *Campos obrigatórios. Apenas uma conta do cedente pode ser a conta padrão, que será a conta para qual o dinheiro das cessões será enviado caso nenhuma conta alternativa seja indicada. Caso sejam enviadas mais de uma conta padrão, um erro será retornado. :::warning Atenção Muito cuidado ao preencher os dados da conta. Caso a conta seja inválida, o pagamento da cessão não ocorrerá, e toda a operação será cancelada. ::: --- ### Definição de Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Avalista. | 3 - 255 | | `document_number` * | string | Número de documento do avalista. | 14 a 18 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do avalista. | 1 a 255 | | `nationality` | string | País de origem do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `phone` | object | Objeto referenciando as informações do telefone do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `guarantor_representatives` | array | Assinantes do Avalista - Apenas para avalista pessoa jurídica. | Ver **[Definição de Representante do Avalista](#definição-de-representante-do-avalista)**. | | `marital_status` | string | Estado civil do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do avalista. | 1 a 255. | *Campos obrigatórios. O campo `guarantor_representatives` pode ser utilizado para indicar tanto representantes de um avalista pessoa jurídica, quanto, no caso de avalista pessoa física, onde se encontrar necessário, o cônjuge para realização da Outorga Uxória. :::warning Atenção Tanto o avalista quanto os representantes também serão adicionados à anáise gerada, sendo necessário enviar os documentos padrão de acordo com o tipo de pessoa do mesmo. Os mesmos também passam pelo processo de compliance, podendo gerar apontamentos. ::: --- ### Definição de Representante do Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Representante. | 3 - 255 | | `document_number` * | string | Número de documento do representante do avalista - obrigatóriamente pessoa física. | 14 | | `email` * | string | Endereço de e-mail do representante do avalista. | 1 a 255 | | `nationality` | string | País de origem do representante do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil do representante do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do representante do avalista. | 1 a 255. | --- # Enumeradores ### Assignor Registry Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **pending_registry** | Pendente Registro | | **registered** | Registrado | --- ### Analysis Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_documents** | Pendente Documentos | | **sent_to_analysis** | Enviado para Análise | | **pending_internal_validation** | Em Validação de documentos | | **in_manual_analysis** | Em Análise Manual de Compliance | | **approved** | Aprovado | | **reproved** | Reprovado | | **canceled** | Cancelado | --- ### Related Party Type | Enumerador | Descrição | | ----------------------- | ------------- | | **president** | Presidente | | **partner** | Sócio | | **administrator** | Administrador | | **director** | Diretor | | **manager** | Gestor | | **attorney** | Procurador | --- ### Document Status | Enumerador | Descrição | | ----------------------- | ------------- | | **created** | Criado | | **valid** | Válido | | **invalid** | Inválido | | **canceled** | Cancelado | | **accepted** | Aceito, porém não validado | --- ### Document Type | Enumerador | Descrição | | ---------------------------- | -------------------------- | | **cnh** | CNH. | | **rg_back** | RG parte traseira. | | **rg_front** | RG parte frontal. | | **passport** | Passaporte - exclusivo para estrangeiros. | | **national_migration_registry** | Registro Nacional de Migração. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. | | **board_election_record** | Ata de Eleição da Diretoria Vigente. | | **power_of_attorney** | Procuração - obrigatório caso o representante seja um procurador. | | **marital_power_of_attorney** | Procuração Uxória - disponível apenas para cônjuges. | | **compliance_statement** | Parecer de Compliance. | | **financial_statement** | Demonstração Financeira. | | **credit_report** | Ata/Parecer de Crédito. | | **manager_statement** | Parecer/Ficha do Gestor. | | **visit_report** | Relatório de Visita. | | **proof_of_residence** | Comprovante de Residência. | | **credit_agency_consulation** | Consulta aos órgãos de Proteção de Crédito. | | **annual_revenues_declaration** | Declaração de Faturamento. | | **financial_institutions_declaration** | Declaração de Relacionamento Bancário. | | **additional_document** | Documento adicional - livre. | --- ### Account Type | Enumerador | Descrição | |----------------------|---------------------| | **checking_account** | Conta Corrente | --- ### Analysis Reproval Reason | Enum | Description | |--------------|---------------| | **assignor_update** | Análise cancelada devido à atualização cadastral posterior | | **insuficient_documents** | Documentação mínima para comprovação de poderes não enviada | | **compliance_reproval** | Reprovação de vínculo por análise do time de compliance | | **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado | | **invalid_documents** | Documentação inválida/expirada | | **missing_related_parties** | Parte relacionada obrigatória não enviada | --- ### Marital Status | Enum | Description | |--------------|---------------| | **single** | Solteiro(a) | | **married** | Casado(a) | | **widower** | Viúvo(a) | | **divorced** | Divorciado(a) | | **separated** | Separado(a) | | **stable_union** | Em União Estável | --- ### Property System | Enum | Descrição | | --------------------------------- | -------------------------------------- | | **total_communion_of_goods** | Comunhão Total de Bens | | **partial_communion_of_goods** | Comunhão Parcial de Bens | | **total_separation_of_goods** | Separação Total de Bens | | **final_participation_of_acquisitions** | Participação Final nos Aquestos | | **compulsory_separation_of_goods** | Separação Obrigatória de Bens | --- # Envio de Documentos URL: /documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos Após o envio do cadastro do cedente, devem ser enviados os documentos relacionados ao mesmo. Para isso, é utilizada a estrutura de análise de documentos, onde, tanto na criação quanto na alteração, uma análise é gerada e os devidos documentos devem ser enviados. Cabe à gestora averiguar a operação do cedente que irá opear com os fundos geridos, e, futuramente, na etapa de criação de contrato mãe, será necessário assinar uma declaração da gestora, atestando que a mesma cumpriu toda a análise requerida pelo manual de Regras e Procedimentos de Administração e Gestão de Recursos de Terceiros, a qual encarrega à gestora tanto a análise quanto a atualização do cadastro do cedente. :::info Caso se trate de uma atualização, os documentos da última análise aprovada são automaticamente reaproveitados, podendo ser substituídos por novos. ::: --- ## Documentos do Cedente ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/document MÉTODO POST ```json title='Request Body' { "document_type":"social_contract", "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==", "observation":"CONTRATO SOCIAL ATUALIZADO", } ``` ## Objeto de Documento | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_type` * | string | Tipo do documento. | Ver **[Tipos de Documento ](#document-type)**. | | `document_b64` * | string | Deve ser o binário do arquivo em PDF, codificado em Base64. | - | | `observation` | string | Campo livre para descrever arquivos enviados. | 1 - 255 | *Campos obrigatórios. ### Response STATUS 201 ```json title='Response Body' { "document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a", "document_type": "social_contract", "analysis_key": "63db95c2-9985-405a-a521-6904f9e96cc6", "status": "valid" } ``` :::info Em caso de atualização cadastral, o envio de documentos específicos do cedente na análise será necessário somente quando houver alguma atualização nas informações que sejam **específicas do cedente**. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000039 | 400 | O status atual da análise não aceita novos documentos. | Documentos só podem ser anexados quando a análise estiver em `pending_documents`. Para reenviar após análise iniciada — ou se a análise tiver sido cancelada por inatividade (`canceled`) — gere uma nova análise via [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). | | ASR000005 | 400 | Formato de arquivo inválido. | Enviar `document_b64` como string em base64 válida. | | ASR000060 | 400 | O arquivo enviado não é um PDF válido. | O conteúdo decodificado de `document_b64` deve ser um PDF. | | ASR000059 | 400 | Tamanho do arquivo excede o limite. | Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). | | ASR000061 | 400 | Tipo de documento inválido para o cedente. | Usar um `document_type` compatível com o tipo de pessoa do cedente (ver tabela [Documentos padrão do cedente/avalista](#documentos-padrão-do-cedenteavalista)). | ## Documentos das partes relacionadas ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/document MÉTODO POST ```json title='Request Body' { "document_type":"cnh", "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==", "observation":"CNH Válida", } ``` ### Response STATUS 201 ```json title='Response Body' { "document_key": "afe8532a-4b0b-4e63-8d16-5084b2681752", "document_type": "cnh", "analysis_related_party_key": "fd1fb513-5ffc-4060-bca1-17deed680011", "status": "valid" } ``` :::info Em caso de atualização cadastral, o envio de documentos das partes relacionadas na análise será necessário somente quando houver alguma inclusão ou atualização de partes relacionadas do cedente. ::: :::caution Atenção! Caso um documento seja enviado com o tipo errado, ou com má qualidade ele pode retornar com o status **accepted**, indicando que a qualidade do mesmo está duvidosa, ou até **invalid**, assim sendo necessário reenviá-lo corretamente. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000035 | 404 | Parte relacionada da análise não encontrada para o `analysis_related_party_key` informado. | Verificar se o `analysis_related_party_key` retornado na criação da análise está correto. | | ASR000039 | 400 | O status atual da análise não aceita novos documentos. | Documentos só podem ser anexados quando a análise estiver em `pending_documents`. | | ASR000005 | 400 | Formato de arquivo inválido. | Enviar `document_b64` como string em base64 válida. | | ASR000060 | 400 | O arquivo enviado não é um PDF válido. | O conteúdo decodificado de `document_b64` deve ser um PDF. | | ASR000059 | 400 | Tamanho do arquivo excede o limite. | Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). | | ASR000062 | 400 | Tipo de documento inválido para a parte relacionada. | Usar um `document_type` compatível com o tipo de pessoa da parte relacionada (ver tabela [Documentos padrão das partes relacionadas/representantes](#documentos-padrão-das-partes-relacionadasrepresentantes)). | ## Cancelamento do envio de documento Com exceção do tipo additional_document, apenas um documento com status "valid" é permitido na análise. Caso, por algum motivo, deseje substituir um documento já válido, deve-se cancelá-lo. ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/document/DOCUMENT_KEY MÉTODO PUT OU ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/document/DOCUMENT_KEY MÉTODO PUT ```json title='Request Body' { "status":"canceled" } ``` ### Response STATUS 200 ```json title='Response Body' { "document_key": "afe8532a-4b0b-4e63-8d16-5084b2681752", "document_type": "cnh", "analysis_related_party_key": "fd1fb513-5ffc-4060-bca1-17deed680011", "status": "canceled" } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000006 | 404 | Documento da análise não encontrado para o `document_key` informado. | Verificar se o `document_key` pertence à análise indicada. | | ASR000036 | 404 | Documento da parte relacionada da análise não encontrado para o `document_key` informado. | Verificar se o `document_key` pertence à parte relacionada indicada (rota com `related_party`). | | ASR000076 | 400 | Status enviado não permitido para esse fluxo. | O único valor aceito para `status` neste endpoint é `canceled`. | --- ### Documentos padrão do cedente/avalista | Tipo de Pessoa | *document_type* | Descrição | Obrigatoriedade | |----------------|-------------------|------------|--------------| | Pessoa Física | cnh | CNH (Carteira Nacional de Habilitação) | * | | Pessoa Física | cin_digital | Carteira de Identidade Nacional (Digital) | * | | Pessoa Física | rg_back | RG (Carteira de Identidade) - Verso | * | | Pessoa Física | rg_front | RG (Carteira de Identidade) - Frente | * | | Pessoa Jurídica | social_contract | Contrato Social | Sempre | | Pessoa Jurídica | commercial_board_certificate | Ceridão Simplificada da Junta Comercial | Opcional, entretanto obrigatório para contratos sociais com data superior a 3 anos | | Pessoa Jurídica | board_election_record | Eleição da diretoria - se aplicável | Necessário para comprovação de vínculo | *Para quaisquer pessoas físicas, é necessário apenas um dentre RG frente e verso, CNH e Carteira de Identidade Nacional. ### Documentos padrão das partes relacionadas/representantes | Tipo de Pessoa | *document_type* | Descrição | Obrigatoriedade | |----------------|-------------------|------------|--------------| | Pessoa Física | cnh | CNH (Carteira Nacional de Habilitação) | * | | Pessoa Física | cin_digital | Carteira de Identidade Nacional (Digital) | * | | Pessoa Física | rg_back | RG (Carteira de Identidade) - Verso | * | | Pessoa Física | rg_front | RG (Carteira de Identidade) - Frente | * | | Pessoa Física | power_of_attorney | Procuração PF ou PJ - Obrigatório caso representante seja um procurador | Necessário para comprovação de vínculo | *Para quaisquer pessoas físicas, é necessário apenas um dentre RG frente e verso, CNH e Carteira de Identidade Nacional. :::warning Atenção Alguns tipos de documentos passam por uma ferramenta de OCR para extração e verificação dos dados. Deve-se sempre atentar ao retorno do envio de documento, que síncronamente retorna a validação - valid/accepted/invalid do OCR. ::: ## Tipos de Documento ### Document Type | Enumerador | Descrição | | ---------------------------- | -------------------------- | | **cnh** | CNH. | | **rg_back** | RG parte traseira. | | **rg_front** | RG parte frontal. | | **passport** | Passaporte - exclusivo para estrangeiros. | | **national_migration_registry** | Registro Nacional de Migração. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. | | **board_election_record** | Ata de Eleição da Diretoria Vigente. | | **power_of_attorney** | Procuração - obrigatório caso o representante seja um procurador. | | **marital_power_of_attorney** | Procuração Uxória - disponível apenas para cônjuges. | | **compliance_statement** | Parecer de Compliance. | | **financial_statement** | Demonstração Financeira. | | **credit_report** | Ata/Parecer de Crédito. | | **manager_statement** | Parecer/Ficha do Gestor. | | **visit_report** | Relatório de Visita. | | **proof_of_residence** | Comprovante de Residência. | | **credit_agency_consulation** | Consulta aos órgãos de Proteção de Crédito. | | **annual_revenues_declaration** | Declaração de Faturamento. | | **financial_institutions_declaration** | Declaração de Relacionamento Bancário. | | **additional_document** | Documento adicional - livre. | ### Document Status | Enumerador | Descrição | | ----------------------- | ------------- | | **created** | Criado | | **valid** | Válido | | **invalid** | Inválido | | **canceled** | Cancelado | | **accepted** | Aceito, porém não validado | --- # Cadastro de Filiais URL: /documentation/iaas/homologacao_cedente/cadastro/filiais Para a habilitação de filiais, existem dois fluxos operacionais que podem ser seguidos: 1. **Fluxo Completo (Do zero):** É o cadastro integral da filial, abrangendo desde dados de endereço e faturamento até informações de representantes legais e avalistas. Neste fluxo, a habilitação segue o processo padrão apresentado anteriormente na documentação, passando por aprovação de documentos e validação de poderes. Este fluxo exige um novo contrato de cessão para a efetiva habilitação do cedente no fundo. 2. **Fluxo Simplificado (Cadastro Vinculado):** Apresentado nesta página, este fluxo trata o cadastro da filial como um vínculo a uma matriz previamente cadastrada. Nele, apenas dados básicos são enviados e uma nova `assignor_registry_key` é criada, porém dados como representantes e avalistas são obrigatoriamente reaproveitados da análise da matriz. :::info Caso a filial já esteja cadastrada como cedente, também é possível vinculá-la à matriz. Nesse caso, a documentação, representação e avalistas anteriores são descartados, e a mesma passa a herdar os dados da matriz. ::: ## Vantagens do Fluxo Facilitado Existem duas principais vantagens no fluxo de ativação facilitada de filiais: * **Opções de Pagamento:** Ao realizar uma operação de cessão com a filial, as contas da matriz também se tornam opções de pagamento. * **Replicação de Configurações:** Todas as Configurações de Cessão da matriz são automaticamente replicadas para a filial assim que aprovada, evitando a necessidade da etapa de assinatura de contrato. Para recuperar as novas chaves, recomendamos a utilização do GET de configuração de cessão paginado, tópico 5.3.1.2., com parâmetros como `assignment_contract_key`, `asset_type` e `assignor_document_number`, utilizando o contrato formalizado pela matriz como referência. :::warning Atenção O fluxo facilitado de filiais exige a presença da seguinte cláusula no contrato mãe formalizado com a matriz para ser utilizado: > CONSIDERANDO que o CEDENTE declara e garante que, caso aplicável, é a matriz e detém plenos poderes para representar juridicamente todas as suas filiais perante a CESSIONÁRIA, inclusive para a prática de todos os atos necessários à formalização e à execução de cessões. O CEDENTE reconhece e assume responsabilidade solidária e ilimitada por todas as obrigações assumidas por suas filiais em decorrência de cessões realizadas junto à CESSIONÁRIA, renunciando, para todos os fins, a qualquer alegação de ausência de poderes ou de autonomia. ::: --- ## Criando uma nova Filial Por mais que o PLD da matriz já tenha sido realizado, a primeira análise (a de vínculo) de uma filial sempre passa pela etapa de consulta e validação de dados externa, sendo necessário aguardar o hook de aprovação ou reprovação da análise gerada, que é enviada automaticamente. ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/branch MÉTODO POST :::info A `assignor_registry_key` enviada na requisição deve pertencer à MATRIZ do cedente, e a mesma já deve estar habilitada. ::: ```json title='Request Body' { "document_number": "32.402.502/0002-16", "email": "qitechfilial@qitech.com.br", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360269" }, "address": { "street": "Rua Maria Carolina dois", "number": "624", "neighborhood": "Jardim Paulistano", "city": "Campinas", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "annual_revenues": 20000, "accounts": [ { "account_branch": "0001", "account_number": "0423223", "account_digit": "6", "financial_institution_code": "329", "account_type": "checking_account", "default_account": true } ] } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_number` * | string | Número de documento do cedente (CNPJ). | 14 a 18 | | `annual_revenues` * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 | | `email` * | string | Endereço de e-mail do cedente. | 1 a 255 | | `phone` | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `accounts` * | array | Lista de contas de desembolso do cedente.| Ver **[Definição de Conta](#definição-de-conta)**. | *Campos obrigatórios. ### Response STATUS 201 ```json title='Response Body' { "assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947", "status": "pending_registry", "name": "QI Tech", "document_number": "32.402.502/0002-16", "last_analysis": { "analysis_key": "49bcaaca-6029-4f6f-97a0-d71f7cefb7ae", "analysis_number": 1, "status": "sent_to_analysis", "analysis_related_parties": [ { "analysis_related_party_key": "65a74b18-0da8-4460-844b-524c9941e615", "document_number": "802.834.257-41", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [] }, { "analysis_related_party_key": "272cc251-a56d-4b89-82a1-d815a319b9fb", "passport_number": "C01X00T47", "name": "Maria Vitoria", "documents": [] } ], "documents": [ { "document_key": "5530af20-f52e-4a2e-b0f3-732e8121f4b3", "document_type": "social_contract", "status": "valid", } ], "analysis_data": {} } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. | | `name` | string | Nome do Cedente. | 1 a 255 | | `document_number` | string | Documento do Cedente. | 14 a 18 | | `last_analysis` | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. | :::info Toda informação de representação, avalistas e documentos serão automaticamente replicadas do cadastro da matriz. Entretanto, a conta enviada deve ser de titularidade da filial, caso contrário, futuras transferências falharão. ::: :::info É importante armazenar a assignor_registry_key, pois ela será utilizada em diversos outros processos, assim como a analysis_key e as analysis_related_party_key. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente matriz não encontrado para o `assignor_registry_key` informado. | Garantir que `assignor_registry_key` na URL corresponda ao cadastro da matriz. | | ASR000099 | 400 | Cedente pessoa física não pode ter filiais. | Apenas matrizes pessoa jurídica (`person_type=legal_person`) podem ter filiais. | | ASR000096 | 400 | Status da matriz não permite ativação de filial. | A matriz deve estar com `status=registered` para criar uma filial. | | ASR000097 | 400 | O cadastro referido não é uma matriz. | O `assignor_registry_key` na URL deve ser de um cadastro com `organization_level=headquarters`. | | ASR000098 | 400 | Raiz do CNPJ da filial não corresponde à da matriz. | A raiz (8 primeiros dígitos) do `document_number` da filial deve ser idêntica à da matriz. | | ASR000032 | 409 | Esse agente já cadastrou um cedente com esse `document_number`. | A filial já possui um cadastro vinculado a este agente; utilize o fluxo de [vínculo de filial existente](#vinculando-uma-filial-já-existente-à-matriz). | | ASR000071 | 404 | Instituição financeira não encontrada para a conta da filial. | Validar o `financial_institution_code` informado em `accounts`. | | ASR000087 | 400 | Informação de conta deve conter apenas números. | Enviar `account_branch`, `account_number` e `account_digit` apenas com dígitos. | | ASR000081 | 400 | Mais de uma conta padrão foi enviada. | Apenas uma conta deve ter `default_account=true`. | --- ## Vinculando uma filial já existente à matriz Caso tanto a filial quanto a matriz já existam em cadastros diferentes, é possível forçar o vínculo entre as duas. Nesse fluxo, todas as informações da filial que não compunham o payload da requisição de criação serão substituídas pelas informações da matriz. ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/branch MÉTODO PUT :::info A `assignor_registry_key` enviada na requisição deve pertencer à MATRIZ do cedente, e a mesma já deve estar habilitada. ::: ```json title='Request Body' { "branch_assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947", } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `branch_assignor_registry_key` * | string | Identificador do cadastro. | 36 | *Campos obrigatórios. ### Response STATUS 200 ```json title='Response Body' { "assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947", "status": "pending_registry", "name": "QI Tech", "document_number": "32.402.502/0002-16", "last_analysis": { "analysis_key": "49bcaaca-6029-4f6f-97a0-d71f7cefb7ae", "analysis_number": 1, "status": "sent_to_analysis", "analysis_related_parties": [ { "analysis_related_party_key": "65a74b18-0da8-4460-844b-524c9941e615", "document_number": "802.834.257-41", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [] }, { "analysis_related_party_key": "272cc251-a56d-4b89-82a1-d815a319b9fb", "passport_number": "C01X00T47", "name": "Maria Vitoria", "documents": [] } ], "documents": [ { "document_key": "5530af20-f52e-4a2e-b0f3-732e8121f4b3", "document_type": "social_contract", "status": "valid", } ], "analysis_data": {} } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. | | `name` | string | Nome do Cedente. | 1 a 255 | | `document_number` | string | Documento do Cedente. | 14 a 18 | | `last_analysis` | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. | ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente matriz ou filial não encontrado. | Garantir que `assignor_registry_key` na URL pertença à matriz e que `branch_assignor_registry_key` no body pertença a um cadastro existente do mesmo agente. | | ASR000099 | 400 | Cedente pessoa física não pode ter filiais. | Apenas matrizes pessoa jurídica podem vincular filiais. | | ASR000096 | 400 | Status da matriz não permite vínculo de filial. | A matriz deve estar com `status=registered`. | | ASR000097 | 400 | O cadastro referido não é uma matriz. | O `assignor_registry_key` na URL deve ser de um cadastro com `organization_level=headquarters`. | | ASR000098 | 400 | Raiz do CNPJ da filial não corresponde à da matriz. | A raiz (8 primeiros dígitos) do `document_number` da filial deve ser idêntica à da matriz. | --- ## Atualizando dados de uma Filial Por mais que seja um cadastro vinculado, as informações da filial ainda podem ser atualizadas, porém com algumas restrições: Informações como email, phone, address e annual_revenues podem ser atualizadas utilizando o mesmo endpoint utilizado para alterar dados da matriz (apresentado abaixo). Entretanto, dados como name, related_parties, guarantors e a documentação em si devem ser atualizados sempre na Matriz. Quando a alteração da matriz é aprovada, todas as filiais vinculadas replicam os dados automaticamente. ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY MÉTODO PUT ```json title='Request Body' { "email": "qidtvm@qitech.com.br", "annual_revenues": 1000000, "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `annual_revenues` | number | Declaração de faturamento anual do cedente. | - | | `email` | string | Endereço de e-mail do cedente. | 1 a 255 | | `phone` | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. | Caso não deseje alterar um campo, basta não enviá-lo na request. ### Response STATUS 200 ```json title='Response Body' { "assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947", "status": "registred", "name": "QI Tech", "document_number": "32.402.502/0002-16", "last_analysis": { "analysis_key": "f51a49e1-842c-471f-a0e1-32ee9f12625d", "analysis_number": 2, "status": "approved", "analysis_related_parties": [ { "analysis_related_party_key": "f361763a-91f5-4688-8e28-cc3f3fbccf9a", "document_number": "802.834.257-41", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "7ea3193b-8e53-40b7-94cf-2d3cc62942e0", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [] }, { "analysis_related_party_key": "f321f063-5f9a-4964-a24a-52deba128160", "passport_number": "C01X00T47", "name": "Maria Vitoria", "documents": [] } ], "documents": [ { "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017", "document_type": "social_contract", "status": "valid", } ], "analysis_data": {} } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. | | `name` | string | Nome do Cedente. | 1 a 255 | | `document_number` | string | Documento do Cedente. | 14 a 18 | | `last_analysis` | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. | :::info Diferente do cadastro de uma matriz, como as alterações não envolvem dados de representação e PLD, a alteração da filial é sempre aprovada AUTOMATICAMENTE. ::: :::info A manutenção de contas segue exatamente a mesma lógica da manutenção de contas da matriz, segundo a aba 5.2.2.5. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente filial não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` na URL corresponde a um cadastro de filial. | | ASR000100 | 400 | Campo enviado não pode ser atualizado em uma filial. | Em filiais, somente `email`, `phone`, `address` e `annual_revenues` podem ser atualizados. Para alterar `name`, `is_in_national_financial_system`, `related_parties` ou `guarantors`, atualizar o cadastro da matriz (ver [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro)). | --- ## Definições ### Definição de Endereço | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `street` * | string | Nome da rua. | 1 a 255 | | `number` * | string | Número do endereço. | 1 a 4 | | `neighborhood` * | string | Bairro. | 1 a 255 | | `city` * | string | Cidade. | 1 a 255 | | `uf` * | string | Sigla do estado. | 2 | | `complement` | string | Complemento do endereço. | 1 a 255 | | `postal_code` * | string | Código postal. | 9 (formato: XXXXX-XXX) | | `country` * | string | País (sigla). | 3, de acordo com a ISO 3166-1 alpha-3 | *Campos obrigatórios. --- ### Definição de Telefone | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `international_dial_code` * | string | Código internacional de discagem. | 1 a 3 | | `area_code` * | string | Código de área. | 2 | | `number` * | string | Número de telefone. | 8 a 9 | *Campos obrigatórios. --- ### Definição de Parte Relacionada | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `document_number` ** | string | Número de documento do beneficiário (CPF). | 14 a 18 | | `passport_number` ** | string | Número de documento do beneficiário estrangeiro. | 8 a 9 | | `related_party_type` * | string | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `direct_beneficiary` * | boolean | Beneficiário diretamente ou indiretamente ligado ao cedente. | 1 a 255 | | `is_representative` * | boolean | Indicador se a parte relacionada é representante assinante do cedente. | 1 a 255 | | `company_registry_number` *** | string | Caso não seja diretamente ligado ao cedente, à qual companhia o mesmo está ligado. | 1 a 255 | | `company_country` *** | string | País onde a companhia-elo entre o beneficiário e o cedente está registrada. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `email` **** | string | Endereço de e-mail do representante. | 1 a 255 | | `phone` | object | Objeto referenciando as informações do telefone do representante. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil da parte relacionada. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão da parte relacionada. | 1 a 255. | *Campos obrigatórios. **document_number obrigatório para brasileiros, para estrangeiros, caso tenha CPF, é possível utilizar o document_number, caso contrário, pelo menos o passport_number deve ser enviado. ***Campos obrigatórios caso a parte relacionada não seja beneficiário diretamente ligada ao cedente. Caso contrário, não devem ser enviados. ****Campos exigidos apenas para representantes assinantes. :::info Campos não obrigatorios, como `marital_status` e `address`, podem ser enviados caso deseje uma qualificação mais completa no contrato mãe de cessão, nas etapas futuras. ::: --- ### Definição de Análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_key` * | string | Identificador da análise. | 36 | | `analysis_number` * | integer | Número sequencial da análise. | - | | `status` * | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. | | `analysis_related_parties` * | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. | | `documents` * | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | | `analysis_data` * | object | Payload da request que originou a análise. | - | | `analysis_datetime` * | string | Objeto date time da criação da análise. | - | | `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. | | `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - | *Campos obrigatórios. --- ### Definição de Partes Relacionadas de análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_related_party_key` * | string | Identificador da parte relacionada. | 36 | | `document_number` * | string | Número de documento da parte relacionada. | 14 a 18 | | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `documents` * | array | Documentos da anáise da parte relacionada. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | *Campos obrigatórios. --- ### Definição de Documentos | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Identificador do documento. | 36 | | `document_type` * | string | Tipo do documento. | Ver **[Enumeradores de tipo de documento](#document-type)**. | | `status` | string | Status do documento. | Ver **[Enumeradores de status de documento](#document-status)**. | | `observation` | string | Observações enviadas. | - | *Campos obrigatórios. --- ### Definição de Conta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `account_branch` * | string | Agência da conta do cedente. | 4 | | `account_number` * | string | Número da conta do cedente. | 3 - 20 | | `account_digit` * | string | Dígito da conta do cedente. | 1 | | `financial_institution_code` * | string | Código do banco da conta do cedente. | 3 | | `account_type` * | string | Tipo de conta. | Ver **[Enumeradores de tipo de conta](#account-type)**. | | `default_account` * | boolean | Conta padrão de desembolso. | - | *Campos obrigatórios. Apenas uma conta do cedente pode ser a conta padrão, que será a conta para qual o dinheiro das cessões será enviado caso nenhuma conta alternativa seja indicada. Caso sejam enviadas mais de uma conta padrão, um erro será retornado. :::warning Atenção Muito cuidado ao preencher os dados da conta. Caso a conta seja inválida, o pagamento da cessão não ocorrerá, e toda a operação será cancelada. ::: --- ### Definição de Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Avalista. | 3 - 255 | | `document_number` * | string | Número de documento do avalista. | 14 a 18 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do avalista. | 1 a 255 | | `nationality` | string | País de origem do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `phone` | object | Objeto referenciando as informações do telefone do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `guarantor_representatives` | array | Assinantes do Avalista - Apenas para avalista pessoa jurídica. | Ver **[Definição de Representante do Avalista](#definição-de-representante-do-avalista)**. | | `marital_status` | string | Estado civil do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do avalista. | 1 a 255. | *Campos obrigatórios. O campo `guarantor_representatives` pode ser utilizado para indicar tanto representantes de um avalista pessoa jurídica, quanto, no caso de avalista pessoa física, onde se encontrar necessário, o cônjuge para realização da Outorga Uxória. :::warning Atenção Tanto o avalista quanto os representantes também serão adicionados à anáise gerada, sendo necessário enviar os documentos padrão de acordo com o tipo de pessoa do mesmo. Os mesmos também passam pelo processo de compliance, podendo gerar apontamentos. ::: --- ### Definição de Representante do Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Representante. | 3 - 255 | | `document_number` * | string | Número de documento do representante do avalista - obrigatóriamente pessoa física. | 14 | | `email` * | string | Endereço de e-mail do representante do avalista. | 1 a 255 | | `nationality` | string | País de origem do representante do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil do representante do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do representante do avalista. | 1 a 255. | --- # Enumeradores ### Assignor Registry Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **pending_registry** | Pendente Registro | | **registered** | Registrado | --- ### Analysis Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_documents** | Pendente Documentos | | **sent_to_analysis** | Enviado para Análise | | **pending_internal_validation** | Em Validação de documentos | | **in_manual_analysis** | Em Análise Manual de Compliance | | **approved** | Aprovado | | **reproved** | Reprovado | | **canceled** | Cancelado | --- ### Related Party Type | Enumerador | Descrição | | ----------------------- | ------------- | | **president** | Presidente | | **partner** | Sócio | | **administrator** | Administrador | | **director** | Diretor | | **manager** | Gestor | | **attorney** | Procurador | --- ### Document Status | Enumerador | Descrição | | ----------------------- | ------------- | | **created** | Criado | | **valid** | Válido | | **invalid** | Inválido | | **canceled** | Cancelado | | **accepted** | Aceito, porém não validado | --- ### Document Type | Enumerador | Descrição | | ---------------------------- | -------------------------- | | **cnh** | CNH. | | **rg_back** | RG parte traseira. | | **rg_front** | RG parte frontal. | | **passport** | Passaporte - exclusivo para estrangeiros. | | **national_migration_registry** | Registro Nacional de Migração. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. | | **board_election_record** | Ata de Eleição da Diretoria Vigente. | | **power_of_attorney** | Procuração - obrigatório caso o representante seja um procurador. | | **marital_power_of_attorney** | Procuração Uxória - disponível apenas para cônjuges. | | **compliance_statement** | Parecer de Compliance. | | **financial_statement** | Demonstração Financeira. | | **credit_report** | Ata/Parecer de Crédito. | | **manager_statement** | Parecer/Ficha do Gestor. | | **visit_report** | Relatório de Visita. | | **proof_of_residence** | Comprovante de Residência. | | **credit_agency_consulation** | Consulta aos órgãos de Proteção de Crédito. | | **annual_revenues_declaration** | Declaração de Faturamento. | | **financial_institutions_declaration** | Declaração de Relacionamento Bancário. | | **additional_document** | Documento adicional - livre. | --- ### Account Type | Enumerador | Descrição | |----------------------|---------------------| | **checking_account** | Conta Corrente | --- ### Analysis Reproval Reason | Enum | Description | |--------------|---------------| | **assignor_update** | Análise cancelada devido à atualização cadastral posterior | | **insuficient_documents** | Documentação mínima para comprovação de poderes não enviada | | **compliance_reproval** | Reprovação de vínculo por análise do time de compliance | | **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado | | **invalid_documents** | Documentação inválida/expirada | | **missing_related_parties** | Parte relacionada obrigatória não enviada | --- ### Marital Status | Enum | Description | |--------------|---------------| | **single** | Solteiro(a) | | **married** | Casado(a) | | **widower** | Viúvo(a) | | **divorced** | Divorciado(a) | | **separated** | Separado(a) | | **stable_union** | Em União Estável | --- ### Property System | Enum | Descrição | | --------------------------------- | -------------------------------------- | | **total_communion_of_goods** | Comunhão Total de Bens | | **partial_communion_of_goods** | Comunhão Parcial de Bens | | **total_separation_of_goods** | Separação Total de Bens | | **final_participation_of_acquisitions** | Participação Final nos Aquestos | | **compulsory_separation_of_goods** | Separação Obrigatória de Bens | --- # Contas do cedente URL: /documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas No ato do cadastro do cedente, é obrigatório providenciar ao menos uma conta de desembolso de cessão para o cedente. Na etapa de aprovação da cessão pela gestora, é possível indicar qualquer uma das contas cadastradas para o cedente para ocorrer o desembolso da mesma. Vale ressaltar que, caso o proponente da operação entre cedente-fundo seja um consultor, a manutenção das contas será de responsabilidade da consultoria ao invś da gestora. Diferente de dados cadastrais, como representantes, endereços, e outros dados, não será criada uma nova análise ao realizar uma alteração nas contas do cedente, sendo assim, a alteração passa a valer de imediato. Para uma conta de desembolso, obrigatóriamente o titular da conta deve ser o cedente, inclusive a titularidade da conta, e o número de documento do dono da conta já é assumido ser o do cedente. :::warning Atenção Muito cuidado ao preencher os dados da conta. Caso a conta seja inválida, o pagamento da cessão não ocorrerá, e toda a operação será cancelada. ::: --- ## Adição de conta alternativa ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/account MÉTODO POST ```json title='Request Body' { "account_number": "8473124", "account_digit": "8", "account_branch": "0001", "account_type": "checking_account", "financial_institution_code": "329", "default_account": false } ``` ## Objeto de Conta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `account_number` * | string | Número da conta. | 3-20 | | `account_digit` * | string | Dígito da conta. | 1 | | `account_branch` * | string | Agência da conta. | 4 | | `account_type` * | string | Tipo da conta. | - | | `financial_institution_code` * | string | Código do banco da conta. | 3 | | `default_account` * | boolean | Conta padrão de desembolso. | - | *Campos obrigatórios. ### Response STATUS 201 ```json title='Response Body' { "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c", "account_branch": "0001", "account_number": "8473124", "account_digit": "8", "account_type": "checking_account", "status": "active", "financial_institution_code": "329", "financial_institution_ispb": "32402502", "default_account": false, } ``` :::info Caso a conta nova seja enviada com "default_account" true, a antiga conta padrão de desembolso será tornada uma conta não padrão, e a partir de então, a nova conta postada será a padrão de desembolso. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000072 | 409 | Já existe uma conta ativa com a mesma combinação de banco, agência, conta e dígito. | Não enviar contas duplicadas — verificar as contas já cadastradas para o cedente. | | ASR000087 | 400 | Informação de conta deve conter apenas números. | Enviar `account_branch`, `account_number`, `account_digit` e `financial_institution_code` apenas com dígitos. | | ASR000071 | 404 | Instituição financeira não encontrada. | Validar o `financial_institution_code` (código bancário) informado. | ## Atualização de conta Não é possível alterar os dados de uma conta. Caso deseje, é necessário desativar a conta errada, e criar uma nova conta com os dados válidos. Para alterar a conta padrão de desembolso, basta indicar qual será a nova conta, que a antiga será alterada automaticamente. Não é possível definir uma conta como não padrão de desembolso, deve-se sempre indicar a nova. ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/account/ACCOUNT_KEY MÉTODO PUT ```json title='Request Body' { "status": "active", "default_account": true, } ``` ## Objeto de Conta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `status` | string | Novo status da conta. | Ver **[Enumeradores de status de conta](#account-status)**. | | `default_account` | boolean | Conta padrão de desembolso. | - | *Campos obrigatórios (nenhum). ### Response STATUS 200 ```json title='Response Body' { "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c", "account_branch": "0001", "account_number": "8473124", "account_digit": "8", "account_type": "checking_account", "status": "active", "financial_institution_code": "329", "financial_institution_ispb": "32402502", "default_account": true, } ``` :::info Caso a atualização enviada com "default_account" true, a antiga conta padrão de desembolso será tornada uma conta não padrão, e a partir de então, a nova conta postada será a padrão de desembolso. Não é possível desativar uma conta padrão, ou definir como padrão uma conta inativa. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000073 | 404 | Conta não encontrada para o `account_key` informado. | Verificar se o `account_key` pertence ao cedente. | | ASR000074 | 400 | Não é possível desativar/desmarcar uma conta padrão. | Indicar primeiro outra conta como padrão (`default_account=true` em outra conta) antes de inativar a atual. | | ASR000075 | 400 | Nenhuma informação foi enviada para atualização. | Informar `status` ou `default_account` no corpo da requisição. | # Enumeradores ### Account Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **active** | Conta ativa e disponível como opção de desembolso. | | **inactive** | Conta inativa e indisponível para desembolo. | --- # Webhooks URL: /documentation/iaas/homologacao_cedente/cadastro/webhooks_analise --- ## Webhooks de Análise --- #### Drivação para Compliance STATUS in_manual_analysis ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "analysis_status": "in_manual_analysis", "reproval_reason": null, "reproval_details": null, }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Em análise de Documentos STATUS pending_internal_validation ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "analysis_status": "pending_internal_validation", "reproval_reason": null, "reproval_details": null, }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Aprovado STATUS approved ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "approved", "reproval_reason": null, "reproval_details": null, }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Reprovado STATUS reproved ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "reproved", "reproval_reason": "insuficient_documents", "reproval_details": "Anexar procuração do sócio XXX.XXX.XXX-XX.", }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Cancelado STATUS canceled Disparado quando uma análise é cancelada. O caso mais comum é o **cancelamento automático por inatividade**: uma análise que fica **1 mês sem movimentação** — tipicamente parada em `pending_documents`, sem documentos anexados ou sem o disparo da análise — é cancelada pela QI Tech. O status é **terminal**. Para retomar o cadastro, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "analysis_status": "canceled", "reproval_reason": null, "reproval_details": null, }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` ## Webhooks de Apontamento --- Disparados sempre que um [Apontamento de Compliance](/documentation/iaas/homologacao_cedente/cadastro/apontamentos) tem seu status alterado. São enviados quando o apontamento é aberto (`open`) e quando é respondido (`closed`). :::info Apontamentos originados por carga da Fromtis (`fromtis_load`) não disparam webhook. ::: #### Apontamento aberto STATUS open ```json title='Webhook Body' { "data":{ "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "annotation_status": "open", "message": "Anexar procuração do sócio XXX.XXX.XXX-XX.", }, "webhook_type":"assignor_registry.annotation_status_change", "webhook_datetime":"2025-01-22T20:30:23Z" } ``` #### Apontamento respondido STATUS closed ```json title='Webhook Body' { "data":{ "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "annotation_status": "closed", "message": "Anexar procuração do sócio XXX.XXX.XXX-XX.", }, "webhook_type":"assignor_registry.annotation_status_change", "webhook_datetime":"2025-01-22T20:30:23Z" } ``` ## Webhooks de Cadastro --- #### Cedente ativado STATUS registered ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "registered", }, "webhook_type":"assignor_registry.assignor_registry_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Cedente expirado STATUS expired ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "expired", }, "webhook_type":"assignor_registry.assignor_registry_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` --- # Consulta de Análise URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_analise --- O campo `status` da análise segue os **[Enumeradores de status de análise](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#analysis-status)**. :::info Status `canceled` Uma análise que fica **1 mês sem movimentação** — tipicamente parada em `pending_documents`, sem documentos anexados ou sem o disparo da análise — é **cancelada automaticamente** e passa a `canceled`. O status é terminal: a análise não aceita mais documentos nem disparo. Para retomar o cadastro, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). ::: ## Consulta de Análise Por Chave ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_documents", "documents": [ { "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017", "document_type": "social_contract", "status": "valid", } ], "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Natália Nascimento", "documents": [ { "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba", "document_type": "cnh", "status": "valid", } ] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [ { "document_key": "8b9fe448-7ad7-4410-b8f7-5c920b07b9a7", "document_type": "cnh", "status": "valid", } ] } ], "analysis_data": { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_registry", "name": "QI CTVM", "document_number": "67.987.787/0001-06", "person_type": "legal_person", "email": "qidtvm@qitech.com.br", "phone": { "number": "936360268", "area_code": "11" }, "address": { "uf": "SP", "city": "São Paulo", "number": "215", "street": "Gilberto Sabino", "country": "BRA", "postal_code": "05425-020", "neighborhood": "Pinheiros" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "4984037284610", "is_representative": true, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ] } } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | --- ## Consulta Paginada de Análises ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analyses MÉTODO GET ### Path params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `limit` | integer | Limite de objetos | - | | `page` | integer | Página desejada | - | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_documents", "documents": [ { "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017", "document_type": "social_contract", "status": "valid", } ], "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Natália Nascimento", "documents": [ { "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba", "document_type": "cnh", "status": "valid", } ] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [ { "document_key": "8b9fe448-7ad7-4410-b8f7-5c920b07b9a7", "document_type": "cnh", "status": "valid", } ] } ], } ], "limit": 10, "page": 0, "is_last_page": true, } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | --- # Consulta de Assinantes URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes Consulta **paginada** dos conjuntos de assinantes (`signer_group_sets`) vinculados ao cedente e às suas partes relacionadas. Retorna tanto os conjuntos padrão (`main`), gerados pela análise da Administradora, quanto os conjuntos customizados (`custom`) definidos pelo cliente. :::info Informação Cada conjunto está vinculado a um proprietário (`owner`), que pode ser o **cedente** (`assignor_registry`) ou uma **parte relacionada de análise** (`analysis_related_party`, de avalistas), e a um tipo de produto. Para criar conjuntos customizados, consulte [Definição de Assinantes](/documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes). ::: --- ## Consulta Paginada de Conjuntos de Assinantes ### Request ENDPOINT /assignor_registry/signer_group_sets MÉTODO GET #### Query Parameters | Campo | Tipo | Descrição | |-------|------|-----------| | `limit` | integer | Quantidade de itens por página (0 a 50). Padrão: 10. | | `page` | integer | Página a ser consultada, iniciando em 0. Padrão: 0. | | `owner_key` | string | Filtra pelo identificador do proprietário (cedente ou parte relacionada). | | `owner_type` | string | Tipo do proprietário. Ver **[Owner Type](#owner-type)**. | | `owner_document_number` | string | Documento do proprietário. Exige `owner_type` para ser utilizado. | | `product_type` | string | Filtra por tipo de produto. Ver **[Product Type](#product-type)**. | | `status` | string | Filtra pelo status do conjunto. Ver **[Signer Group Set Status](#signer-group-set-status)**. | :::tip Dica Para listar apenas os conjuntos que estão efetivamente sendo utilizados nas assinaturas, filtre por `status=valid`. Conjuntos em `in_analysis` ainda dependem da aprovação do cadastro e não são enviados para assinatura. ::: ### Response STATUS 200 ```json title='Response Body' { "data": [ { "signer_group_set_key": "f2c1e4a8-91d2-4f10-8a3b-7e5c9b2d4a6e", "owner_key": "c4295375-4077-4092-a258-5bcdf8875907", "owner_type": "assignor_registry", "product_type": "assignment_contract", "signer_group_set_type": "custom", "status": "valid", "signer_groups": [ { "minimum_required_signers": 2, "signers": [ { "document_number": "883.512.866-80", "is_required_signer": true }, { "document_number": "802.834.257-41", "is_required_signer": false } ], "expiration": null } ] } ], "limit": 10, "page": 0, "is_last_page": true } ``` #### Campos de Paginação | Campo | Tipo | Descrição | |-------|------|-----------| | `data` | array | Lista de conjuntos de assinantes da página atual. Ver **[Definição de Conjunto de Assinantes](#definicao-de-conjunto-de-assinantes-signer-group-set)**. | | `limit` | integer | Quantidade de itens por página utilizada na consulta. | | `page` | integer | Página retornada, iniciando em 0. | | `is_last_page` | boolean | Indica se esta é a última página do resultado. | ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000121 | 400 | `owner_document_number` enviado sem `owner_type`. | Ao filtrar por `owner_document_number`, sempre informar também `owner_type`. | | ASR000120 | 400 | Valor de `status` inválido no filtro. | Usar um valor válido para o filtro `status` (ver enum [Signer Group Set Status](#signer-group-set-status)). | --- ## Definições ### Definição de Conjunto de Assinantes (Signer Group Set) | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `signer_group_set_key` | string | Identificador único do conjunto. | 36 | | `owner_key` | string | Identificador do proprietário. Pode ser `assignor_registry_key` ou `analysis_related_party_key`. | 36 | | `owner_type` | string | Tipo do proprietário. | Ver **[Owner Type](#owner-type)**. | | `product_type` | string | Tipo de produto ao qual o conjunto está associado. | Ver **[Product Type](#product-type)**. | | `signer_group_set_type` | string | Tipo do conjunto (`main` ou `custom`). | Ver **[Signer Group Set Type](#signer-group-set-type)**. | | `status` | string | Status do conjunto. | Ver **[Signer Group Set Status](#signer-group-set-status)**. | | `signer_groups` | array | Lista de grupos de assinantes que compõem o conjunto. | Ver **[Definição de Grupo de Assinantes](#definicao-de-grupo-de-assinantes-signer-group)**. | --- ### Definição de Grupo de Assinantes (Signer Group) | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `minimum_required_signers` | number | Quantidade mínima de assinantes do grupo necessários para validar a assinatura. | Mínimo 1 | | `signers` | array | Lista de assinantes do grupo. | Ver **[Definição de Assinante](#definicao-de-assinante-signer)**. | | `expiration` | string | Data de expiração do grupo no formato `YYYY-MM-DD`. Retorna `null` quando o grupo não expira. | 10 | --- ### Definição de Assinante (Signer) | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_number` | string | CPF do assinante no formato `XXX.XXX.XXX-XX`. | 14 | | `is_required_signer` | boolean | Indica se o assinante é obrigatório no grupo. | - | --- # Enumeradores ### Owner Type | Enumerador | Descrição | |------------|-----------| | **assignor_registry** | Conjunto vinculado ao cedente. | | **analysis_related_party** | Conjunto vinculado a uma parte relacionada da análise (avalistas). | --- ### Product Type | Enumerador | Descrição | |------------|-----------| | **assignment_contract** | Contrato de cessão (utilizado por padrão). | | **commercial_paper** | Nota Comercial (Cadastro único com a plataforma de escrituração). | --- ### Signer Group Set Type | Enumerador | Descrição | |------------|-----------| | **main** | Conjunto padrão, gerado da análise da Administradora. | | **custom** | Conjunto customizado, criado pelo cliente sobrepondo o conjunto `main`. | --- ### Signer Group Set Status | Enumerador | Descrição | |------------|-----------| | **in_analysis** | Conjunto enviado e atrelado à análise em aberto. Não é utilizado nas assinaturas. | | **valid** | Conjunto vigente e utilizado nas assinaturas. | | **inactive** | Conjunto substituído por uma versão mais recente ou desativado. | --- # Consulta de Cedente URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente --- ## Consulta de Cedente Por Chave ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY MÉTODO GET --- ### Response STATUS 200 ```json title='Response Body' { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "registred", "name": "QI CTVM", "document_number": "67.987.787/0001-06", "person_type": "legal_person", "email": "qidtvm@qitech.com.br", "annual_revenues": 1000000, "is_in_national_financial_system": true, "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "4984037284610", "is_representative": true, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ], "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_documents", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Natália Nascimento", }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", } ], "documents": [], "analysis_data": {} } } ``` ### Objeto Cedente | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `name` * | string | Nome do cedente. | 1 a 255 | | `document_number` * | string | Número de documento do cedente (CNPJ). | 14 a 18 | | `status` | enumerador | Status do cadastro. | 14 a 18 | | `annual_revenues` * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do cedente. | 1 a 255 | | `is_in_national_financial_system` * | boolean | Indicador se o cedente é integrante do SFN. | - | | `phone` | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-telefone)**. | | `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-endereco)**. | | `related_parties` * | array | Lista de partes relacionadas da empresa.| Ver **[Definição de Parte Relacionada](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-parte-relacionada)**. | | `accounts` * | array | Lista de contas de desembolso do cedente.| Ver **[Definição de Conta](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-conta)**. | | `guarantors` * | array | Lista de avalistas do cedente.| Ver **[Definição de Avalista](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-avalista)**. | ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | --- ## Consulta Paginada de Cedentes ### Request ENDPOINT /assignor_registry/assignor_registries MÉTODO GET ### Path params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `name` | string | Nome do cedente | 1-255 | | `document_number` | string | Número de documento do cedente | 1-18 | | `assignor_registry_status` | string | Status do cedente | 1-255 | | `analysis_status` | string | Status da análise mais recente | 1-255 | | `limit` | integer | Limite de objetos | - | | `page` | integer | Página desejada | - | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "registred", "name": "QI CTVM", "document_number": "67.987.787/0001-06", "person_type": "legal_person", "email": "qidtvm@qitech.com.br", "annual_revenues": 1000000, "is_in_national_financial_system": true, "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "49.846.582/0001-10", "is_representative": true, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ], "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_documents", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Natália Nascimento", }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", } ], "documents": [], "analysis_data": {} } } ], "limit": 10, "page": 0, "is_last_page": true, } ``` --- ## Consulta de Conjuntos de Assinantes A consulta dos assinantes vinculados ao cedente e suas partes relacionadas é feita através do endpoint paginado de conjuntos de assinantes (`signer_group_sets`), que retorna tanto os conjuntos padrão (`main`) gerados pela análise quanto os conjuntos customizados (`custom`) definidos pelo cliente. Para a especificação completa do endpoint — incluindo filtros disponíveis (`owner_key`, `owner_type`, `owner_document_number`, `product_type` e `status`), paginação, formato de resposta e enumeradores —, consulte [Consulta de Assinantes](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes). --- --- # Ativação do Produto URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/ativacao_da_esteira --- Para ativar o produto, basta escolher dentre as opções de um contrato qual produto deseja-se ativar. Uma vez escolhido, deve-se fazer uma requisição e esperar o Webhook com a assignment_configuration_key. ### Request ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY/product/PRODUCT_KEY MÉTODO PUT ```json title='Request Body' { "disbursement":{ "target_account": { "account_branch": "0001", "account_digit": "1", "account_number": "92268", "financial_institution_code": "329", "account_type": "checking_account", "owner": { "document_number": "44.450.102/0001-84" } } } } ``` ### Response STATUS 200 ```json title='Response Body' { "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "pending_activation" } ``` --- # Consultar Documentos URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos --- ### Request ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY/attached_document/DOCUMENT_KEY MÉTODO GET ### Path Params | Parâmetro | Descrição | |------------------------------|------------------------------------| | `assignment_contract_key` | Chave da contrato de cessão | | `document_key` | Chave do documento | ### Response STATUS 200 ```json { "document_key":"UUID", "document_type":"manager_declaration | assignment_contract", "status":"signed | pending_signature", "document_template_key":"UUID", "required_parties":[ "manager | consultant | attestant" ], "download_url":"url para download do documento" } ``` :::info Observação O campo de download url trás a URL assinada para download do documento em sua versão mais atual, ou seja caso o documento esteja assinado ele vai trazer nesta mesma URL. A mesma expira, e não deve ser utilizada para consulta atemporal. ::: ### Definição de Documento Anexo | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Chave única de identificação do documento. | 36 | | `document_type` * | string | Tipo do documento. | -- | | `status` * | string | Status do documento. | Ver **[Enumeradores de status do documento](#attached-document-status)**. | | `document_template_key` | string | Chave única de identificação do template que gerou o documento. | 36 | | `required_parties` | array | Lista de partes que assinam o documento em questão. | -- | | `download_url` | string | URL de download do PDF. | -- | ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. | | ACT000087 | 404 | Documento anexo não encontrado para o `document_key` informado. | Verificar se o `document_key` pertence ao contrato indicado. | # Enumeradores ### Attached Document Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_generate** | Pendente geração do documento | | **approved** | Documento gerado | | **signed** | Documento assinado | --- # Manipulação de contrato URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/manutencao_do_contrato --- Dependendo do fluxo, pode ser necessário realizar algumas chamadas para concluir o fluxo de um contrato. --- # Aprovação do Gestor --- Caso o contrato seja proposto por uma consultoria, após a geração dos documentos, será necessária a aprovação do gestor, antes que o mesmo sja enviado para assinatura. ### Request ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY MÉTODO PUT ```json title='Request Body' { "status": "denied", "denial_reason": "Documentação do cedente insuficiente", } ``` #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `status` * | string | Decisão do Gestor. denied ou approved | -- | | `denial_reason` | string | Descritivo com o motivo da recusa. | 1 a 500 | *Campos obrigatórios ### Response STATUS 202 ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. | | ACT000025 | 400 | Apenas gestores podem realizar a aprovação ou recusa. | A aprovação/recusa deve ser feita por um agente com `AGENT-TYPE=manager`. | | ACT000077 | 400 | Status atual do contrato não permite aprovação ou recusa. | Para `approved`: o contrato deve estar em `pending_manager_approval`. Para `denied`: o contrato deve estar em `pending_manager_approval` ou `pending_document`. | --- # Envio para Assinatura Manual --- Caso o template configure envio manual para assinatura, é possível agrupar vários contratos, desde que os mesmos tenham o mesmo gestor, cedente e avalistas, para um mesmo lote de assinaturas. ### Request ENDPOINT /assignment_contract/signature_batch MÉTODO POST ```json title='Request Body' { "assignment_contract_keys": ["assignment_contract_key", "assignment_contract_key"], } ``` #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `assignment_contract_keys` * | array | Lista de contratos para serem enviados no mesmo lote | -- | *Campos obrigatórios ### Response STATUS 202 ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para uma das chaves informadas. | Verificar todos os `assignment_contract_keys` enviados no array. | | ACT000088 | 400 | Status de um contrato não é válido para envio manual. | Todos os contratos do lote devem estar com `status=pending_signature_submission`. | | ACT000089 | 404 | Contratos do lote possuem partes relacionadas (gestor, cedente, avalistas) diferentes. | Apenas contratos com as mesmas partes relacionadas podem ser agrupados em um mesmo lote de assinaturas. | --- # Cancelamento de Contrato --- Em qualquer etapa, menos no caso de um contrato já assinado, é possível cancelar o mesmo. Caso esteja em assinatura, o evento de assinaturas também é cancelado ### Request ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY MÉTODO PUT ```json title='Request Body' { "status": "canceled" } ``` #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `status` * | string | canceled | -- | *Campos obrigatórios ### Response STATUS 202 ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. | | ACT000077 | 400 | Status atual do contrato não permite cancelamento. | Contratos com status `signed` ou `denied` não podem ser cancelados. | --- # Contrato de Cessão URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato --- Esse processo gera um contrato de cessão entre o Fundo de Investimento e o Cedente e o envia para a assinatura. Para gerar um contrato, é necessário possuir em mãos o fund_class_key do fundo, providenciado pelo time da QI CTVM, assim como um assignment_contract_template_key, também providenciado pelo time, que define os parâmetros do contrato, como coobrigação, documentos obrigatórios de cessão, cláusulas, etc. Na estrutura do contrato, existem os produtos, que identificam, por exemplo, uma configuração de cessão de um tipo de ativo, de recompra, e assim por diante. Serão enviados para assinatura dois documentos: o contrato propriamente dito, com todas as partes relacionadas envolvidas, como cedente, gestora, avalistas, etc.; e a declaração da gestora, a qual deve ser assinada apenas por esta, atestando que foram cumpridas todas as normas e exigências previstas pela CVM, Anbima e Banco Central quanto à operação do cedente, abrangendo desde a análise de risco até o PLD, entre outras que podem ser consultadas nos respectivos portais. O fluxo do contrato é variável: é possível configurar o envio dos documentos para assinatura assim que gerados, ou para aguardar um envio manual dos mesmos. Além disso, caso o mesmo seja proposto por um consultor, será necessária a aprovação do gestor, antes que o mesmo seja enviado para assinatura. Por último, caso o cadastro de cedente ainda não tenha sido liberado, ou o mesmo esteja em processo de atualização, será necessário aguardar a conclusão da última análise antes de enviar para assinatura. Caso a análise seja recusada, o contrato também é cancelado. Após a assinatura de ambos os documentos pelas partes requeridas, os produtos ficam pendentes de ativação, podendo levar alguns minutos para configurar a esteira de cessão, e finalmente, será possível usar a chave da configuração `assignment_configuration_key` de cessão do respectivo produto para realizar a cessão entre o fundo e o cedente. Opcionalmente, é possível definir avalistas da operação entre o cedente e o fundo, desde que o template de contrato permita tal. Os avalistas devem ser previamente cadastrados junto com o cedente, e apenas indicados no contrato pelo número do documento. Vale ressaltar que as contas de desembolso são definidas no cadastro do cedente. Todo o fluxo de assinatura do contrato é realizado pela nossa certificadora, CertifiQI, para maior comodidade e facilidade. O acompanhamento das assinaturas e posterior ativação do cedente se dá de forma automática graças a esse recurso. ### Request ENDPOINT /assignment_contract/assignment_contract MÉTODO POST ```json title='Request Body' { "fund_class_key": "813ce253-bae5-4448-8d15-04c48d9991b7", "assignor_document_number": "18.458.041/0001-91", "assignment_contract_template_key": "2555f90a-4c6a-4d65-8bda-5d16f827840c", "credit_limit": 1000000, "external_id": "Contrato 550", "observation": "Contrato referente ao vínculo com coobrigação do cedente", "guarantors": [ { "name": "Avalista da operação", "document_number": "81.914.413/0001-83" } ] } ``` #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `fund_class_key` * | string | Chave única de identificação do Fundo. Gerada na criação do Fundo e fornecida pelo time da QI CTVM. | Chave uuid | | `assignment_contract_template_key` * | string | Chave única de identificação do Template de Contrato. Também fornecida pelo time da QI CTVM. | Chave uuid | | `assignor_document_number` * | string | Número do documento do cedente. | CPF ou CNPJ | | `credit_limit` | number | Valor do limite de crédito do contrato. | - | | `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato. | 1 a 255 | | `observation` | string | Observação. Campo livre para quaisquer anotações. | 1 a 500 | | `guarantors` | array | Avalistas da operação. | Ver **[Definição de Avalista](#definição-de-avalista)**. | *Campos obrigatórios :::warning Aviso É muito importante que os avalistas sejam indicados tanto no cadastro do cedente, quanto nessa etapa. Caso seja indicado somente no cadastro, e não no contrato, o avalista não irá assinar o documento. Caso seja indicado apenas no contrato, e não no cadastro, um erro será retornado. ::: --- ### Response STATUS 201 ```json title='Response Body' { "assignment_contract_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "pending_document", "products": [ { "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "assignment_configuration_key": "372f0449-4043-4523-9f0f-dff70c65b9c9", "product_type": "assignment_term", "asset_type": "ccb", "status": "pending_contract", "required_documents": [ "ccb" ] } ] } ``` :::info É de extrema importância salvar a `assignment_contract_key`, pois a mesma é utilizada para caracterizar as configurações de cessão geradas pelo contrato futuramente, principalmente as originadas pelo fluxo de filiais do tópico 5.2.2.6.. É possível recuperar as configurações geradas seguindo o GET do tópico 5.3.1.2. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000001 | 404 | Classe de Fundo não encontrada para o `fund_class_key` informado. | Verificar se o `fund_class_key` está correto e pertence ao gestor autenticado. | | ACT000016 | 404 | Template de contrato não encontrado para o `assignment_contract_template_key` informado. | Verificar se o `assignment_contract_template_key` está correto e vinculado ao `fund_class_key`. | | ACT000123 | 400 | Template está inativo e não pode ser usado para criar contratos. | Utilizar um template ativo. | | ACT000065 | 404 | Cedente não cadastrado para o agente proponente. | Verificar se o `assignor_document_number` corresponde a um cedente cadastrado. | | ACT000096 | 400 | Cedente não possui conta cadastrada. | Cadastrar pelo menos uma conta de desembolso para o cedente antes de propor um contrato (ver [Manutenção de Contas](/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas)). | | ACT000081 | 400 | Avalista não está cadastrado junto ao cedente. | Cada item em `guarantors` deve corresponder a um avalista previamente cadastrado para o cedente, com status `registered` ou `pending_registry`. | | ACT000095 | 409 | Número de caso (`case_number`) duplicado para este fundo. | Utilizar um `case_number` único dentro do mesmo `fund_class_key`, ou omitir o campo para gerar um automaticamente. | ### Definição de Contrato de Cessão | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignment_contract_key` * | string | Chave única de identificação do contrato. | 36 | | `fund_class` * | object | Objeto fundo | -- | | `assignor` * | object | Objeto cedente. | -- | | `consultant` | object | Objeto consultor. Somente quando o consultor for parte do contrato. | -- | | `assignment_contract_template` * | object | Objeto template de contrato. | -- | | `attached_documents` * | array | Lista de documentos anexos. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. | | `products` * | array | Lista de produtos sob o contrato. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. | | `proposal_agent` * | string | Tipo do agente proponente do contrato. | -- | | `status` * | string | Status do contrato. | Ver **[Enumeradores de status do contrato de cessão](#assignment-contract-status)**. | | `credit_limit` | number | Limite de crédito enviado. | -- | | `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato | 1 a 255 | | `case_number` | string | Número de caso. Único por fundo | -- | | `denial_reason` | string | Detalhes da recusa do gestor. | 1 a 255 | | `observation` | string | Observações enviadas. | 1 a 500 | | `creation_datetime` | string | Datetime da criação do contrato. | -- | ### Definição de Documento Anexo | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Chave única de identificação do documento. | 36 | | `document_type` * | string | Tipo do documento. | -- | | `status` * | string | Status do documento. | Ver **[Enumeradores de status do documento](#attached-document-status)**. | | `document_template_key` | string | Chave única de identificação do template que gerou o documento | 36 | | `required_parties` | array | Lista de partes que assinam o documento em questão | -- | ### Definição de Produto | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `product_key` * | string | Chave única de identificação do produto. | 36 | | `assignment_configuration_key` * | string | Chave única de identificação da Configuração de Cessão. | 36 | | `asset_type` * | string | Tipo do ativo. | -- | | `status` * | string | Status do produto. | -- | ### Definição de Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do avalista. | 1 a 255 | | `document_number` * | string | CPF ou CNPJ. | 14 a 18 | *Campos obrigatórios :::warning Aviso Como já indicado, o avalista deve ser previamente cadastrado, junto com o cedente em específico. ::: # Enumeradores ### Assignment Contract Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_document** | Pendente geração dos documentos | | **sending_to_signature** | Em envio para assinatura | | **pending_signature** | Disponível para assinatura das partes | | **signed** | Assinado | | **pending_manager_approval** | Pendente aprovação do gestor | | **denied** | Reprovado na análise do gestor | | **pending_signature_submission** | Pendente envio manual para assinatura | | **pending_assignor_registry_release** | Pendente liberação do cadastro de cedente vinculado (Em fase de cadastro ou atualização) | | **canceled** | Cancelado | ### Attached Document Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_generate** | Pendente geração do documento | | **approved** | Documento gerado | | **signed** | Documento assinado | --- # Recuperação do Contrato URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato --- ## Recuperação do Contrato ### Request ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { "assignment_contract_key": "UUID", "fund_class": { "fund_class_key": "UUID", "name": "SAMPLE FUND NAME", "document_number": "00.000.000/0000-00", "manager": { "manager_key": "UUID", "document_number": "00.000.000/0000-00", "manager_name": "SAMPLE MANAGER NAME" } }, "assignor": { "assignor_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE ASSIGNOR NAME" }, "assignment_contract_template": { "assignment_contract_template_key": "UUID", "document_template_key": "UUID", "name": "NOME DO TEMPLATE", "borrower_agreement": null }, "attached_documents": [ { "document_key": "UUID", "document_type": "assignment_contract", "status": "pending_generate", "document_template_key": "UUID", "required_parties": ["manager", "assignor", "consultant"] } ], "proposal_agent": "consultant", "status": "pending_document", "credit_limit": 0.00, "external_id": "ID EXTERNO", "case_number": "NÚMERO DO PROCESSO", "denial_reason": "MOTIVO DA NEGATIVA", "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ", "products": [ { "product_key": "UUID", "assignment_configuration_key": "UUID", "asset_type": "ccb | duplicata_mercantil | duplicata_servico", "status": "pending_signature | active | canceled", "has_coobligation": true, } ], "signature_batch_key": "UUID" } ``` ### Definição de Contrato de Cessão | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignment_contract_key` * | string | Chave única de identificação do contrato. | 36 | | `fund_class` * | object | Objeto fundo | -- | | `assignor` * | object | Objeto cedente. | -- | | `consultant` | object | Objeto consultor. Somente quando o consultor for parte do contrato. | -- | | `assignment_contract_template` * | object | Objeto template de contrato. | -- | | `attached_documents` * | array | Lista de documentos anexos. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. | | `products` * | array | Lista de produtos sob o contrato. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. | | `proposal_agent` * | string | Tipo do agente proponente do contrato. | -- | | `status` * | string | Status do contrato. | Ver **[Enumeradores de status do contrato de cessão](#assignment-contract-status)**. | | `credit_limit` | number | Limite de crédito enviado. | -- | | `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato | 1 a 255 | | `case_number` | string | Número de caso. Único por fundo | -- | | `denial_reason` | string | Detalhes da recusa do gestor. | 1 a 255 | | `observation` | string | Observações enviadas. | 1 a 500 | | `signature_batch_key` | string | Identificador do lote de assinaturas. | 36 | | `creation_datetime` | string | Datetime da criação do contrato. | -- | ### Definição de Documento Anexo | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Chave única de identificação do documento. | 36 | | `document_type` * | string | Tipo do documento. | -- | | `status` * | string | Status do documento. | Ver **[Enumeradores de status do documento](#attached-document-status)**. | | `document_template_key` | string | Chave única de identificação do template que gerou o documento | 36 | | `required_parties` | array | Lista de partes que assinam o documento em questão | -- | ### Definição de Produto | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `product_key` * | string | Chave única de identificação do produto. | 36 | | `assignment_configuration_key` * | string | Chave de identificação da configuração de cessão. Necssária na esteira de compra de ativos. | 36 | | `asset_type` * | string | Tipo do ativo. | -- | | `status` * | string | Status do produto. | -- | ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. | --- # Listagem de Contratos de Cessão --- ### Request ENDPOINT /assignment_contract/assignment_contracts MÉTODO GET ### Query Params | Parâmetro | Descrição | |-----------------------------|---------------------------------------------------------------------------| | `assignor_document_number` | Documento do cedente | | `fund_class_document_number`| Documento do fundo | | `fund_class_key` | Identificador único do fundo (UUID) | | `status` | Status da cessão | | `case_number` | Número do caso | | `start_date` | Data de início | | `end_date` | Data de fim | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "assignment_contract_key": "UUID", "fund_class": { "fund_class_key": "UUID", "name": "SAMPLE FUND NAME", "document_number": "00.000.000/0000-00", "manager": { "manager_key": "UUID", "document_number": "00.000.000/0000-00", "manager_name": "SAMPLE MANAGER NAME" } }, "assignor": { "assignor_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE ASSIGNOR NAME" }, "assignment_contract_template": { "assignment_contract_template_key": "UUID", "document_template_key": "UUID", "name": "NOME DO TEMPLATE", "borrower_agreement": null }, "attached_documents": [ { "document_key": "UUID", "document_type": "assignment_contract", "status": "pending_generate", "document_template_key": "UUID", "required_parties": ["manager", "assignor", "consultant"] } ], "proposal_agent": "consultant", "status": "pending_document", "credit_limit": 0.00, "external_id": "ID EXTERNO", "case_number": "NÚMERO DO PROCESSO", "denial_reason": "MOTIVO DA NEGATIVA", "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ", "products": [ { "product_key": "UUID", "assignment_configuration_key": "UUID", "asset_type": "ccb | duplicata_mercantil | duplicata_servico", "status": "pending_signature | active | canceled", "has_coobligation": true, } ], "signature_batch_key": "UUID" } ], "limit": 10, "page": 0, "is_last_page": true } ``` # Enumeradores ### Assignment Contract Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_document** | Pendente geração dos documentos | | **sending_to_signature** | Em envio para assinatura | | **pending_signature** | Disponível para assinatura das partes | | **signed** | Assinado | | **pending_manager_approval** | Pendente aprovação do gestor | | **denied** | Reprovado na análise do gestor | | **pending_signature_submission** | Pendente envio manual para assinatura | | **pending_assignor_registry_release** | Pendente liberação do cadastro de cedente vinculado (Em proceso de cadastro ou atualização) | | **canceled** | Cancelado | ### Attached Document Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_generate** | Pendente geração do documento | | **approved** | Documento gerado | | **signed** | Documento assinado | --- # Webhooks do Contrato URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato --- #### Pendente Aprovação do Gestor STATUS pending manager approval ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "pending_manager_approval" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Pendente Envio para Assinatura STATUS pending signature submission ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "pending_signature_submission" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Pendente Liberação do Cadastro do Cedente STATUS pending assignor registry release ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "pending_assignor_registry_release" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Recusado pelo Gestor STATUS denied ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "denied" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Contrato Enviado para Assinatura STATUS pending signature ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "pending_signature" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Assinado STATUS signed ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "signed" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Contrato Cancelado STATUS canceled ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "canceled" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` # Webhooks do Produto --- #### Produto Ativado STATUS active ```json title='Webhook Body' { "data":{ "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "assignment_configuration_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "active" }, "webhook_type":"assignment_contract.product_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Produto Em Ativação STATUS pending_create_assignment_configuration ```json title='Webhook Body' { "data":{ "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "assignment_configuration_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "pending_create_assignment_configuration" }, "webhook_type":"assignment_contract.product_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` --- # Webhooks do Produto URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_produto --- #### Produto Ativado STATUS Active ```json title='Webhook Body' { "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "assignment_configuration_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "active" } ``` --- # Introdução URL: /documentation/iaas/homologacao_cedente/inicio A parte de cadastro de Cedente é essencial para o início da operação de qualquer fundo que compre direitos creditórios. Nessa seção iremos explicar todo o fluxo, desde o envio das primeiras informações, até a abertura da Esteira de Cessão para envio de Ativos. Para ter acesso aos serviços discutidos nas próximas sessões, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox) quanto em ambiente de produção. É importante mencionar que para a efetiva liberação de um Cedente, deve-se consumir dois diferentes sistemas: 1. O cadastro do Cedente em nossa base, realizado uma única vez; 2. Formalização de um Contrato de Cessão, entre o Cedente e o Fundo; Para ambos os sistemas, tanto o gestor quanto o consultor podem atuar como agentes, propondo cadastros e contratos entre os cedentes e os fundos de acordo com o desenvolver da operação. ### Cadastro do Cedente Nessa etapa, deve-se enviar todas as informações tanto do Cedente quanto dos seus representantes e beneficiários finais. Uma vez feito o envio, o Cedente nasce Pendente Registro, é gerada uma primeira análise e deve-se enviar a documentação necessária, validando o cadastro. Por fim, após anexar todos os documentos necessários deve-se comandar o disparo da Análise, ou seja, o envio da Análise para validação, a qual passará por um processo de anti-fraude e PLD. Alguns documentos são necessários para a análise realizada, no caso de uma pessoa jurídica, o contrato social, com a última atualização disponível, certidão simplificada da Junta Comercial, e a ata de eleição da diretoria vigente. Além disso, devem ser enviados os documentos dos beneficiários finais da empresa, para fins de combate à lavagem de dinheiro, corrupção e financiamento ao terrorismo. Para cedentes pessoa física, apenas o documento de identificação é suficiente para a análise. Em ambos os casos, é necessário um termo de responsabilidade do agente de cadastro, afirmando que realizou todo o levante de documentos, como comprovantes de faturamento, compliance, entre outros, propostos pela norma da CVM e da AMBIMA. Assim que esta primeira Análise for aprovada, o cadastro passará por uma etapa de validação interna, onde uma equipe validará as informações recebidas e dará seguimento ao mesmo, após a validação dos assinantes. Assim que efetivado, o cedente estará disponível para as próximas operações. Nesse momento, caso configurado, enviamos um Webhook notificando que a Análise foi aprovada, mas também é possível acompanhar os cedentes cadastrados pelo portal do gestor. :::warning Análises paradas por 1 mês são canceladas automaticamente Uma Análise que fica **1 mês sem movimentação** é cancelada automaticamente, passando para o status `canceled`. Na prática isso atinge as análises que permanecem em `pending_documents` — aquelas em que a documentação nunca foi anexada, ou em que o [Disparo da Análise](/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise) nunca foi comandado. O cancelamento é **terminal**: a análise cancelada não volta atrás e não aceita novos documentos nem disparo. Para retomar o cadastro, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). A mudança dispara o webhook `assignor_registry.analysis_status_change` com `analysis_status: canceled` — veja [Webhooks de Análise](/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise). ::: ### Atualização de Cedente Em caso de necessidade de atualização cadastral, deve-se enviar novamente todas as informações do Cedente com as modificações desejadas. Após envio, é gerada uma nova Análise em que é necessário anexar a documentação necessária para garantirmos a validade da atualização. Por fim, após anexar todos os documentos necessários deve-se comandar o disparo da Análise, ou seja, o envio da nova Análise para validação. Vale ressaltar que os documentos que devem ser enviados, são apenas os das entidades que foram alteradas, seja a adição de um novo representante, ou alteração de algum dado cadastral da companhia. Assim que esta nova Análise for aprovada, os novos dados cadastrais do Cedente são efetivamente alterados. Nesse momento, caso configurado, enviamos um Webhook notificando que a Análise foi aprovada. Note que, uma atualização cadastral de um Cedente não gera impedimento em realizar novas operações com ele. ### Formalização de Contrato de Cessão Para formalizar a relação entre o Cedente e o Fundo, é necessário a assinatura de um Contrato de Cessão, que rege essa venda de ativos. Nós disponibilizamos uma API que viabiliza esse processo de maneira automática. O processo envolve o pedido de formalização, a partir de um template, que irá disparar internamente a criação do contrato e envio para assinatura. Uma vez com o contrato assinado, os produtos definidos pelo template ficam disponíveis para ativação. Assim o cliente escolhe qual produto quer ativar, e indica a conta de desembolso. Será retornada, através da ativação do Produto, a chave da Configuração de Cessão gerada, identificador que será utilizado posteriormente no processo de compra e venda de ativos. --- # Integração via SFTP URL: /documentation/iaas/integracao_sftp/inicio O SFTP (Secure File Transfer Protocol) é o canal pelo qual a QI CTVM disponibiliza os relatórios dos fundos para download . Os modelos disponíveis, o layout coluna a coluna de cada arquivo e os exemplos para download estão na [documentação de Relatórios DTVM](/documentation/iaas/relatorios_dtvm/). Para a integração, recomendamos bibliotecas e clientes que implementem o protocolo, como o `paramiko` em Python, o `sftp` da linha de comando ou qualquer cliente SFTP padrão. :::info Liberação de acesso Para solicitar o acesso, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). A liberação é feita primeiro no ambiente de Homologação (Sandbox) e depois em Produção. ::: ## Como funciona a autenticação O acesso é autenticado por **chave pública SSH** — não há senha. Você gera o par de chaves, mantém a chave privada sob o seu controle e nos envia apenas a chave pública, que cadastramos no seu usuário do SFTP. | Quem | O que fornece | | --------------- | -------------------------------------------------------------------------------- | | **Você** | A chave pública (arquivo `.pub`), no formato OpenSSH | | **A QI CTVM** | `HOSTNAME`, `PORT` (22) e `USERNAME`, além do fingerprint do host | :::danger Nunca envie a sua chave privada Nenhum time da QI Tech vai pedir a sua chave privada. Se alguém pedir — por e-mail, por chamado ou por qualquer outro canal —, não somos nós. O compartilhamento no 1Password descrito no passo 3 é apenas para a chave **pública** (`sftp_qitech.pub`). Se a chave privada já foi enviada a alguém ou anexada em algum lugar, considere-a comprometida: gere um par novo e nos envie a nova chave pública. ::: ## 1. Gerando o par de chaves Gere um par **dedicado ao SFTP**. Não reutilize a chave que assina os seus tokens JWT: são credenciais de sistemas diferentes, com ciclos de vida diferentes — rotacionar uma passaria a obrigar a rotação da outra, e um vazamento em um dos lados atingiria os dois. Troque `nome-da-empresa` pelo nome da sua empresa — por exemplo, `sftp-acme`. Esse texto é apenas um comentário dentro da chave, e serve para nos ajudar a identificá-la. **Linux / macOS** ```bash mkdir -p ~/.ssh && chmod 700 ~/.ssh ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f ~/.ssh/sftp_qitech ``` **Windows (PowerShell)** ```powershell New-Item -ItemType Directory -Force "$env:USERPROFILE\.ssh" | Out-Null ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f "$env:USERPROFILE\.ssh\sftp_qitech" ``` **Windows (cmd)** ```batch if not exist "%USERPROFILE%\.ssh" mkdir "%USERPROFILE%\.ssh" ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f "%USERPROFILE%\.ssh\sftp_qitech" ``` **Windows (WSL)** ```bash mkdir -p ~/.ssh && chmod 700 ~/.ssh ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f ~/.ssh/sftp_qitech ``` Dentro do WSL, use o caminho do Linux (`~/.ssh`). A chave fica no sistema de arquivos do WSL, e não na pasta do usuário do Windows. :::caution Copie o comando da aba correspondente Cada aba escreve o caminho da pasta na forma que aquele programa entende, então os comandos não são intercambiáveis. Se você rodar o comando de uma aba em outro programa, aparece `No such file or directory` e nenhuma chave é criada — nesse caso, é só voltar e copiar o comando da aba certa. No Windows, se você não sabe qual usar, use o **PowerShell**: é o que abre por padrão no Terminal do Windows. ::: O comando pergunta por uma passphrase e gera dois arquivos: | Arquivo | O que é | | ------------------ | ----------------------------------------------------------- | | `sftp_qitech` | **Chave privada.** Nunca envie e nunca compartilhe. | | `sftp_qitech.pub` | **Chave pública.** É esta que você deve nos enviar. | Sobre a passphrase : - **Integração automatizada** (um serviço seu baixando os relatórios): deixe em branco, apertando Enter nas duas perguntas, e proteja a chave privada onde ela for armazenada, em um gerenciador de segredos com acesso restrito. Uma passphrase que precisa ficar disponível para o processo em tempo de execução não acrescenta proteção real. - **Uso por uma pessoa**: defina uma passphrase . O `ssh-keygen` já cria a chave privada com permissão restrita ao seu usuário. Se você copiar o arquivo para outra máquina, restaure a permissão — clientes SSH recusam chaves privadas legíveis por outros usuários: ```bash chmod 600 ~/.ssh/sftp_qitech ``` ## 2. Conferindo o formato da chave pública O conteúdo do arquivo `.pub` é **uma única linha**, começando pelo tipo da chave e terminando no comentário: ``` ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE1wA3uBEFYG+Yi7zIw7/YUJJ4fBB0MUZsvUVaqyyv6M sftp-acme ``` Confira o arquivo antes de nos enviar: ```bash ssh-keygen -lf ~/.ssh/sftp_qitech.pub ``` A resposta esperada é o fingerprint da chave, no formato `256 SHA256:... sftp-acme (ED25519)`. Se o comando responder `is not a public key file`, o arquivo está corrompido ou não é uma chave pública OpenSSH. ### Se a sua chave está no formato PEM/X.509 Uma chave que começa com `-----BEGIN PUBLIC KEY-----` está no formato PEM/X.509, o padrão do OpenSSL. Esse formato **não pode ser cadastrado no SFTP**: o servidor espera o formato OpenSSH, de uma única linha. Se essa chave já é dedicada ao SFTP, você não precisa gerar outra — basta convertê-la: - **Você ainda tem a chave privada correspondente.** Vale para qualquer tipo de chave: ```bash ssh-keygen -y -f caminho/para/chave_privada ``` - **Você só tem a chave pública em PEM.** Vale para chaves RSA: ```bash ssh-keygen -i -m PKCS8 -f caminho/para/chave_publica.pem ``` Os dois comandos imprimem a chave no formato OpenSSH na saída padrão. A conversão não preserva o comentário original; se quiser, acrescente `sftp-nome-da-empresa` ao final da linha. ## 3. Enviando a chave pública Envie a chave pública pelo **1Password**, compartilhando o item com o time de integração. É por esse canal que recebemos as chaves: ele preserva o conteúdo exatamente como você o gerou e deixa a origem do envio verificável — quem conseguisse substituir a sua chave pública no caminho passaria a ter acesso ao seu diretório no SFTP. 1. No 1Password, crie um item e cole nele o conteúdo do arquivo `sftp_qitech.pub` **como texto puro, em uma única linha, sem quebras**. 2. Acrescente o fingerprint da chave — a saída do `ssh-keygen -lf` do passo anterior. Comparamos com o fingerprint da chave que recebemos e confirmamos que ela não foi alterada no caminho. 3. Compartilhe o item com o time de integração e avise em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) que o compartilhamento foi feito. :::caution Não anexe a chave em `.docx` nem em `.pdf` A formatação automática desses programas substitui caracteres (um `+` por um travessão, aspas retas por tipográficas) e insere quebras de linha. Qualquer uma dessas alterações invalida a chave, e o erro só aparece na hora da conexão. ::: Com a chave pública cadastrada, confirmamos a liberação e enviamos o `HOSTNAME`, o `USERNAME` e o fingerprint do host. ## 4. Conectando ao SFTP ### Confira o host key na primeira conexão Na primeira conexão, o seu cliente vai perguntar se você confia no servidor. Não aceite sem conferir: compare o fingerprint apresentado com o que o time de integração enviou. É essa comparação que impede que outro servidor se passe pelo nosso. ```bash ssh-keyscan -t ed25519 > qitech_host_key ssh-keygen -lf qitech_host_key # compare com o fingerprint enviado pela QI CTVM cat qitech_host_key >> ~/.ssh/known_hosts ``` Depois de conferido, o `known_hosts` passa a ser a referência do cliente e conexões com outro host key são recusadas automaticamente. ### Credenciais da conexão | Credencial | Origem | | ------------------- | --------------------------------------------- | | `HOSTNAME` | Endereço do servidor, informado pela QI CTVM | | `PORT` | 22 | | `USERNAME` | Usuário, informado pela QI CTVM | | **Chave privada** | O arquivo `sftp_qitech` que você gerou | :::caution Atenção Essas credenciais dão acesso direto aos relatórios do seu fundo e não devem ser compartilhadas. ::: ### Exemplo de código **Python** ```python import paramiko HOSTNAME = "sftp.exemplo.com" # informado pela QI CTVM PORT = 22 USERNAME = "usuario" # informado pela QI CTVM PRIVATE_KEY = "/caminho/para/sftp_qitech" # a chave privada que você gerou KNOWN_HOSTS = "/caminho/para/known_hosts" # com o host key da QI CTVM já conferido client = paramiko.SSHClient() client.load_host_keys(KNOWN_HOSTS) # Recusa a conexão se o host key não for o esperado. # Não use AutoAddPolicy: ela aceita qualquer servidor sem verificação. client.set_missing_host_key_policy(paramiko.RejectPolicy()) client.connect( hostname=HOSTNAME, port=PORT, username=USERNAME, key_filename=PRIVATE_KEY, # o paramiko identifica o tipo da chave pelo arquivo look_for_keys=False, allow_agent=False, timeout=30, ) try: with client.open_sftp() as sftp: # Lista os arquivos disponíveis for name in sftp.listdir("/"): print(name) # Faz o download de um arquivo sftp.get("caminho/remoto/arquivo.csv", "caminho/local/arquivo.csv") finally: client.close() ``` ## 5. Baixando os arquivos Os arquivos são nomeados a partir do nome resumido do fundo , do modelo do relatório e da data de referência no formato YYYY-MM-DD: - `example_name_assets_wallet_composition_2026-07-29.csv` Os modelos disponíveis, o layout coluna a coluna de cada arquivo e os exemplos para download estão na [documentação de Relatórios DTVM](/documentation/iaas/relatorios_dtvm/). :::info Informação O SFTP de relatórios descrito nesta página é exclusivamente para download de arquivos; não é permitido realizar upload . ::: ## Rotação e revogação da chave Para trocar a chave, gere um par novo e nos envie a nova chave pública pelo 1Password, seguindo os passos 1 a 3. Cadastramos a nova chave e informamos quando a anterior for removida — assim a troca acontece sem janela de indisponibilidade. Se houver suspeita de comprometimento da chave privada, avise o time de integração no mesmo contato: revogamos o acesso da chave antiga imediatamente, antes de cadastrar a nova. --- # Recebimento de Webhooks URL: /documentation/iaas/introducao/autenticacao_webhooks A assinatura dos Webhooks utiliza-se de uma estratégia de criptografia com chaves simétricas, ou seja, tanto a QI CTVM quanto o Parceiro integrador compartilham de uma mesma chave. Ao realizarmos uma configuração de Webhooks, iremos gerar uma Signature Key e disponibiliza-lá. Toda requisição originada no sistema da QI, irá carregar um header SIGNATURE que será um JWT assinado com essa chave. O encoding é realizado com o algoritmo HS256. Abaixo temos um exemplo em python de como realizar o decoding da assinatura: ```python from jose import jwt signature_key = "CHAVE UNICA DISPONIBILIZADA PELO TIME QI" signature_token = headers["SIGNATURE"] decoded_token = jwt.decode(signature_token, key=signature_key, algorithms=["HS256"]) print(decoded_token) ``` ## O que a assinatura carrega O JWT decodificado traz quatro campos: | Campo | Descrição | |-------|-----------| | `timestamp` | Data e hora da assinatura, em UTC, no formato `AAAA-MM-DDTHH:MM:SS`. | | `method` | Método HTTP da requisição — sempre `POST`. | | `uri` | A URL de destino configurada para o seu webhook. | | `payload_md5` | Hash MD5 do corpo da requisição. | :::tip Use o `payload_md5` para validar integridade Calcular o MD5 do corpo recebido e comparar com `payload_md5` confirma que o payload não foi alterado em trânsito. Como o hash é calculado sobre o corpo serializado, compare os bytes recebidos — não o resultado de um *re-encode* do JSON depois de parsear. ::: Além do `SIGNATURE`, as requisições levam o header **`AGENT-KEY`**, com o identificador do agente (classe de fundo, investidor ou gestor) a que a notificação se refere. Ele é útil para rotear a notificação quando a sua integração atende mais de um fundo pela mesma URL. ## Tentativas de entrega Consideramos a entrega bem-sucedida quando a sua aplicação responde com um status de sucesso. Em caso de falha — resposta de erro ou erro de rede — a notificação volta para a fila e é retentada. São feitas **até 5 tentativas** por notificação. Esgotadas as tentativas, ela é marcada como falha e não é mais retentada automaticamente. :::info Notificação que não chegou Uma notificação que falhou nas 5 tentativas pode ser reenviada pela QI CTVM — entre em contato com o time de integração informando o período e o tipo de evento. O reenvio não é uma operação disponível na sua integração. ::: :::warning Trate o recebimento como idempotente Uma tentativa pode ter chegado à sua aplicação e a resposta ter se perdido, o que faz a notificação ser retentada. Sua aplicação precisa tolerar receber a mesma notificação mais de uma vez — use as chaves do payload para reconhecer o que já foi processado. ::: ## Validação de origem Sugerimos que, além de comparar a assinatura, o parceiro integrador valide o nosso IP, dado que todas as nossas requisições são originadas de um mesmo IP, conforme o ambiente: |Ambiente|IP | |--------|--------------| |Produção|54.205.166.229| |Sandbox |52.72.221.4 | :::danger Atenção! Os webhooks da QI CTVM não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs. ::: --- # Introdução URL: /documentation/iaas/introducao/inicio A QI CTVM é uma instituição financeira que presta os serviços de Administração e Custódia de Fundos de Investimento. Nós temos uma série de serviços, utilizando REST APIs que viabilizam uma nova experiência em toda a operação, visando facilidades, automações e uma total transparência para os envolvidos. Essa documentação tem como objetivo descrever os fluxos, endpoints e estruturas de dados necessárias para operar quaisquer Fundos de Investimentos. Obs.: Em caso de dúvidas em qualquer etapa do processo favor entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) detalhando seu problema/dúvida que te auxiliaremos. ## Perfis de Acesso No nosso sistema nós reconhecemos o usuário pelo perfil que ele assume dentro da estrutura da QI CTVM. Possuímos 5 principais perfis: 1. Gestores; 2. Originadores; 3. Cedentes; 4. Investidores; 5. Distribuidores; Cada um desses perfis possui um Endpoint específico para a sua integração, com as devidas rotas disponibilizadas; Para criarmos um Perfil de Acesso para utilização das nossas APIs é necessário que se entre em contato com nosso time através do e-mail [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). Gestoras e consultorias solicitam apenas o **nome, e-mail e CPF** do usuário master responsável e, a partir daí, criam a integração e cadastram a chave pública pelo próprio portal — sem enviar chaves por e-mail. Veja [Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal). ## Ambientes (Hosts) A QI CTVM possui dois ambientes, SANDBOX e PRODUÇÃO. Ambos os ambientes possuem código e comportamento completamente idênticos, porém, o ambiente de SANDBOX apresenta valores monetários totalmente fictícios, e o ambiente de Produção realiza transações financeiras válidas. O ambiente Sandbox foi criado para os desenvolvedores realizarem suas integrações, e quando estiverem prontos para entrada em produção, atualizarem apenas as variáveis de ambiente com os parâmetros de Produção. | Perfil | Ambiente | Host | |----------------|----------|------------------------------------------------| | Gestores | Sandbox | https://manager-api.sandbox.qidtvm.com.br/ | | Originadores | Sandbox | https://originator-api.sandbox.qidtvm.com.br/ | | Cedentes | Sandbox | https://assignor-api.sandbox.qidtvm.com.br/ | | Investidores | Sandbox | https://investor-api.sandbox.qidtvm.com.br/ | | Distribuidores | sandbox | https://distributor-api.sandbox.qidtvm.com.br/ | | Consultores | sandbox | https://consultant-api.sandbox.qidtvm.com.br/ | | Gestores | Produção | https://manager-api.qidtvm.com.br/ | | Cedentes | Produção | https://assignor-api.qidtvm.com.br/ | | Originadores | Produção | https://originator-api.qidtvm.com.br/ | | Investidores | Produção | https://investor-api.qidtvm.com.br/ | | Distribuidores | Produção | https://distributor-api.qidtvm.com.br/ | | Consultores | Produção | https://consultant-api.qidtvm.com.br/ | | Público | Produção | https://api.qidtvm.com.br/ | :::danger Aviso Importante! Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech. ::: --- # Integração pelo portal URL: /documentation/iaas/introducao/integracao_via_portal Gestoras e consultorias criam a própria integração de API pelo portal: criam a integração, cadastram a chave pública e recebem ali mesmo a API Key. Nenhuma chave trafega por e-mail. :::tip Este é o caminho padrão Cadastrar a chave pública pela tela é o procedimento recomendado para gestoras e consultorias, em sandbox e em produção. O envio da chave pública por e-mail é tratado como exceção — veja [Quando o envio por e-mail ainda é usado](#quando-o-envio-por-e-mail-ainda-e-usado). Pelo portal a chave é cadastrada pelo próprio responsável, com confirmação explícita e fingerprint visível na tela. Isso elimina o repasse manual de arquivos entre caixas de e-mail, reduz o risco de a chave errada ser cadastrada e permite a troca da chave a qualquer momento, sem abrir chamado. ::: ## Visão geral do fluxo | Etapa | Quem faz | Onde | | ----- | -------- | ---- | | 1. Cadastro do usuário master | Time de integração da QI Tech | A partir do contato por e-mail ou WhatsApp | | 2. Acesso ao portal | Usuário master | Portal do Gestor ou Portal do Consultor | | 3. Criação dos demais usuários e permissões | Usuário master | Portal, em **Gestão de Acesso > Usuários** | | 4. Criação da integração | Usuário master ou usuário com permissão | Portal, em **Gestão de Acesso > Integração API** | | 5. Cadastro da chave pública | Usuário com permissão | Portal, na tela da integração | | 6. Liberação das permissões da integração | Time de integração da QI Tech | Aparece na própria tela quando concluída | | 7. Configuração de webhooks (opcional) | Usuário com permissão | Portal, na tela da integração | ## 1. Solicitar o cadastro do usuário master Entre em contato com o time de integração da QI Tech por e-mail ([integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)) ou WhatsApp informando, do responsável pela homologação: - **Nome completo** - **E-mail corporativo** - **CPF** Com esses dados criamos o **usuário master** da gestora ou da consultoria no ambiente solicitado. Esse usuário é o ponto de partida: é ele quem cria os demais usuários, concede permissões e cria as integrações de API. :::danger Não envie chaves por e-mail A solicitação contém apenas nome, e-mail e CPF do responsável. **Não envie a chave pública nessa mensagem** — ela é cadastrada por você mesmo no portal, na etapa 5. E a chave privada nunca é enviada a ninguém, em nenhuma hipótese: a QI Tech jamais pedirá que você a compartilhe. ::: ## 2. Acessar o portal | Perfil | Ambiente | Portal | | ------ | -------- | ------ | | Gestora | Sandbox | https://portal-do-gestor.sandbox.fundos.qitech.com.br/ | | Gestora | Produção | https://portal-do-gestor.fundos.qitech.com.br/ | | Consultoria | Sandbox | https://portal-do-consultor.sandbox.fundos.qitech.com.br/ | | Consultoria | Produção | https://portal-do-consultor.fundos.qitech.com.br/ | O acesso é feito por login único (SSO) com o e-mail cadastrado na etapa anterior. ## 3. Criar os demais usuários e conceder permissões Somente o usuário master (ou quem ele autorizar) enxerga a tela de integração. Para dar acesso a outras pessoas do time: 1. Acesse **Gestão de Acesso > Usuários** e clique em **Criar usuário**. 2. Informe **Nome**, **Sobrenome**, **E-mail** e **CPF**. 3. Abra o usuário criado e conceda a permissão de integração: - Gestora: **Gerenciar Integração API** (`manager.manage_integration`) - Consultoria: **Gerenciar integração com a API** (`consultant.manage_integration`) Sem essa permissão o item **Integração API** não aparece no menu. ## 4. Criar a integração Em **Gestão de Acesso > Integração API**, clique em **Criar integração** e informe um nome que identifique o uso (por exemplo, `ETL noturno` ou `Backoffice`). Ao confirmar, a QI Tech gera as credenciais da integração e a tela de detalhe é aberta: | Credencial | Para que serve | | ---------- | -------------- | | **API Key** | Vai no header `API-CLIENT-KEY` de todas as requisições. Veja [Teste de autenticação](/documentation/iaas/introducao/teste_de_autenticacao). | | **Client Integration Key** | Identificador da integração. Use para referenciá-la em contatos com o time de integração. | Uma mesma gestora ou consultoria pode manter **várias integrações ativas ao mesmo tempo**, cada uma com sua própria chave pública — útil para separar sistemas ou ambientes internos. A integração nasce com status **Criada**. Ela só passa a **Ativa** depois que a chave pública é cadastrada. ## 5. Cadastrar a chave pública Na tela da integração, clique em **Cadastrar chave pública**. Há duas formas de fazer isso. ### Opção A — Gerar o par de chaves no navegador O portal gera o par direto no seu navegador e baixa a chave privada para a sua máquina. **A chave privada nunca é enviada à QI Tech**: só a chave pública é transmitida. 1. Escolha o **Algoritmo da chave**. 2. Clique em **Gerar par de chaves**. O download da chave privada começa automaticamente. 3. Guarde a chave privada em local seguro — ela não é exibida novamente e não pode ser recuperada. Se necessário, use **Baixar chave privada** e **Baixar chave pública** antes de sair da tela. 4. A chave pública já vem preenchida no formulário. Confirme para cadastrá-la. Cada algoritmo determina o `alg` que você deve usar ao assinar o JWT das requisições: | Algoritmo no portal | Assinatura do JWT | | ------------------- | ----------------- | | RSA 2048 (recomendado) | `RS256` | | RSA 4096 | `RS256` | | EC P-256 | `ES256` | | EC P-384 | `ES384` | | EC P-521 | `ES512` | ### Opção B — Enviar a sua própria chave pública Se você já gerou o par fora do portal — veja [Troca de chaves](/documentation/iaas/introducao/troca_de_chaves) — envie apenas a chave pública: - **Arraste o arquivo** para a área indicada, ou clique para selecioná-lo (`.pem`, `.pub`, `.key`, `.crt` ou `.txt`); ou - **Cole o conteúdo** do PEM no campo de texto. O portal identifica o algoritmo da chave e informa, abaixo do campo, com qual `alg` você deve assinar suas requisições. ### Requisitos e recusas A chave precisa estar em PEM, no bloco `-----BEGIN PUBLIC KEY-----`. O portal recusa o cadastro nos casos abaixo: | Situação | Motivo | | -------- | ------ | | Conteúdo de chave privada (`BEGIN ... PRIVATE KEY`) | A chave privada nunca deve ser enviada | | Certificado (`BEGIN CERTIFICATE`) | Não é uma chave pública | | Chave no formato OpenSSH (`ssh-rsa`, `ecdsa-sha2-...`) | Converta para PEM | | RSA com menos de 2048 bits | Abaixo do mínimo aceito | | PEM ilegível | Conteúdo corrompido ou incompleto | Para confirmar, digite `CADASTRAR` no campo de confirmação. **O cadastro é imediato**: a integração passa a usar essa chave assim que você confirma. Concluído o cadastro, a tela exibe o **Fingerprint (SHA-256)** da chave e a data do cadastro. Use o fingerprint para conferir que a chave cadastrada é mesmo a sua. ## 6. Liberação das permissões da integração :::info Apenas para gestoras Consultorias não passam por esta etapa: a autorização é feita pelas permissões de fundo da consultoria, e a integração já fica pronta para uso depois do cadastro da chave. ::: Para gestoras, o último passo é a liberação das permissões de **Leitura** e **Escrita** da integração, feita pelo time de integração da QI Tech. Não é preciso aguardar na tela — o status aparece em **Permissões** quando a liberação for concluída. ## 7. Configurar webhooks (opcional) Ainda na tela da integração, o bloco **Webhooks** permite cadastrar a URL de destino das notificações. Os sistemas disponíveis são: | Sistema | Eventos | | ------- | ------- | | Cadastro de cedentes | Análises, registro de cedentes e apontamentos | | Contratos de cessão | Status de contratos de cessão e produtos | | Recebíveis | Cessões e ativos da esteira de recebíveis | | Liquidação | Lotes de pagamento e liquidações | Você pode usar a mesma URL para todos os sistemas ou uma URL por sistema. Cada sistema gera uma **chave de assinatura (HMAC)** própria, usada para validar as entregas recebidas — veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks). :::caution Webhooks são configurados por agente A configuração de webhooks vale para a gestora ou consultoria como um todo, não por integração. Se houver mais de uma integração de API, todas compartilham a mesma configuração. ::: ## Trocar a chave pública A qualquer momento, na tela da integração, use **Trocar chave** e repita a etapa 5. Confirme digitando `TROCAR`. :::danger A troca é imediata A chave anterior é invalidada na hora. Requisições assinadas com ela passam a falhar assim que a nova chave é cadastrada. Faça a troca em uma janela em que você possa atualizar a chave privada usada pela sua aplicação. ::: ## Desativar e reativar a integração **Desativar integração** (confirmando com `DESATIVAR`) faz com que toda chamada feita com aquela credencial passe a ser recusada. Nada é apagado: chave pública, permissões e webhooks continuam salvos e voltam a valer ao reativar. Use a desativação como resposta imediata a uma suspeita de vazamento da chave privada; em seguida, gere um novo par e cadastre a nova chave pública antes de reativar. ## Entrada em produção O procedimento em produção é o mesmo. Envie por e-mail ao time de integração o **nome, e-mail e CPF do usuário master** da gestora ou da consultoria no ambiente de produção. A partir do acesso desse usuário master, a criação dos demais usuários, a concessão de permissões e a criação das integrações de API são feitas por você, pelo portal — sem novo contato com o time. As credenciais de sandbox não valem em produção: cada ambiente tem suas próprias integrações, chaves e API Keys. :::danger Aviso Importante! Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech. ::: ## Quando o envio por e-mail ainda é usado O cadastro pelo portal está disponível para **gestoras** e **consultorias**. Os demais perfis de acesso — cedentes, originadores, investidores e distribuidores — continuam enviando a chave pública ao time de integração, conforme descrito em [Troca de chaves](/documentation/iaas/introducao/troca_de_chaves). Se você é gestora ou consultoria e ainda não tem acesso ao portal, solicite o usuário master pela etapa 1 em vez de enviar a chave por e-mail. --- # Pacote de Endpoints URL: /documentation/iaas/introducao/pacote_endpoints Para facilitar a experiência de integração com o ecossistema da QI Tech , disponibilizamos um pacote completo contendo todos os endpoints possíveis, já organizado em uma estrutura de pastas. Nosso objetivo é tornar o processo de integração mais ágil, claro e padronizado — reduzindo o esforço inicial e garantindo que você tenha acesso imediato a todos os recursos necessários durante a implementação. Esse pacote centraliza: - A lista completa dos endpoints disponíveis para cada produto; - Estrutura organizada por temas, seguindo a documentação; Um ponto único de referência, evitando consultas fragmentadas ou perda de informações importantes. Ao disponibilizarmos essa pasta, buscamos garantir que parceiros integradores tenham um caminho mais simples, rápido e estruturado para iniciar suas implementações com a QI Tech, reforçando nosso compromisso com clareza, segurança e eficiência técnica. ### [📦 Baixar pacote Python completo](/downloads/integracao_python_iaas.zip) --- # Endpoints de teste URL: /documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste ## Método GET ### Request ENDPOINT /authentication_test MÉTODO GET ### Response STATUS 200 Response Body ```json { "success": "Congrats!" } ``` ## Metodo POST ### Request ENDPOINT /authentication_test MÉTODO POST Request Body ```json { "name": "QI Tech" } ``` ### Response STATUS 200 Response Body ```json { "name": "QI Tech", "success": "Congrats!" } ``` --- # Teste de autenticação URL: /documentation/iaas/introducao/teste_de_autenticacao/ ### 1. Introdução Nessa seção iremos explicar como deve funcionar a requisição para que possa ser aceita pelo nosso sistema. Em primeiro Lugar deve-se colocar no header API-CLIENT-KEY a Api Key fornecida pelo time da QI CTVM. Depois deve-se criar um Header de AUTHORIZATION assinando com a Chave Privada do parceiro integrador; Abaixo iremos ensinar o passo a passo utilizando de Python para exemplificar o processo de criação da AUTHORIZATION. ### 2. Importar bibliotecas Neste exemplo em python estamos usando 5 bibliotecas para poder realizar o processo de autenticação. ```python from datetime import datetime import json from jose import jwt from hashlib import md5 import requests ``` ### 3. Inserir a chave privada e a chave de integração ```python title="Dados da criptografia" api_key = "\" client_private_key = '''-----BEGIN EC PRIVATE KEY----- MIHbAgEBBEH7OuewosJfz4zKF+Gm0ogJxhb8G6LSMDVQQbFYz335mHCx9/Pr6Yk+ yYwsVozeXhlry3/vnUn1zCasU+4O+yseZ6AHBgUrgQQAI6GBiQOBhgAEAa46fN/2 8vI64shRhu9erMA6JLl3zHFX8gFHQrbb0g4IDfjXCKMCILiwdtL8QecstsgepTa7 yo1pTXOVNDbmLX2TAK38xb2Gv6OC+PA+5drF2wWajWbVLpR2R7mYEzr5HNIAJYHb 5C1jvM2ItK2R22HAbYfH25nsvGhkCGbrRNWQVF9g -----END EC PRIVATE KEY-----''' ``` ### 4. Definir variáveis Definir as variáveis método, endpoint e conteúdo particular a cada requisição (neste exemplo, utilizaremos o método "POST" para o endpoint "/authentication_test") ```python title="Dados da requisição" base_url = "https://assignor-api.qidtvm.com.br" today_str = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S") method = "POST" endpoint = "/authentication_test" body = {"name": "QI Tech"} ``` :::caution **Atenção** O campo `uri` da assinatura deve ser **idêntico** ao caminho enviado na requisição. Se o endpoint receber parâmetros na *query string*, eles também fazem parte da URI assinada — veja [Requisições com query string](#query-string). ::: ### 5. Construir Dicionário Base de Assinatura ```python title="Dicionário base" dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint} ``` #### 5.1. Se necessário, adicionar o conteúdo Para as requisições que tenham _body_, deve-se adicionar o md5 do bytes desse conteúdo. Como todas as requisições no nosso sistema são através de JSON, pode-se usar o seguinte: ```python title="Dicionário base" body_bytes = json.dumps(body).encode() md5_instance = md5() md5_instance.update(body_bytes) md5_body = md5_instance.hexdigest() dict_to_sign["payload_md5"] = md5_body ``` ### 6. Realizar criptografia do header Realizar criptografia utilizando biblioteca JWT (neste exemplo de código, utilizamos jsonwebtoken como jwt em javascript) ```python jwt_headers = {"alg": "ES512", "typ": "JWT"} encoded_header_token = jwt.encode( claims=dict_to_sign, key=client_private_key, algorithm="ES512", headers=jwt_headers, ) ``` ### 7. Montando o header final ```python headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token} ``` ```python title="Definindo url final" url = f"{base_url}{endpoint}" ``` ### Realizando requisição ```python resp = requests.post(url=url, headers=headers, json=body) print(resp.json()) ``` ## Requisições com query string {#query-string} Endpoints paginados ou com filtros recebem parâmetros na *query string* — por exemplo `?page=0&limit=20`. Nesses casos, a *query string* **faz parte da URI assinada**. O campo `uri` deve ser igual ao caminho enviado na requisição: mesmos parâmetros, na mesma ordem e com a mesma codificação. Se a URI assinada e a URI enviada não forem iguais, a requisição é recusada com status `401`: ```json title="Resposta" { "title": "Invalid endpoint", "description": "Invalid endpoint.", "translation": "O endpoint e invalido", "code": "MIT000015" } ``` ### Exemplo ```python title="GET com paginação" base_url = "https://manager-api.qidtvm.com.br" path = "/quota/fund_class/{fund_class_key}/investor_positions" query_string = "page=0&limit=20" # a query string faz parte da uri assinada uri = f"{path}?{query_string}" method = "GET" today_str = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S") dict_to_sign = {"timestamp": today_str, "method": method, "uri": uri} jwt_headers = {"alg": "ES512", "typ": "JWT"} encoded_header_token = jwt.encode( claims=dict_to_sign, key=client_private_key, algorithm="ES512", headers=jwt_headers, ) headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token} resp = requests.get(url=f"{base_url}{uri}", headers=headers) print(resp.json()) ``` ### Recomendações - Monte a *query string* e envie a URL completa. Evite usar o argumento `params` do `requests` junto com uma URI já assinada: o cliente HTTP pode reordenar ou recodificar os parâmetros e invalidar a assinatura. - Requisições `GET` normalmente não têm corpo. Nesse caso, não envie *body* nem o campo `payload_md5`. - Valores com caracteres especiais (pontuação de documentos, datas, espaços) devem ser assinados já no formato final em que serão enviados na URL. --- # Troca de Chaves URL: /documentation/iaas/introducao/troca_de_chaves ## 1. Requisição Assinada Todas as requisições em nossas APIs devem usar o protocolo **HTTPs**, utilizando **TLS 1.2 ou 1.3**, contendo dois Headers: 1. API-CLIENT-KEY: Uma chave disponibilizada pelo nosso time de Integração que identifica uma integração específica; 2. AUTHORIZATION: Uma assinatura da requisição que deve ser realizada conforme explicado nesse manual; Como padrão a QI CTVM utiliza-se do padrão de chaves assimétricas, onde existem duas chaves diferentes, uma para assinatura, denominada chave privada , e uma para leitura, denominada de chave pública . Com a chave privada, o parceiro integrador deverá realizar a assinatura utilizando-se do padrão JWT. O parceiro integrador é responsável por gerar o par e fornecer à QI CTVM a chave pública para que possamos validar as suas requisições. :::caution **Atenção** A chave privada é de uso exclusivo do parceiro integrador, e deve ser armazenada com segurança. A QI CTVM nunca irá pedir, em hipótese alguma, que voce a compartilhe conosco. ::: ## 2. Como entregar a chave pública :::tip Gestoras e consultorias: cadastre pelo portal Se você é uma **gestora** ou uma **consultoria**, o caminho recomendado é cadastrar a chave pública você mesmo, pela tela do Portal do Gestor ou do Portal do Consultor. Veja o guia completo em **[Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal)**. Pelo portal você cria a integração, cadastra a chave pública e recebe a API Key na própria tela — nenhuma chave trafega por e-mail. O cadastro é imediato, o fingerprint da chave fica visível para conferência e a troca pode ser feita a qualquer momento, sem abrir chamado. É o procedimento padrão tanto em sandbox quanto em produção. Para começar, envie ao time de integração o **nome, e-mail e CPF** do usuário master responsável pela homologação — e **apenas isso**. A chave pública não deve ser anexada a essa solicitação. ::: Os demais perfis de acesso — **cedentes, originadores, investidores e distribuidores** — continuam enviando a chave pública gerada ao time de integração da QI Tech, em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), e aguardando a configuração da integração. ## 3. Gerando o par Você pode gerar o par de chaves pelo próprio portal, no momento do cadastro — a chave privada é gerada no seu navegador e baixada apenas para você (veja [Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal)) — ou gerá-lo localmente pelo terminal. Para gerar uma chave privada em um computador UNIX faça: ```bash $ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key ``` E a partir desta chave privada gere sua chave pública. ```bash $ openssl ec -in private.key -pubout -outform PEM -out public.key.pub ``` A chave pública é o arquivo `public.key.pub`. É esse — e somente esse — arquivo que deve ser cadastrado no portal ou enviado ao time de integração. # Vídeo explicativo --- # Início URL: /documentation/iaas/investidor/cadastro_investidor/inicio Esta seção descreve o processo geral de **cadastro de investidores** na plataforma QI Tech. O cadastro é o passo inicial obrigatório antes que qualquer investidor possa participar de uma oferta, subscrever cotas ou movimentar recursos. Ao final do fluxo, a QI Tech executa uma **análise cadastral** que valida os dados, documentos e enquadramento do investidor frente às exigências regulatórias. ### Como o cadastro está estruturado O cadastro de investidor é dividido em três fluxos, organizados de acordo com o canal pelo qual o investidor será integrado. Cada fluxo é descrito em detalhes em sua respectiva subseção. Carteira Administrada carteiras geridas profissionalmente em nome de um titular econômico (investor owner) `investor-integration` Distribuição Externa investidores cadastrados por conta e ordem por meio de distribuidores parceiros `distributor-integration` Cadastrar como Gestor / Consultor gestores (`manager-integration`) e consultores (`consultant-integration`) cadastram seus cotistas — **pessoa física, pessoa jurídica ou classe de fundo de investimento** :::info Classes de fundo de investimento O cadastro de **classes de fundo** (FIMs, FIAs, FIDCs e demais) faz parte do fluxo **Cadastrar como Gestor / Consultor** — é lá que estão todas as etapas, já com as diferenças de PF, PJ e fundo indicadas em cada página. Apenas a **gestora** ou a **administradora** da classe pode realizar esse cadastro. ::: ### Conceitos comuns a todos os fluxos Apesar das particularidades de cada tipo, todos os fluxos compartilham um conjunto de conceitos e recursos: - **Investor / Investor Analysis** — cada investidor possui um identificador único (`investor_key`) e, a cada ciclo de cadastro, uma nova análise cadastral (`investor_analysis_key`). É a análise que recebe os dados, documentos e o resultado final da validação. - **Feedbacks** — durante e após a análise, a QI Tech pode solicitar correções ou complementos por meio de feedbacks, que ficam disponíveis na própria análise cadastral. - **Etapas cadastrais** — os fluxos cadastrais seguem linearmente os seguintes passos: - Criação do investidor (primeiro cadastro) ou análise (atualização) - **Cliente**; - Envio de dados cadastrais e documentos necessários - **Cliente**; - Envio do cadastro para análise - **Cliente**; - Aprovação do cadastro ou retorno para preenchimento com feedbacks - **QI Tech**; - Assinatura de documentos - **Cliente**. Uma vez que o cliente assinar os documentos enviados após a análise, o investidor estará apto a interagir com o resto do sistema, como geração de termos de adesão, boletins de subscrição e boletagem de aportes. --- # atualizacao_cadastral URL: /documentation/iaas/investidor/cadastro/atualizacao_cadastral --- # atualizar_status_grupo_assinantes URL: /documentation/iaas/investidor/cadastro/atualizar_status_grupo_assinantes --- # busca_informacoes_de_uma_analise_cadastral_do_investidor URL: /documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor --- # busca_informacoes_do_investidor URL: /documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor --- # buscar_documentos_para_assinatura URL: /documentation/iaas/investidor/cadastro/buscar_documentos_para_assinatura --- # Buscar Dados de investidores paginado URL: /documentation/iaas/investidor/cadastro/buscar_investidores_paginado --- ### Introdução Este recurso permite listar investidores aplicando filtros opcionais (documento, status e nome), com paginação. ### Input / Output Não há corpo de requisição. Os filtros são passados via *query string*, todos opcionais. Como ***output*** será retornada a lista de investidores que atendem aos filtros informados. ### Request ENDPOINT `/investor_registry/investors` MÉTODO `GET` STATUS `200` ### Query Params Todos os parâmetros são **opcionais**. | Param | Tipo | Default | Descrição | |-------------------|--------|:-------:|--------------------------------------------------------------| | `document_number` | string | `None` | Filtro por documento completo | | `status` | string | `None` | Filtro por status | | `name` | string | `None` | Filtro por nome | | `limit` | int | `100` | Itens por página (mín. `0`, máx. `500`) | | `page` | int | `0` | Página; o offset é calculado como `page * limit` | ### Response ```json title='Response Body' { "data": [ { "name": "investidor 1", "status": "approved", "person_type": "natural_person", "investor_key": "UUID v4", "email": "investidor1@exemplo.com", "phone": "11999990001", "distributor": { "distributor_key": "UUID v4", "name": "Distribuidora XYZ", "document_number": "00000000000191", "registry_configuration": {} } }, { "name": "investidor 2", "status": "pending", "person_type": "natural_person", "investor_key": "UUID v4", "email": "investidor2@exemplo.com", "phone": "11999990002", "distributor": { "distributor_key": "UUID v4", "name": "Distribuidora XYZ", "document_number": "00000000000191", "registry_configuration": {} } } ], "limit": 50, "page": 0, "is_last_page": true } ``` ### Response Params | Campo | Tipo | Descrição | |----------------|---------|--------------------------------------------------------------------| | `data` | array | Lista de objetos de **[Investor](#investor)** | | `limit` | int | Quantidade de itens por página utilizada na consulta | | `page` | int | Página retornada | | `is_last_page` | boolean | Indica se esta é a última página de resultados | ### Investor {#investor} | Campo | Tipo | Descrição | |-----------------|--------|----------------------------------------------------| | `investor_key` | string | Chave única de identificação do investidor | | `name` | string | Nome (ou razão social) do investidor | | `status` | string | Status atual do investidor | | `person_type` | string | Tipo de pessoa (`natural_person` ou `legal_person`) | | `email` | string | E-mail de contato do investidor | | `phone` | string | Telefone de contato do investidor | | `distributor` | object | Objeto de **Distributor** | ### Distributor {#distributor} | Campo | Tipo | Descrição | |--------------------------|--------|--------------------------------------------------| | `distributor_key` | string | Chave única do distribuidor | | `name` | string | Nome do distribuidor | | `document_number` | string | CNPJ do distribuidor | | `registry_configuration` | object | Configurações de cadastro do distribuidor | --- # ciclo_de_vida_da_analise URL: /documentation/iaas/investidor/cadastro/ciclo_de_vida_da_analise --- # consultar_analise_em_andamento URL: /documentation/iaas/investidor/cadastro/consultar_analise_em_andamento --- # atualizar_status_conta_bancaria URL: /documentation/iaas/investidor/cadastro/contas_bancarias/atualizar_status_conta_bancaria --- # definir_conta_principal URL: /documentation/iaas/investidor/cadastro/contas_bancarias/definir_conta_principal --- # enviar_contas_bancarias URL: /documentation/iaas/investidor/cadastro/contas_bancarias/enviar_contas_bancarias --- # Criar investidor URL: /documentation/iaas/investidor/cadastro/criar_investidor --- ### Introdução Este recurso tem como objetivo nos informar dados básicos para iniciar o cadastro de um **investidor**. A criação de um investidor já dispara, em conjunto, a abertura de uma primeira **análise cadastral** vinculada a ele. Por isso, ao final desta chamada são retornadas duas chaves: ***investor_key*** (identifica o investidor) e ***investor_analysis_key*** (identifica a análise cadastral em andamento). O campo **`person_type`** define se o investidor é **pessoa física** (`natural_person`) ou **pessoa jurídica** (`legal_person`). Dentro de pessoa jurídica, o campo **`investor_sub_type`** distingue uma empresa comum (`default`) de uma **classe de fundo de investimento** (`fund_class`), que segue regras próprias ao longo de todo o fluxo. :::info Informação No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início **1**: reprovação automática; CPF/CNPJ com início **8**: pendente de validação manual; o restante é aprovado automaticamente. ::: :::info Informação Para a integração de `gestores` ou `consultores` é possível determinar se o investidor irá preencher os dados através da plataforma, ou não. Caso o investidor vá preencher o próprio cadastro, basta passar o query param `create_investor_user = true` ::: ### Input / Output Como ***input*** envie os dados básicos do investidor. Os campos obrigatórios variam de acordo com **`person_type`** e **`investor_sub_type`**. Como ***output*** serão retornadas a ***investor_key*** e a ***investor_analysis_key***. A ***investor_key*** identifica o investidor; a ***investor_analysis_key*** identifica a análise cadastral aberta junto com a criação. Um mesmo investidor pode possuir mais de uma análise cadastral ao longo do tempo (renovações, atualizações). ### Request ENDPOINT `/investor_registry/investor` MÉTODO `POST` STATUS `201` ### Request body Caso 01: Pessoa Física ```json title='Request Body' { "name": "João da Silva", "document_number": "123.456.789-00", "person_type": "natural_person", "email": "joao.silva@example.com", "phone": { "international_dial_code": "55", "area_code": "11", "number": "987654321" } } ``` Caso 02: Pessoa Jurídica ```json title='Request Body' { "name": "Empresa XPTO Ltda", "document_number": "12.345.678/0001-90", "person_type": "legal_person", "investor_sub_type": "default", "registry_user": { "name": "José da Silva", "document_number": "123.456.789-00", "email": "jose.silva@example.com", "phone": { "international_dial_code": "55", "area_code": "11", "number": "987654321" } } } ``` Caso 03: Classe de Fundo de Investimento ( fund_class ) ```json title='Request Body' { "name": "Fundo XPTO Multimercado", "document_number": "12.345.678/0001-90", "person_type": "legal_person", "investor_sub_type": "fund_class" } ``` :::warning Atenção Os campos obrigatórios mudam de acordo com o **`person_type`** e o **`investor_sub_type`**: - **`natural_person`**: `name`, `document_number`, `person_type` (`email` e `phone` recomendados para criação de usuário) - **`legal_person`** / `default`: `name`, `document_number`, `person_type`, `investor_sub_type` e `registry_user` - **`legal_person`** / `fund_class`: `name`, `document_number`, `person_type` e `investor_sub_type` — **sem `registry_user`**, já que a representação é feita pelos *investor owners* (administrador e gestora) ::: :::warning Classes de fundo: só o gestor ou o administrador cadastra Apenas a **gestora** ou a **administradora** do fundo pode criar um investidor `fund_class`, e somente se o seu próprio cadastro estiver atualizado. Veja **[Introdução](./introducao)** para o detalhamento dessa exigência. ::: :::warning Apenas classes em funcionamento Somente classes **operacionais** na CVM podem ser cadastradas. Classes pré-operacionais, encerradas, canceladas ou incorporadas são recusadas na análise. Se o CNPJ não constar na base da CVM, o `submit` é recusado com `IVR000068`. ::: :::info O que a CVM preenche por você Para `fund_class`, parte dos dados cadastrais é preenchida **automaticamente** a partir da base pública da CVM no momento do envio para análise — incluindo razão social, data de constituição, patrimônio e os vínculos com administrador, gestora e (quando aplicável) investidor exclusivo. Como consequência, **endereço, patrimônio, suitability, grupos de assinantes e documentos do investidor não são enviados** para esse subtipo. Consulte **[Quais etapas se aplicam a cada tipo](./introducao#etapas-por-tipo)**. ::: :::info Sobre o `registry_user` O **`registry_user`** representa o usuário (pessoa física) responsável por preencher os dados cadastrais do investidor. Para **pessoa física**, normalmente este usuário é o próprio investidor e o campo pode ser omitido. Para **pessoa jurídica**, é o representante que responderá pelo preenchimento. ::: ### Body params | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------| | `name` | string | Nome (ou razão social) do investidor | 1 - 255 | Sim | | `person_type` | string | Enumerador de **[Person Type](#person-type)** | - | Sim | | `document_number` | string | CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`). Para `fund_class`, o CNPJ da classe registrada na CVM | 14 ou 18 | Sim* | | `investor_sub_type` | string | Enumerador de **[Investor Sub Type](#investor-sub-type)** | - | Não | | `email` | string | E-mail do investidor | 1 - 255 | Não | | `phone` | object | Objeto de **[Phone](#phone)** | - | Não | | `registry_user` | object | Objeto de **[Registry User](#registry-user)** | - | Não | ### Phone | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------| | `international_dial_code` | string | Código internacional (ex.: `55`) | 1 - 3 | Sim | | `area_code` | string | DDD | 2 | Sim | | `number` | string | Número do telefone | 8 - 9 | Sim | ### Registry User | Campo | Tipo | Descrição | Caracteres | Obrigatório | |---------------------|----------|------------------------------------------------------|--------------|-------------| | `name` | string | Nome do usuário cadastrador | 1 - 255 | Sim | | `document_number` | string | CPF do usuário (formato `XXX.XXX.XXX-XX`) | 14 | Sim | | `email` | string | E-mail do usuário | 1 - 255 | Sim | | `phone` | object | Objeto de **[Phone](#phone)** | - | Sim | ### Person Type {#person-type} | Enumerador | Descrição | |---------------------|------------------------------------------------------| | `natural_person` | Pessoa física | | `legal_person` | Pessoa jurídica | ### Investor Sub Type {#investor-sub-type} | Enumerador | Descrição | |--------------------------|--------------------------------------------------------------------------------------------| | `default` | Pessoa jurídica regular (default quando o campo não é informado) | | `fund_class` | Classe de fundo de investimento — dispara o enriquecimento automático com os dados públicos da CVM e segue regras próprias de etapas, partes relacionadas e investor owners | ### Response ```json title='Response Body' { "investor_key": "UUID", "investor_analysis_key": "UUID" } ``` --- # definir_grupo_assinantes_padrao URL: /documentation/iaas/investidor/cadastro/definir_grupo_assinantes_padrao --- # enviar_cadastro_para_analise URL: /documentation/iaas/investidor/cadastro/enviar_cadastro_para_analise --- # enviar_dados_cadastrais URL: /documentation/iaas/investidor/cadastro/enviar_dados_cadastrais --- # enviar_endereco URL: /documentation/iaas/investidor/cadastro/enviar_endereco --- # enviar_grupos_assinantes URL: /documentation/iaas/investidor/cadastro/enviar_grupos_assinantes --- # enviar_investor_document URL: /documentation/iaas/investidor/cadastro/enviar_investor_document --- # enviar_patrimonio URL: /documentation/iaas/investidor/cadastro/enviar_patrimonio --- # consultar_feedback URL: /documentation/iaas/investidor/cadastro/feedback/consultar_feedback --- # enviar_mensagem_feedback URL: /documentation/iaas/investidor/cadastro/feedback/enviar_mensagem_feedback --- # listar_feedbacks URL: /documentation/iaas/investidor/cadastro/feedback/listar_feedbacks --- # Introdução URL: /documentation/iaas/investidor/cadastro/introducao Esta seção reúne os cadastros feitos por um gestor (`manager-integration`) ou consultor (`consultant-integration`) em nome de seus cotistas, cobrindo os **três tipos de investidor** que essa integração pode cadastrar: | Tipo | `person_type` / `investor_sub_type` | O que é | |------|--------------------------------------|---------| | **Pessoa Física (PF)** | `natural_person` | Investidor pessoa física | | **Pessoa Jurídica (PJ)** | `legal_person` + `investor_sub_type: default` | Empresa investidora — inclui `financial_institution` | | **Fundo de Investimento** | `legal_person` + `investor_sub_type: fund_class` | Classe de fundo com CNPJ próprio (FIMs, FIAs, FIDCs e demais), que aplica recursos em nome de seus cotistas | O cadastro contempla o envio de dados cadastrais, endereço, patrimônio, contas bancárias, suitability, grupos de assinantes, documentos, partes relacionadas e, quando aplicável, *investor owner*, até o disparo da análise cadastral pela QI Tech. **As etapas exigidas variam conforme o tipo** — cada página adiante indica o que se aplica a PF, a PJ e a fundo. Importante ressaltar que, para PF e PJ, a assinatura é sempre executada exclusivamente pelo investidor ou representante legal identificado durante a análise. :::warning Fundos: só o gestor ou o administrador cadastra O cadastro de uma classe de fundo **só pode ser feito pela gestora ou pela administradora** do próprio fundo. Não há outro papel autorizado a abrir esse cadastro. Além disso, **o cadastro de quem cadastra precisa estar em dia**: apenas gestoras e administradoras com o próprio cadastro atualizado conseguem cadastrar classes de fundo. Essa manutenção é feita pela mesma API — a gestora ou administradora atualiza o próprio cadastro por **[Atualização Cadastral](./atualizacao_cadastral)** e, na sequência, mantém as suas classes de fundo enquanto investidores. ::: :::warning Apenas classes de fundo em funcionamento Somente classes **em funcionamento (operacionais)** na CVM podem ser cadastradas. Classes em fase pré-operacional, encerradas, canceladas, incorporadas ou de qualquer forma não operacionais são recusadas na análise. O enquadramento é lido da base pública da CVM a partir do CNPJ informado na criação do investidor. Se o CNPJ não constar na base da CVM, o campo fica indefinido e o `submit` é recusado com `IVR000068` — em Homologação, utilize um CNPJ de classe efetivamente registrada e em funcionamento. ::: ### Fluxo de Cadastro 1. Criar Investidor criação inicial do investidor e abertura da primeira análise cadastral ↓ 2. Enviar Dados Cadastrais PF, PJ e fundo — dados específicos da pessoa física ou jurídica ↓ 3. Enviar Endereço PF e PJ — informações de endereço. Fundo: etapa pulada ↓ 4. Enviar Patrimônio PF e PJ — patrimônio e enquadramento. Fundo: etapa pulada ↓ 5. Enviar Contas Bancárias PF, PJ e fundo — contas para movimentação ↓ 6. Enviar Suitability PF e PJ — questionário de adequação ao perfil. Fundo: etapa pulada ↓ 7. Enviar Grupos de Assinantes PF e PJ — quem deve assinar os documentos. Fundo: etapa pulada ↓ 8. Enviar Documentos do Investidor PF e PJ — upload dos documentos obrigatórios. Fundo: etapa pulada ↓ 9. Criar Partes Relacionadas PJ — sócios, diretores, beneficiários finais. Fundo: só se for exclusivo na CVM ↓ 10. Enviar Documentos das Partes Relacionadas documentos de cada parte relacionada. Fundo: só se for exclusivo na CVM ↓ 11. Enviar para Análise submissão da análise cadastral para validação ↓ 12. Assinar Documentos assinatura dos documentos gerados após aprovação ### Quais etapas se aplicam a cada tipo {#etapas-por-tipo} | Etapa | PF | PJ | Classe de fundo | |-------|:--:|:--:|:----------------| | 1. Criar Investidor | ✅ | ✅ | ✅ | | 2. Enviar Dados Cadastrais | ✅ | ✅ | ✅ *(razão social, data de constituição e patrimônio vêm da CVM)* | | 3. Enviar Endereço | ✅ | ✅ | ⏭️ **pulado** | | 4. Enviar Patrimônio | ✅ | ✅ | ⏭️ **pulado** | | 5. Enviar Contas Bancárias | ✅ | ✅ | ✅ | | 6. Enviar Suitability | ✅ | ✅ *(obrigatório em `retail`)* | ⏭️ **pulado** | | 7. Enviar Grupos de Assinantes | ✅ | ✅ | ⏭️ **pulado** | | 8. Enviar Documentos do Investidor | ✅ | ✅ | ⏭️ **pulado** | | 9. Criar Partes Relacionadas | opcional | ✅ obrigatório | ⚠️ **só se exclusivo** | | 10. Documentos das Partes Relacionadas | opcional | ✅ obrigatório | ⚠️ **só se exclusivo** | | 11. Enviar para Análise | ✅ | ✅ | ✅ | | 12. Assinar Documentos | ✅ | ✅ | ✅ | :::info O que uma classe de fundo **não** envia Endereço, patrimônio, suitability, grupos de assinantes e documentos do investidor **não fazem parte do cadastro de uma classe de fundo** — nenhum deles é exigido no `submit`, e as etapas correspondentes podem ser puladas por completo. Os dados que sustentam a análise vêm de outra fonte: razão social, data de constituição, patrimônio e os vínculos com **administrador** e **gestora** são preenchidos automaticamente a partir da base pública da CVM no envio para análise. A representação do fundo se dá por esses *investor owners*, e não por representantes legais. ::: :::warning Partes relacionadas: apenas em classe exclusiva Partes relacionadas e seus documentos são exigidos **quando, e somente quando, a classe é exclusiva na CVM**. Nesse caso é obrigatória ao menos uma parte relacionada do tipo `exclusive_investor`, e a participação somada precisa fechar **exatamente 100%**. Para uma classe **não exclusiva**, pule as etapas 9 e 10 — nenhuma parte relacionada é necessária. O caráter exclusivo (`exclusive_fund_class`) é derivado automaticamente da classe CVM na criação do investidor; consulte **[Criar Parte Relacionada — Exigências por tipo de investidor](./related_party/criar_parte_relacionada#exigencias)** para a matriz completa. ::: Nas subseções a seguir veremos cada uma das etapas necessárias para concluir esses cadastros, com as diferenças de PF, PJ e classe de fundo indicadas em cada página. --- # atualizar_parte_relacionada URL: /documentation/iaas/investidor/cadastro/related_party/atualizar_parte_relacionada --- # atualizar_status_parte_relacionada URL: /documentation/iaas/investidor/cadastro/related_party/atualizar_status_parte_relacionada --- # criar_parte_relacionada URL: /documentation/iaas/investidor/cadastro/related_party/criar_parte_relacionada --- # enviar_documento_parte_relacionada URL: /documentation/iaas/investidor/cadastro/related_party/enviar_documento_parte_relacionada --- # consultar_formulario_suitability URL: /documentation/iaas/investidor/cadastro/suitability/consultar_formulario_suitability --- # enviar_suitability URL: /documentation/iaas/investidor/cadastro/suitability/enviar_suitability --- # atualizacao_cadastral URL: /documentation/iaas/investidor/carteira_administrada/atualizacao_cadastral --- # atualizar_status_grupo_assinantes URL: /documentation/iaas/investidor/carteira_administrada/atualizar_status_grupo_assinantes --- # busca_informacoes_de_uma_analise_cadastral_do_investidor URL: /documentation/iaas/investidor/carteira_administrada/busca_informacoes_de_uma_analise_cadastral_do_investidor --- # busca_informacoes_do_investidor URL: /documentation/iaas/investidor/carteira_administrada/busca_informacoes_do_investidor --- # buscar_documentos_para_assinatura URL: /documentation/iaas/investidor/carteira_administrada/buscar_documentos_para_assinatura --- # ciclo_de_vida_da_analise URL: /documentation/iaas/investidor/carteira_administrada/ciclo_de_vida_da_analise --- # consultar_analise_em_andamento URL: /documentation/iaas/investidor/carteira_administrada/consultar_analise_em_andamento --- # atualizar_status_conta_bancaria URL: /documentation/iaas/investidor/carteira_administrada/contas_bancarias/atualizar_status_conta_bancaria --- # definir_conta_principal URL: /documentation/iaas/investidor/carteira_administrada/contas_bancarias/definir_conta_principal --- # enviar_contas_bancarias URL: /documentation/iaas/investidor/carteira_administrada/contas_bancarias/enviar_contas_bancarias --- # Criar investidor URL: /documentation/iaas/investidor/carteira_administrada/criar_investidor --- ### Introdução Este recurso tem como objetivo nos informar dados básicos para iniciar o cadastro de um **investidor**. A criação de um investidor já dispara, em conjunto, a abertura de uma primeira **análise cadastral** vinculada a ele. Por isso, ao final desta chamada são retornadas duas chaves: ***investor_key*** (identifica o investidor) e ***investor_analysis_key*** (identifica a análise cadastral em andamento). :::info Informação No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início **1**: reprovação automática; CPF/CNPJ com início **8**: pendente de validação manual; o restante é aprovado automaticamente. ::: ### Input / Output Como ***input*** envie os dados básicos do investidor. Os campos obrigatórios variam de acordo com **`person_type`** e **`investor_sub_type`**. Como ***output*** serão retornadas a ***investor_key*** e a ***investor_analysis_key***. A ***investor_key*** identifica o investidor; a ***investor_analysis_key*** identifica a análise cadastral aberta junto com a criação. Um mesmo investidor pode possuir mais de uma análise cadastral ao longo do tempo (renovações, atualizações). ### Request ENDPOINT `/investor_registry/investor` MÉTODO `POST` STATUS `201` ### Request body Caso 01: Pessoa Física ```json title='Request Body' { "name": "João da Silva", "document_number": "123.456.789-00", "person_type": "natural_person", "email": "joao.silva@example.com", "phone": { "international_dial_code": "55", "area_code": "11", "number": "987654321" } } ``` Caso 02: Pessoa Jurídica ```json title='Request Body' { "name": "Empresa XPTO Ltda", "document_number": "12.345.678/0001-90", "person_type": "legal_person", "investor_sub_type": "default" } ``` :::warning Atenção Os campos obrigatórios mudam de acordo com o **`person_type`**: - **`natural_person`**: `name`, `document_number`, `person_type` (`email` e `phone` recomendados para criação de usuário) - **`legal_person`**: `name`, `document_number`, `person_type`, `investor_sub_type` ::: ### Body params | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------| | `name` | string | Nome (ou razão social) do investidor | 1 - 255 | Sim | | `person_type` | string | Enumerador de **[Person Type](#person-type)** | - | Sim | | `document_number` | string | CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`) | 14 ou 18 | Sim* | | `investor_sub_type` | string | Enumerador de **[Investor Sub Type](#investor-sub-type)** | - | Não | | `email` | string | E-mail do investidor | 1 - 255 | Não | | `phone` | object | Objeto de **[Phone](#phone)** | - | Não | | `investor_owner_type` | string | Tipo de relação de propriedade - Enumerador de **[Investor Owner Type](#investor-owner-type)** | 1 - 255 | Não | ### Phone | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------| | `international_dial_code` | string | Código internacional (ex.: `55`) | 1 - 3 | Sim | | `area_code` | string | DDD | 2 | Sim | | `number` | string | Número do telefone | 8 - 9 | Sim | ### Person Type {#person-type} | Enumerador | Descrição | |---------------------|------------------------------------------------------| | `natural_person` | Pessoa física | | `legal_person` | Pessoa jurídica | ### Investor Sub Type {#investor-sub-type} | Enumerador | Descrição | |--------------------------|--------------------------------------------------------------------------------------------| | `default` | Pessoa jurídica regular (default quando o campo não é informado) | ### Investor Owner Type {#investor-owner-type} | Enumerador | Descrição | |--------------------------|--------------------------------------------------------------------------------------------| | `wallet_manager` | Gestor de Carteira ### Response ```json title='Response Body' { "investor_key": "UUID", "investor_analysis_key": "UUID" } ``` --- # definir_grupo_assinantes_padrao URL: /documentation/iaas/investidor/carteira_administrada/definir_grupo_assinantes_padrao --- # enviar_cadastro_para_analise URL: /documentation/iaas/investidor/carteira_administrada/enviar_cadastro_para_analise --- # enviar_dados_cadastrais URL: /documentation/iaas/investidor/carteira_administrada/enviar_dados_cadastrais --- # enviar_endereco URL: /documentation/iaas/investidor/carteira_administrada/enviar_endereco --- # enviar_grupos_assinantes URL: /documentation/iaas/investidor/carteira_administrada/enviar_grupos_assinantes --- # enviar_investor_document URL: /documentation/iaas/investidor/carteira_administrada/enviar_investor_document --- # enviar_patrimonio URL: /documentation/iaas/investidor/carteira_administrada/enviar_patrimonio --- # consultar_feedback URL: /documentation/iaas/investidor/carteira_administrada/feedback/consultar_feedback --- # enviar_mensagem_feedback URL: /documentation/iaas/investidor/carteira_administrada/feedback/enviar_mensagem_feedback --- # listar_feedbacks URL: /documentation/iaas/investidor/carteira_administrada/feedback/listar_feedbacks --- # Introdução URL: /documentation/iaas/investidor/carteira_administrada/introducao Esta seção descreve o fluxo de cadastro de investidores do tipo **Carteira Administrada** — carteiras geridas profissionalmente em nome de um titular econômico (o *investor owner*). Diferente do cadastro de uma pessoa física ou jurídica padrão, aqui o investidor é a própria carteira, e o cadastro precisa contemplar tanto os dados da carteira quanto os dados do titular que detém os recursos investidos por meio dela. O tipo de integração utilizada para esse tipo de cadastro de investidor é a `investor-integration`, descrita na seção de introdução da documentação. Para cadastrar um investidor através de uma gestora de carteiras é necessário que o cadastro da gestora esteja atualizado, o que pode ser garantido e mantido através da mesma integração de investidor. Dessa forma, a gestora pode realizar sua atualização cadastral através da API de cadastro de investidores, bem como a manutenção de seus próprios investidores. Um ponto muito importante é que apenas gestoras que estiverem com seus cadastros atualizados podem realizar o cadastro de investidores de carteira administrada. Portanto, é necessário realizar essa manutenção cadastral. ### Fluxo de Cadastro 1. Criar Investidor criação inicial do investidor e abertura da primeira análise cadastral ↓ 2. Enviar Dados Cadastrais dados específicos da pessoa física ou jurídica ↓ 3. Enviar Endereço informações de endereço ↓ 4. Enviar Patrimônio informações de patrimônio e enquadramento ↓ 5. Enviar Contas Bancárias contas para movimentação ↓ 6. Enviar Suitability questionário de adequação ao perfil ↓ 7. Enviar Grupos de Assinantes definição de quem deve assinar os documentos ↓ 8. Enviar Documentos do Investidor upload de documentos obrigatórios ↓ 9. Criar Partes Relacionadas sócios, diretores, beneficiários finais ↓ 10. Enviar Documentos das Partes Relacionadas documentos de cada parte relacionada ↓ 11. Enviar Contrato de Carteira Administrada documento que atesta representação legal ↓ 12. Enviar para Análise submissão da análise cadastral para validação ↓ 13. Assinar Documentos assinatura dos documentos gerados após aprovação Nas subseções a seguir veremos cada uma das etapas necessárias para concluir o cadastro de uma Carteira Administrada e disparar a análise cadastral pela QI Tech. --- # enviar_documento_investor_owner URL: /documentation/iaas/investidor/carteira_administrada/investor_owner/enviar_documento_investor_owner --- # atualizar_parte_relacionada URL: /documentation/iaas/investidor/carteira_administrada/related_party/atualizar_parte_relacionada --- # atualizar_status_parte_relacionada URL: /documentation/iaas/investidor/carteira_administrada/related_party/atualizar_status_parte_relacionada --- # criar_parte_relacionada URL: /documentation/iaas/investidor/carteira_administrada/related_party/criar_parte_relacionada --- # enviar_documento_parte_relacionada URL: /documentation/iaas/investidor/carteira_administrada/related_party/enviar_documento_parte_relacionada --- # consultar_formulario_suitability URL: /documentation/iaas/investidor/carteira_administrada/suitability/consultar_formulario_suitability --- # enviar_suitability URL: /documentation/iaas/investidor/carteira_administrada/suitability/enviar_suitability --- # Adicionar Conta Bancária URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/adicionar_contas_bancarias --- ### Request ENDPOINT /investor_registry/investor/\{investor_key\}/bank_account MÉTODO POST STATUS 201 ### Request body ```json title='Request Body' { "financial_institution_code": "329", "account_number": "000000", "account_digit": "0", "account_branch": "000" } ``` ### Body params | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------| | `financial_institution_code` | string | Código da Instituição Financeira | 1 - 4 | Sim | | `account_number` | string | Número de Conta | 1 - 20 | Sim | | `account_digit` | string | Dígito de Conta | 1 | Sim | | `account_branch` | string | Agência | 1 - 4 | Sim | ### Response ```json title='Response Body' { "bank_account_key": "UUID", "external_bank_account_key": "UUID", "status": "active" } ``` | Campo | Tipo | Descrição | |-----------------------------|--------|----------------------------------------------------------------------------------------------| | `bank_account_key` | string | Identificador interno da conta bancária criada | | `external_bank_account_key` | string | Chave usada nas rotas de manutenção da conta | | `status` | string | Status da conta na criação — sempre `active` | ### Erros Tratáveis | Código | Significado | |------------------------------------|-----------------| "IVR000077" | Essa conta já foi cadastrada para o investidor | --- # Atualizar Conta Bancária URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_conta_bancaria --- ### Request ENDPOINT /investor_registry/investor/\{investor_key\}/bank_account/\{bank_account_key\}/update MÉTODO PUT STATUS 204 ### Request body ```json title='Request Body' { "status": "str", "main_account": true, } ``` :::warning Atenção Existem três formas de atualizar a conta bancária: - Atualizar o *status* para inactive , desativando o uso da conta. - Atualizar o *status* para active , reativando o uso da conta. - Atualizar a definição de conta principal utilizando a propriedade *main_account* , tornando a conta em questão a principal do investidor. Caso sejam enviados ambos os parâmetros, um erro será retornado. ::: ### Body params | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------| | `status` | string | Novo Status da Conta | 1 - 20 | Não | | `main_account` | bool | Define se a conta é a principal do investidor | - | Não | --- # Consultar Contas Bancárias URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/buscar_contas_bancarias --- ### Request ENDPOINT /investor/investor/INVESTOR_KEY/bank_accounts MÉTODO GET STATUS 200 ### Query params | Campo | Tipo | Descrição | Opções | Obrigatório | |-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------| | `status` | string | Novo Status da Conta | "active" ou "inactive" | Não | | `main_account` | bool | Define se a conta é a principal do investidor | True ou False | Não | ### Responses ```json { "data": [ { "bank_account_key": "UUID4", "financial_institution_code": "329", "account_number": "00000000", "account_digit": "0", "account_branch": "0001", "main_account": true, "status": "active" }, { "bank_account_key": "UUID4", "financial_institution_code": "329", "account_number": "00000000", "account_digit": "0", "account_branch": "0001", "main_account": false, "status": "inactive" } ], "limit": 50, "page": 0, "is_last_page": true } ``` --- # assinar_documento URL: /documentation/iaas/investidor/distribuicao_externa/assinar_documento --- # atualizacao_cadastral URL: /documentation/iaas/investidor/distribuicao_externa/atualizacao_cadastral --- # atualizar_status_grupo_assinantes URL: /documentation/iaas/investidor/distribuicao_externa/atualizar_status_grupo_assinantes --- # busca_informacoes_de_uma_analise_cadastral_do_investidor URL: /documentation/iaas/investidor/distribuicao_externa/busca_informacoes_de_uma_analise_cadastral_do_investidor --- # busca_informacoes_do_investidor URL: /documentation/iaas/investidor/distribuicao_externa/busca_informacoes_do_investidor --- # buscar_documentos_para_assinatura URL: /documentation/iaas/investidor/distribuicao_externa/buscar_documentos_para_assinatura --- # ciclo_de_vida_da_analise URL: /documentation/iaas/investidor/distribuicao_externa/ciclo_de_vida_da_analise --- # consultar_analise_em_andamento URL: /documentation/iaas/investidor/distribuicao_externa/consultar_analise_em_andamento --- # atualizar_status_conta_bancaria URL: /documentation/iaas/investidor/distribuicao_externa/contas_bancarias/atualizar_status_conta_bancaria --- # definir_conta_principal URL: /documentation/iaas/investidor/distribuicao_externa/contas_bancarias/definir_conta_principal --- # enviar_contas_bancarias URL: /documentation/iaas/investidor/distribuicao_externa/contas_bancarias/enviar_contas_bancarias --- # Criar investidor URL: /documentation/iaas/investidor/distribuicao_externa/criar_investidor --- ### Introdução Este recurso tem como objetivo nos informar dados básicos para iniciar o cadastro de um **investidor**. A criação de um investidor já dispara, em conjunto, a abertura de uma primeira **análise cadastral** vinculada a ele. Por isso, ao final desta chamada são retornadas duas chaves: ***investor_key*** (identifica o investidor) e ***investor_analysis_key*** (identifica a análise cadastral em andamento). Existem 3 tipos principais de investidor, definidos pelo campo **`person_type`**: **pessoa física** (`natural_person`), **pessoa jurídica** (`legal_person`) e **PCO** ('nominee'). Para pessoas jurídicas, o campo **`investor_sub_type`** distingue subtipos como **fundo de investimento** (`fund_class`), que possuem regras próprias ao longo do fluxo de cadastro. :::warning Atenção Para os casos de investidores distribuídos por conta e ordem (PCO | `nominee`) não existe uma esteira cadastral e portanto, apenas o `POST` de criação é necessário para torná-lo apto em todo o sistema. ::: :::info Informação No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início **1**: reprovação automática; CPF/CNPJ com início **8**: pendente de validação manual; o restante é aprovado automaticamente. ::: ### Input / Output Como ***input*** envie os dados básicos do investidor. Os campos obrigatórios variam de acordo com **`person_type`** e **`investor_sub_type`**. Como ***output*** serão retornadas a ***investor_key*** e a ***investor_analysis_key***. A ***investor_key*** identifica o investidor; a ***investor_analysis_key*** identifica a análise cadastral aberta junto com a criação. Um mesmo investidor pode possuir mais de uma análise cadastral ao longo do tempo (renovações, atualizações). ### Request ENDPOINT `/investor_registry/v2/investor` MÉTODO `POST` STATUS `201` ### Request body Caso 01: Pessoa Física ```json title='Request Body' { "name": "João da Silva", "document_number": "123.456.789-00", "person_type": "natural_person", "email": "joao.silva@example.com", "phone": { "international_dial_code": "55", "area_code": "11", "number": "987654321" } } ``` Caso 02: Pessoa Jurídica ```json title='Request Body' { "name": "Empresa XPTO Ltda", "document_number": "12.345.678/0001-90", "person_type": "legal_person", "investor_sub_type": "default", "registry_user": { "name": "José da Silva", "document_number": "123.456.789-00", "email": "jose.silva@example.com", "phone": { "international_dial_code": "55", "area_code": "11", "number": "987654321" } } } ``` Caso 03: Pessoa Jurídica — Fundo de Investimento ( fund_class ) ```json title='Request Body' { "name": "Fundo XPTO Multimercado", "document_number": "12.345.678/0001-90", "person_type": "legal_person", "investor_sub_type": "fund_class" } ``` Caso 04: Nominee (PCO) ```json title='Request Body' { "name": "Nominee XPTO", "person_type": "nominee", "external_distribution_key": "ID-DISTRIBUICAO-001" } ``` :::warning Campos obrigatórios por `person_type` Os campos obrigatórios mudam de acordo com o **`person_type`**. A ausência de qualquer um deles é recusada com `IVR000009`, cuja mensagem lista a relação completa exigida. - **`natural_person`**: `name`, `document_number`, `person_type`, **`investor_sub_type`** - **`legal_person`**: `name`, `document_number`, `person_type`, **`investor_sub_type`** - **`nominee`**: `name`, `person_type`, `external_distribution_key` **`investor_sub_type` é obrigatório também para pessoa física** — envie `default` quando não houver subtipo específico. `email` e `phone` são opcionais para um distribuidor, mas recomendados: sem `email`, nenhum usuário de acesso é criado para o investidor. ::: :::info Sobre o `registry_user` O **`registry_user`** representa o usuário (pessoa física) responsável por preencher os dados cadastrais do investidor. Para **pessoa física**, normalmente este usuário é o próprio investidor e o campo pode ser omitido. Para **pessoa jurídica**, é o representante que responderá pelo preenchimento. Quando enviado, o objeto exige `name`, `document_number` e `email`. Se omitido em pessoa física, o usuário é derivado do `email` do próprio investidor — e, se o investidor também não tiver `email`, nenhum usuário é criado. ::: :::warning `investor_owner_type` não é aceito de distribuidores Apesar de existir no schema, `investor_owner_type` é **recusado** quando o investidor é criado por uma integração de distribuidor com `person_type` `natural_person` ou `legal_person`. Vínculos de carteira administrada e de fundo são estabelecidos pelo endpoint **Criar Investor Owner**, dentro da análise cadastral. ::: ### Investidor não residente {#nao-residente} A residência é definida **na criação do investidor** e é imutável depois disso. Ela é controlada pelo campo `resident`. ```json title='Request Body — pessoa física não residente' { "name": "Maria Fernandes", "document_number": "123.456.789-00", "person_type": "natural_person", "investor_sub_type": "default", "resident": false, "non_resident_type": "third_party_representation", "investor_owners": [ { "type": "non_resident_representative", "name": "Representante Legal Brasil Ltda", "document_number": "12.345.678/0001-90" } ] } ``` | Campo | Tipo | Descrição | Obrigatório | |----------------------|---------|-----------------------------------------------------------------------------------------------------|-------------| | `resident` | boolean | Define a residência da análise cadastral. Default `true` | Não | | `non_resident_type` | string | `self_representation` ou `third_party_representation`. Obrigatório quando `resident: false` (`IVR000222`) | Condicional | | `investor_owners` | array | Representante legal residente no Brasil, com `type: "non_resident_representative"` | Não | #### Tipos de representação {#non-resident-type} `non_resident_type` declara **como o investidor não residente é representado no Brasil**. É essa escolha que determina quais entidades você precisa cadastrar e quais documentos serão exigidos no envio para análise. | Enumerador | Tipo de conta | Significado | |------------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| | `third_party_representation` | Conta **4373** | O INR opera por meio de terceiros: existe um **custodiante**, responsável pela guarda dos ativos, e um **representante legal brasileiro**, responsável por representá-lo no país. Na prática, costumam ser a mesma entidade. | | `self_representation` | Conta **CNR** (autocustódia / representação tributária) | O investidor é seu próprio custodiante e representante. **Não** existe custodiante nem representante terceiro. | O que muda entre os dois: | | `third_party_representation` | `self_representation` | |------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------| | **Custodiante** | Parte relacionada do tipo `asset_custodian` | Não existe | | **Representante** | Investor owner do tipo `non_resident_representative` — sempre **residente**, com CPF/CNPJ | Não existe | | **Documentos de representação** | `custody_contract` (no custodiante) **e** `representation_contract` (no representante) — **ou** uma única `simplified_declaration` na análise | Nenhum | :::warning Como a exigência documental é verificada Em `third_party_representation`, o `custody_contract` só é reconhecido quando enviado em uma parte relacionada **ativa** do tipo `asset_custodian`, e o `representation_contract` só é reconhecido quando enviado em um investor owner **ativo** do tipo `non_resident_representative`. Enviar os dois contratos como documentos da análise cadastral não satisfaz a regra. Se a combinação não for encontrada no `submit`, a resposta é `IVR000029`. ::: Regras que valem para **os dois** tipos: - `nif_number` é **obrigatório** no envio dos dados cadastrais (`IVR000224`); - parte relacionada estrangeira sem CPF/CNPJ precisa de `passport` ou `foreign_id`; - pessoa física nascida no Brasil (`natural_person.place_of_birth.country: "BRA"`) precisa de `final_departure_tax_return`. :::info `non_resident_type` é imutável O valor é fixado na criação do investidor. Você pode reenviá-lo nos dados cadastrais, mas apenas com o **mesmo** valor — divergência, ou envio em um cadastro residente, resulta em `IVR000225`. ::: :::warning Residência e endereço precisam concordar Com `resident: true` (default), o endereço enviado na Etapa 3 precisa ter `country: "BRA"`, senão `IVR000227`. Com `resident: false`, o `country` **não** pode ser `BRA`, senão `IVR000226`. `postal_code` e `uf` não têm validação de formato, então códigos postais estrangeiros são aceitos como estão. Use `EX` em `uf` para endereços no exterior. ::: :::info Investidores `fund_class` Para fundos de investimento (`investor_sub_type: "fund_class"`), parte dos dados cadastrais é preenchida automaticamente a partir da base da CVM no momento do envio para análise — incluindo razão social, data de constituição, patrimônio e vínculos com administrador, gestor e (quando aplicável) investidor exclusivo. Veja o documento **Criar Investor Owner** para o cadastro de relações de propriedade adicionais. ::: ### Body params | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------| | `name` | string | Nome (ou razão social) do investidor | 1 - 255 | Sim | | `person_type` | string | Enumerador de **[Person Type](#person-type)** | - | Sim | | `investor_sub_type` | string | Enumerador de **[Investor Sub Type](#investor-sub-type)**. Exigido para `natural_person` e `legal_person` | - | Sim | | `document_number` | string | CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`) | 14 ou 18 | Sim* | | `external_distribution_key` | string | Identificador externo da distribuição (obrigatório para `nominee`) | 1 - 100 | Sim* | | `resident` | boolean | Residência da análise cadastral. Default `true`. Veja [Investidor não residente](#nao-residente) | - | Não | | `non_resident_type` | string | `self_representation` ou `third_party_representation`. Exigido quando `resident: false` | - | Condicional | | `investor_owners` | array | Representante legal residente, para investidor não residente | - | Não | | `email` | string | E-mail do investidor | 1 - 255 | Não | | `phone` | object | Objeto de **[Phone](#phone)** | - | Não | | `registry_user` | object | Objeto de **[Registry User](#registry-user)** | - | Não | | `external_id` | string | Identificador do investidor no seu sistema | 1 - 50 | Não | \* `document_number` não deve ser enviado para `person_type: nominee`. `external_distribution_key` é exigido apenas para `nominee`. ### Phone | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------| | `international_dial_code` | string | Código internacional (ex.: `55`) | 1 - 3 | Sim | | `area_code` | string | DDD | 2 | Sim | | `number` | string | Número do telefone | 8 - 9 | Sim | ### Registry User | Campo | Tipo | Descrição | Caracteres | Obrigatório | |---------------------|----------|------------------------------------------------------|--------------|-------------| | `name` | string | Nome do usuário cadastrador | 1 - 255 | Sim | | `document_number` | string | CPF do usuário (formato `XXX.XXX.XXX-XX`) | 14 | Sim | | `email` | string | E-mail do usuário | 1 - 255 | Sim | | `phone` | object | Objeto de **[Phone](#phone)** | - | Sim | ### Person Type {#person-type} | Enumerador | Descrição | |---------------------|------------------------------------------------------| | `natural_person` | Pessoa física | | `legal_person` | Pessoa jurídica | | `nominee` | Nominee / PCO (sem documento obrigatório) | ### Investor Sub Type {#investor-sub-type} | Enumerador | Descrição | |--------------------------|--------------------------------------------------------------------------------------------| | `default` | Investidor regular, pessoa física ou jurídica | | `fund_class` | Fundo de investimento — dispara enriquecimento automático com dados públicos da CVM | | `financial_institution` | Instituição financeira. Segue as mesmas regras de `default` | | `non_resident` | Subtipo de classificação. **Não** define a residência da análise — para isso use `resident` | ### Response ```json title='Response Body' { "investor_key": "UUID", "investor_analysis_key": "UUID" } ``` --- # definir_grupo_assinantes_padrao URL: /documentation/iaas/investidor/distribuicao_externa/definir_grupo_assinantes_padrao --- # enviar_cadastro_para_analise URL: /documentation/iaas/investidor/distribuicao_externa/enviar_cadastro_para_analise --- # Enviar Dados Cadastrais do Investidor URL: /documentation/iaas/investidor/distribuicao_externa/enviar_dados_cadastrais --- ### Introdução Este recurso tem como objetivo enviar os dados cadastrais específicos da pessoa que compõe a **análise cadastral** de um investidor. O corpo enviado deve conter **um** dos blocos `natural_person` ou `legal_person`, coerente com o `person_type` informado na criação do investidor. ### Input / Output Como ***input*** envie os dados cadastrais específicos do tipo de investidor. Como ***output*** será retornada a representação atualizada da análise cadastral. As chaves ***investor_key*** e ***investor_analysis_key*** identificam o investidor e a análise atualizada. :::info Investidor `fund_class` Para fundos de investimento (`investor_sub_type: "fund_class"`), as informações da pessoa jurídica (razão social, data de constituição, etc.) são preenchidas **automaticamente** a partir da base da CVM ao enviar a análise para validação. Esta etapa não é necessária para esse subtipo. ::: ### Request ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/registry_data` MÉTODO `PUT` STATUS `202` ### Request body Exemplo: Pessoa Física ```json title='Request Body' { "name": "João da Silva", "email": "joao.silva@example.com", "phone": { "international_dial_code": "55", "area_code": "11", "number": "987654321" }, "natural_person": { "birthdate": "1990-05-15", "gender": "male", "mother_name": "Maria da Silva", "nationality": "BRA", "place_of_birth": { "country": "BRA", "uf": "SP", "city": "São Paulo" }, "marital_status": "single", "spouse": { "name": "Maria Santos", "document_number": "123.456.789-00" }, "profession": "Engenheiro", "occupation": "Engenheiro de Software", "occupation_company": { "name": "Empresa XYZ Ltda", "document_number": "12.345.678/0001-90" } } } ``` Exemplo: Pessoa Jurídica ```json title='Request Body' { "name": "Empresa XPTO Ltda", "email": "contato@empresaxpto.com.br", "phone": { "international_dial_code": "55", "area_code": "11", "number": "1234567890" }, "legal_person": { "legal_name": "Empresa XPTO Limitada", "constitution_date": "2020-01-15" } } ``` Exemplo: Pessoa Jurídica (`fund_class`) ```json title='Request Body' { "name": "Empresa XPTO Ltda", "email": "contato@empresaxpto.com.br", "phone": { "international_dial_code": "55", "area_code": "11", "number": "1234567890" }, "legal_person": { "giin_number": "XXXXXX.XXXXX.XX.XXX", } } ``` ### Body params | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-------------------|----------|--------------------------------------------------------------------------------------|------------|-------------| | `name` | string | Nome (ou razão social) do investidor | 1 - 255 | Não | | `email` | string | E-mail de contato | 1 - 255 | Não | | `phone` | object | Objeto de **[Phone](#phone)** | - | Não | | `natural_person` | object | Objeto de **[Natural Person](#natural-person)** — obrigatório para pessoa física | - | Sim* | | `legal_person` | object | Objeto de **[Legal Person](#legal-person)** — obrigatório para pessoa jurídica | - | Sim* | \* É obrigatório enviar **exatamente um** entre `natural_person` ou `legal_person`, de acordo com o `person_type` do investidor. ### Natural Person {#natural-person} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |------------------------|--------|-----------------------------------------------------------------|------------|-------------| | `birthdate` | string | Data de nascimento (`YYYY-MM-DD`) | 10 | Sim | | `mother_name` | string | Nome completo da mãe | 1 - 255 | Sim | | `nationality` | string | Nacionalidade — código ISO de 3 letras (ex.: `BRA`) | 3 | Sim | | `place_of_birth` | object | Objeto de **[Place of Birth](#place-of-birth)** | - | Sim | | `marital_status` | string | Enumerador de **[Marital Status](#marital-status)** | - | Sim | | `profession` | string | Profissão | 1 - 255 | Sim | | `occupation` | string | Ocupação | 1 - 255 | Sim | | `gender` | string | Enumerador de **[Gender](#gender)** | - | Não | | `spouse` | object | Objeto de **[Spouse](#spouse)** | - | Não | | `occupation_company` | object | Objeto de **[Occupation Company](#occupation-company)** | - | Não | ### Gender {#gender} | Enumerador | Descrição | |------------|--------------| | `male` | Masculino | | `female` | Feminino | ### Marital Status {#marital-status} | Enumerador | Descrição | |---------------------------------------------|-------------------------------------------------| | `single` | Solteiro(a) | | `married` | Casado(a) | | `civil_union` | União estável | | `divorced` | Divorciado(a) | | `widowed` | Viúvo(a) | | `married_with_partial_community_property` | Casado(a) em comunhão parcial de bens | ### Place of Birth {#place-of-birth} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------|--------|----------------------------------------------------|------------|-------------| | `country` | string | Código ISO do país (3 letras, ex.: `BRA`) | 3 | Não | | `uf` | string | Estado (UF) | - | Não | | `city` | string | Cidade | - | Não | ### Spouse {#spouse} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-------------------|--------|----------------------------------------------------------------------|------------|-------------| | `name` | string | Nome completo do cônjuge | 1 - 255 | Sim | | `document_number` | string | CPF do cônjuge (`XXX.XXX.XXX-XX`) | 14 | Sim | ### Occupation Company {#occupation-company} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-------------------|--------|------------------------------------------------------------|------------|-------------| | `name` | string | Nome da empresa | 1 - 255 | Sim | | `document_number` | string | CNPJ da empresa (`XX.XXX.XXX/XXXX-XX`) | 18 | Sim | ### Legal Person {#legal-person} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |---------------------|--------|--------------------------------------------------------------------------|------------|-------------| | `legal_name` | string | Razão social da empresa | 1 - 255 | Não | | `constitution_date` | string | Data de constituição (`YYYY-MM-DD`) | 10 | Não | | `giin_number` | string | GIIN (`Global Intermediary Identification Number`), quando aplicável | 1 - 20 | Não | ### Phone {#phone} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |---------------------------|--------|------------------------|------------|-------------| | `international_dial_code` | string | Código internacional | 1 - 3 | Sim | | `area_code` | string | DDD | 2 | Sim | | `number` | string | Número de telefone | 8 - 9 | Sim | ### Response A análise cadastral atualizada é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**. --- --- # enviar_documento_assinado URL: /documentation/iaas/investidor/distribuicao_externa/enviar_documento_assinado --- # enviar_endereco URL: /documentation/iaas/investidor/distribuicao_externa/enviar_endereco --- # enviar_grupos_assinantes URL: /documentation/iaas/investidor/distribuicao_externa/enviar_grupos_assinantes --- # Enviar Documento do Investidor URL: /documentation/iaas/investidor/distribuicao_externa/enviar_investor_document --- ### Introdução Este recurso faz o upload de um documento que compõe a análise cadastral do investidor. Os documentos obrigatórios variam conforme o `person_type` e o `investor_sub_type` do investidor, bem como sua categoria (varejo, qualificado, profissional). :::warning Atenção - Este endpoint deve ser chamado **uma vez para cada documento** obrigatório - A análise cadastral precisa estar no status `pending_registry_data`. Em outro status, a chamada é recusada com `IVR000026` - Um mesmo `type` só aceita um envio bem-sucedido: veja [Reenvio e documento duplicado](#duplicado) ::: ### Input / Output Como ***input*** envie o conteúdo do arquivo em **base64**, o tipo do documento e a extensão. Como ***output*** será retornada a representação do documento criado, identificado por `investor_analysis_document_key`, acompanhada da representação completa da análise cadastral à qual ele pertence. ### Request ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document` MÉTODO `POST` STATUS `201` ### Query params | Campo | Tipo | Descrição | Obrigatório | |---------|---------|--------------------------------------------------------------------------------------------------------------------------|-------------| | `force` | boolean | Se `true`, força o envio mesmo quando há validação prévia falha. O documento entra obrigatoriamente em análise manual. | Não | ### Request body Exemplo: CNH (Pessoa Física) ```json title='Request Body' { "type": "cnh", "document_b64": "base64_encoded_document_content", "file_extension": "pdf", "document_data": { "document_type": "CNH", "issuer_entity": "DETRAN" } } ``` Exemplo: RG (frente e verso) ```json title='Request Body — Frente' { "type": "rg_front", "document_b64": "base64_encoded_document_content", "file_extension": "jpeg", "document_data": { "document_type": "RG", "issuer_entity": "SSP", "document_number": "20.932.206-8" } } ``` ```json title='Request Body — Verso' { "type": "rg_back", "document_b64": "base64_encoded_document_content", "file_extension": "jpeg" } ``` Exemplo: Cartão CNPJ (Pessoa Jurídica) ```json title='Request Body' { "type": "cnpj_card", "document_b64": "base64_encoded_document_content", "file_extension": "pdf" } ``` ### Body params | Campo | Tipo | Descrição | Caracteres | Obrigatório | |------------------|--------|--------------------------------------------------------------------|------------|-------------| | `type` | string | Enumerador de **[Document Type](#document-type)** | - | Sim | | `document_b64` | string | Conteúdo do arquivo codificado em base64 | - | Sim | | `file_extension` | string | Extensão do arquivo. Valores aceitos: `pdf`, `jpeg` | - | Sim | | `document_data` | object | Metadados livres do documento (ex.: número, órgão emissor) | - | Não | | `observation` | string | Observação livre sobre o documento | até 500 | Não | ### Document Type {#document-type} #### Identificação e comprovantes de pessoa física | Enumerador | Descrição | Extensões | |--------------------------------|------------------------------------------------------|----------------| | `cnh` | CNH | `pdf`, `jpeg` | | `rg_front` | RG — frente | `pdf`, `jpeg` | | `rg_back` | RG — verso | `pdf`, `jpeg` | | `passport` | Passaporte (identificação de estrangeiro) | `pdf`, `jpeg` | | `foreign_id` | Documento de identidade estrangeiro (ex.: RNE) | `pdf`, `jpeg` | | `proof_of_residence` | Comprovante de residência | `pdf`, `jpeg` | | `billing_statement` | Fatura / extrato | `pdf`, `jpeg` | #### Documentos societários de pessoa jurídica | Enumerador | Descrição | Extensões | |--------------------------------|------------------------------------------------------|----------------| | `cnpj_card` | Cartão CNPJ | `pdf`, `jpeg` | | `social_contract` | Contrato social | `pdf`, `jpeg` | | `company_statute` | Estatuto | `pdf`, `jpeg` | | `board_election_record` | Ata de eleição estatutária | `pdf`, `jpeg` | | `financial_statements` | Demonstrações financeiras | `pdf`, `jpeg` | | `organizational_chart` | Organograma societário | `pdf`, `jpeg` | #### Representação, qualificação e contratos | Enumerador | Descrição | Extensões | |--------------------------------|------------------------------------------------------|----------------| | `power_of_attorney` | Procuração | `pdf`, `jpeg` | | `investor_qualification_proof` | Comprovação de qualificação / enquadramento | `pdf`, `jpeg` | | `wallet_manager_contract` | Contrato de carteira administrada / intermediação | `pdf`, `jpeg` | | `extra_document` | Documento avulso, sem tipo específico | `pdf`, `jpeg` | #### Investidor não residente | Enumerador | Descrição | Extensões | |--------------------------------|------------------------------------------------------|----------------| | `custody_contract` | Contrato de custódia | `pdf`, `jpeg` | | `representation_contract` | Contrato de representação | `pdf`, `jpeg` | | `simplified_declaration` | Declaração simplificada | `pdf`, `jpeg` | | `final_departure_tax_return` | Declaração final de saída definitiva do país | `pdf`, `jpeg` | :::warning Tipos gerados pela QI Tech Os tipos `qualified_investor_term`, `professional_investor_term`, `natural_person_registry_form`, `legal_person_registry_form`, `investor_suitability_form` e `adhesion_term` aparecem na consulta do investidor, mas são **gerados pela QI Tech** para assinatura — não devem ser enviados por este endpoint. ::: ### Documentos Obrigatórios {#documentos-obrigatorios} As combinações abaixo são conjuntos alternativos: basta satisfazer **uma** das opções de cada lista. A validação roda no envio para análise (`submit`) e recusa com `IVR000029`, devolvendo na mensagem a matriz exata que faltou. #### Pessoa Física (`natural_person`) Uma das opções: | Opção | Documentos | |-------|---------------------------------------------------| | 1 | `cnh` **+** `proof_of_residence` | | 2 | `rg_front` **+** `rg_back` **+** `proof_of_residence` | #### Pessoa Jurídica (`legal_person` / `investor_sub_type: default`, `financial_institution`) Uma das opções — sempre **ao menos um** documento societário **e** as demonstrações financeiras: | Opção | Documentos | |-------|--------------------------------------------------------| | 1 | `board_election_record` **+** `financial_statements` | | 2 | `company_statute` **+** `financial_statements` | | 3 | `social_contract` **+** `financial_statements` | O documento societário exigido depende do tipo jurídico da empresa — daí as três opções. Não é possível enviar apenas `financial_statements`. :::warning Documentos obrigatórios Embora esses documentos sejam o mínimo para envio de uma análise, caso, por exemplo, somente o `company_statute` não seja suficiente para definir firmas e poderes do cotista, a análise pode ser recusada exigindo também o `board_election_record`. ::: #### Pessoa Jurídica — Fundo de Investimento (`investor_sub_type: fund_class`) **Nenhum documento é exigido.** Os dados do fundo são obtidos por enriquecimento na base da CVM, e a representação é feita pelos investor owners (administrador e gestora). ### Reenvio e documento duplicado {#duplicado} Um tipo de documento é considerado **satisfeito** assim que existe, para aquela análise, um documento daquele tipo com status `valid` ou `in_manual_analysis`. A partir daí, novos envios do mesmo tipo são recusados: ```json HTTP 409 { "title": "Already exists valid document for investor analysis.", "code": "IVR000023" } ``` Enquanto **todos** os documentos de um tipo estiverem `invalid`, novos envios daquele tipo continuam sendo aceitos — é assim que se corrige um arquivo ilegível. O tipo `extra_document` é a única exceção: aceita múltiplos envios sempre. ### Validação automática e `status` do documento {#validacao} Documentos dos tipos `cnh`, `rg_front`, `rg_back` e `proof_of_residence` passam por validação automática (OCR) e voltam com um dos status abaixo. Os demais tipos entram diretamente em `in_manual_analysis`. | Status | Significado | |---------------------|------------------------------------------------------------------------------| | `valid` | Validado automaticamente | | `in_manual_analysis`| Encaminhado para conferência humana | | `invalid` | Reprovado na validação automática — reenvie, ou use `force=true` | `force=true` pula o efeito da reprovação automática: o documento é registrado como `in_manual_analysis` e passa a satisfazer a exigência do tipo. :::info Sobre `investor_qualification_proof` Este documento **não integra a matriz de obrigatórios** e sua ausência nunca bloqueia o `submit`. Ele atua depois: se o `total_financial_applications` declarado estiver abaixo do piso da categoria informada — R$ 1.000.000 para `qualified`, R$ 10.000.000 para `professional` — ele é utilizado para a validação. Investidores `fund_class` são isentos dessa verificação. ::: ### Response ```json title='Response Body' { "investor_analysis_document_key": "UUID", "type": "cnh", "status": "in_manual_analysis", "observation": "Documento emitido em 2019, legibilidade reduzida no verso.", "data": { "type": "cnh", "file_extension": "pdf", "document_data": { "document_type": "CNH", "issuer_entity": "DETRAN" } }, "investor_analysis": { } } ``` | Campo | Tipo | Descrição | |----------------------------------|--------|------------------------------------------------------------------------------| | `investor_analysis_document_key` | string | Identificador do documento. É a chave usada nas demais rotas de documento | | `type` | string | Enumerador de **[Document Type](#document-type)** | | `status` | string | `valid`, `invalid` ou `in_manual_analysis` — veja [Validação automática](#validacao) | | `observation` | string | Observação enviada na requisição. `null` quando não informada | | `data` | object | Eco dos campos enviados, sem o conteúdo em base64 | | `investor_analysis` | object | Representação completa da análise cadastral — mesmo formato de **Busca informações de uma análise cadastral do investidor** | --- # enviar_patrimonio URL: /documentation/iaas/investidor/distribuicao_externa/enviar_patrimonio --- # Enviar Suitability URL: /documentation/iaas/investidor/distribuicao_externa/enviar_suitability --- ### Introdução Este recurso registra o **perfil de suitability** do investidor na análise cadastral. :::info Na distribuição externa você envia o perfil, não as respostas Diferente das demais superfícies, a integração de distribuição externa **não** responde ao questionário de suitability pela API — não há endpoint de formulário e não se enviam respostas numeradas. Você aplica o suitability no seu próprio canal e informa aqui apenas o **resultado**: `conservative`, `moderate` ou `bold`. ::: ### Request ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/suitability` MÉTODO `PUT` STATUS `202` ### Request body ```json title='Request Body' { "profile": "bold" } ``` ### Body params | Campo | Tipo | Descrição | Obrigatório | |-----------|--------|--------------------------------------------------|-------------| | `profile` | string | Enumerador de **[Profile](#profile)** | Sim | `profile` é o **único** campo aceito. Qualquer outra propriedade no corpo é recusada com `QIT000001`. ### Profile {#profile} | Enumerador | Descrição | |------------------|--------------------------------------------------------------------------------| | `conservative` | Conservador | | `moderate` | Moderado | | `bold` | Arrojado | | `not_applicable` | O suitability não se aplica a este investidor — ver **[Suitability não aplicável](#not-applicable)** | ### Response A resposta devolve os **dados cadastrais da análise** já atualizados, com o objeto `suitability` preenchido: ```json title='Response Body' { "natural_person": { "...": "..." }, "address": { "...": "..." }, "net_worth": { "...": "..." }, "suitability": { "profile": "bold" } } ``` --- ### Quando o envio é obrigatório | Investidor | Suitability | |---------------------------------------------------|--------------------------------------------------------------------| | **Pessoa física** | **Obrigatório** — sem ele o `submit` falha com `IVR000150` | | **Pessoa jurídica** enquadrada como `retail` | **Obrigatório** — sem ele o `submit` falha com `IVR000133` | | **Pessoa jurídica** `qualified` ou `professional` | **Opcional** — simplesmente não chame este endpoint | ### Suitability não aplicável {#not-applicable} Quando o suitability não se aplica ao investidor, envie `profile: "not_applicable"` neste mesmo endpoint: ```json title='Request Body' { "profile": "not_applicable" } ``` A análise passa a registrar `suitability: {"profile": "not_applicable"}`. :::info `not_applicable` é exclusivo da distribuição externa Este valor só é aceito de integrações de distribuição externa. Nas superfícies internas da QI Tech a declaração é recusada com `IVR000244`. ::: ### Pré-condições e erros | Código | HTTP | Quando ocorre | |-------------|------|----------------------------------------------------------------------------------------| | `IVR000018` | 400 | A análise não está em `pending_registry_data` | | `QIT000001` | 400 | `profile` ausente, fora do enumerador, ou corpo com propriedade extra | | `IVR000008` | 404 | Investidor não encontrado para as credenciais utilizadas | | `IVR000133` | 400 | *(no `submit`)* pessoa jurídica `retail` sem suitability | | `IVR000150` | 400 | *(no `submit`)* pessoa física sem suitability | O envio pode ser repetido enquanto a análise estiver em `pending_registry_data` — o último perfil enviado substitui o anterior. --- # consultar_feedback URL: /documentation/iaas/investidor/distribuicao_externa/feedback/consultar_feedback --- # enviar_mensagem_feedback URL: /documentation/iaas/investidor/distribuicao_externa/feedback/enviar_mensagem_feedback --- # listar_feedbacks URL: /documentation/iaas/investidor/distribuicao_externa/feedback/listar_feedbacks --- # Introdução URL: /documentation/iaas/investidor/distribuicao_externa/introducao Esta seção descreve o fluxo de cadastro de investidores no contexto de **Distribuição Externa** — quando os investidores são captados por um distribuidor externo e aportam em produtos da QI Tech por meio dele — através da integração de distribuição externa (`distributor-integration`). Embora o esqueleto do cadastro seja semelhante ao de um investidor padrão (dados cadastrais, contas bancárias, suitability, grupos de assinantes, partes relacionadas e investor owner quando aplicável), o vínculo com o distribuidor responsável é o que diferencia este fluxo dos demais. Além disso, existem duas formas diferentes de criar investidores distribuídos externamente: uma com identificação do investidor e outra **PCO** (Por Conta e Ordem). Para o caso de investidores PCO, é necessário apenas o `POST` de criação do investidor e ele já estará apto a investir em todo o sistema. :::warning Investor Owner O sistema de cadastro de investidor trabalha com o conceito de investor-owner, que nada mais é do que um investidor que é "dono" de outro investidor. Os casos de uso para isso são investidores cadastrados como carteira administrada e fundos de investimento. Portanto, para fundos de investimento e investidores de carteira administrada é necessário que os gestores/administrador estejam devidamente identificados e atualizados dentro do sistema. ::: ### Fluxo de Cadastro — Investidor Identificado 1. Criar Investidor criação inicial do investidor e abertura da primeira análise cadastral ↓ 2. Enviar Dados Cadastrais dados específicos da pessoa física ou jurídica ↓ 3. Enviar Endereço informações de endereço ↓ 4. Enviar Patrimônio informações de patrimônio e enquadramento ↓ 5. Enviar Contas Bancárias contas para movimentação ↓ 6. Enviar Suitability questionário de adequação ao perfil ↓ 7. Enviar Grupos de Assinantes definição de quem deve assinar os documentos ↓ 8. Enviar Documentos do Investidor upload de documentos obrigatórios ↓ 9. Criar Partes Relacionadas sócios, diretores, beneficiários finais ↓ 10. Enviar Documentos das Partes Relacionadas documentos de cada parte relacionada ↓ 11. Enviar para Análise submissão da análise cadastral para validação ↓ 12. Assinar Documentos assinatura dos documentos gerados após aprovação ### Fluxo de Cadastro — Por Conta e Ordem (PCO) 1. Criar Investidor criação inicial do investidor — não há esteira cadastral adicional para PCO Nas subseções a seguir veremos cada uma das etapas necessárias para concluir o cadastro de um investidor via Distribuição Externa e disparar a análise cadastral pela QI Tech. --- # criar_investor_owner URL: /documentation/iaas/investidor/distribuicao_externa/investor_owner/criar_investor_owner --- # enviar_documento_investor_owner URL: /documentation/iaas/investidor/distribuicao_externa/investor_owner/enviar_documento_investor_owner --- # atualizar_parte_relacionada URL: /documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_parte_relacionada --- # atualizar_status_parte_relacionada URL: /documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_status_parte_relacionada --- # criar_parte_relacionada URL: /documentation/iaas/investidor/distribuicao_externa/related_party/criar_parte_relacionada --- # enviar_documento_parte_relacionada URL: /documentation/iaas/investidor/distribuicao_externa/related_party/enviar_documento_parte_relacionada --- # Recuperando Informações da Posição do Investidor URL: /documentation/iaas/investidor/informacoes_posicao_investidor --- ### Request ENDPOINT /quota/investor/INVESTOR_KEY/investor_positions MÉTODO GET ### Query Params | Parâmetro | Descrição | |------------------------------|--------------------------------------------------------------------------------------| | `issuance_serie_key` | Chave única de identificação da série de emissão | | `only_above_zero` | Posições atuais com número de cotas maior que zero | | `fund_class_document_number` | CNPJ do Fundo | ### Responses STATUS 200 Caso 01: Investidor com Posição em somente uma série de COTA ÚNICA ```json { "data": [ { "investor_position_key":"UUID", "investor": { "distributor": { "distributor_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE DISTRIBUTOR NAME", "account_data": { "owner": { "name": "SAMPLE DISTRIBUTOR NAME", "document_number": "00.000.000/0000-00" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" } }, "investor_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE INVESTOR NAME", "person_type": "natural_person / legal_person / fund_class", "account_data": { "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, "investor_sub_type": "person / financial_institution" }, "total_net_worth": 0.00, "total_number_of_quotas": 0.00000000000000, "issuance_serie": { "name": "1", "cetip_code": "0000000UN1", "start_date": "YYYY-MM-DD", "maturity_date": "YYYY-MM-DD", "original_quota_value": 0.00000000000000, "remuneration_type": "residual", "investment_category": "fidc / multi_market", "condominum_type": "open_ended / close_ended", "tax_classification": "short_term / long_term", "investment_restriction_type": "just_professional", "issuance_serie_key": "UUID", "minimum_share_capital": 0.0, "accounting_date": "YYYY-MM-DD", "sub_class": { "name": "COTA ÚNICA", "sub_class_key": "UUID", "subordination_level": 0, "fund_class": { "name": "SAMPLE FUND CLASS NAME", "fund_class_key": "UUID", "document_number": "00.000.000/0000-00" } } } }, ], "limit": 50, "page": 0, "is_last_page": true } ``` Caso 02: Investidor com Posição em somente uma série de COTA SÊNIOR ```json { "data": [ { "investor_position_key":"UUID", "investor": { "distributor": { "distributor_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE DISTRIBUTOR NAME", "account_data": { "owner": { "name": "SAMPLE DISTRIBUTOR NAME", "document_number": "00.000.000/0000-00" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" } }, "investor_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE INVESTOR NAME", "person_type": "natural_person / legal_person / fund_class", "account_data": { "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, "investor_sub_type": "person / financial_institution" }, "total_net_worth": 0.00, "total_number_of_quotas": 0.00000000000000, "issuance_serie": { "name": "1", "cetip_code": "0000000SN1", "start_date": "YYYY-MM-DD", "maturity_date": "YYYY-MM-DD", "original_quota_value": 0.00000000000000, "remuneration_type": "yield_curve", "interest_rate_type": "post_fixed", "pre_fixed": { "calendar_base": "workdays / calendar_360 / calendar_365", "monthly_rate": 0.00000000000000 }, "post_fixed": { "calendar_base": "workdays / calendar_360 / calendar_365", "indexer": "di / ipca", "rate": 1, "lag": {"reference": "daily / monthly", "amount": 1}, }, "investment_category": "fidc / multi_market", "condominum_type": "open_ended / close_ended", "tax_classification": "short_term / long_term", "investment_restriction_type": "just_professional", "issuance_serie_key": "UUID", "minimum_share_capital": 0.0, "accounting_date": "YYYY-MM-DD", "sub_class": { "name": "COTA SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "name": "SAMPLE FUND CLASS NAME", "fund_class_key": "UUID", "document_number": "00.000.000/0000-00" } } } }, ], "limit": 50, "page": 0, "is_last_page": true } ``` Caso 03: Investidor com Posição em duas uma séries, uma COTA SÊNIOR e uma COTA SUBORDINADA ```json { "data":[ { "investor_position_key":"UUID", "investor":{ "distributor":{ "distributor_key":"UUID", "document_number":"00.000.000/0000-00", "name":"SAMPLE DISTRIBUTOR NAME", "account_data":{ "owner":{ "name":"SAMPLE DISTRIBUTOR NAME", "document_number":"00.000.000/0000-00" }, "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" } }, "investor_key":"UUID", "document_number":"00.000.000/0000-00", "name":"SAMPLE INVESTOR NAME", "person_type":"natural_person / legal_person / fund_class", "account_data":{ "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" }, "investor_sub_type":"person / financial_institution" }, "total_net_worth":0.00, "total_number_of_quotas":0.00000000000000, "issuance_serie":{ "name":"1", "cetip_code":"0000000SN1", "start_date":"YYYY-MM-DD", "maturity_date":"YYYY-MM-DD", "original_quota_value":0.00000000000000, "remuneration_type":"yield_curve", "interest_rate_type":"post_fixed", "pre_fixed":{ "calendar_base":"workdays / calendar_360 / calendar_365", "monthly_rate":0.00000000000000 }, "post_fixed":{ "calendar_base":"workdays / calendar_360 / calendar_365", "indexer":"di / ipca", "rate":1, "lag":{ "reference":"daily / monthly", "amount":1 } }, "investment_category":"fidc / multi_market", "condominum_type":"open_ended / close_ended", "tax_classification":"short_term / long_term", "investment_restriction_type":"just_professional", "issuance_serie_key":"UUID", "minimum_share_capital":0.0, "accounting_date":"YYYY-MM-DD", "sub_class":{ "name":"COTA SÊNIOR", "sub_class_key":"UUID", "subordination_level":1, "fund_class":{ "name":"SAMPLE FUND CLASS NAME", "fund_class_key":"UUID", "document_number":"00.000.000/0000-00" } } } }, { "investor_position_key":"UUID", "investor":{ "distributor":{ "distributor_key":"UUID", "document_number":"00.000.000/0000-00", "name":"SAMPLE DISTRIBUTOR NAME", "account_data":{ "owner":{ "name":"SAMPLE DISTRIBUTOR NAME", "document_number":"00.000.000/0000-00" }, "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" } }, "investor_key":"UUID", "document_number":"00.000.000/0000-00", "name":"SAMPLE INVESTOR NAME", "person_type":"natural_person / legal_person / fund_class", "account_data":{ "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" }, "investor_sub_type":"person / financial_institution" }, "total_net_worth":0.00, "total_number_of_quotas":0.00000000000000, "issuance_serie":{ "name":"1", "cetip_code":"0000000JR1", "start_date":"YYYY-MM-DD", "maturity_date":"YYYY-MM-DD", "original_quota_value":0.00000000000000, "remuneration_type":"residual", "investment_category":"fidc / multi_market", "condominum_type":"open_ended / close_ended", "tax_classification":"short_term / long_term", "investment_restriction_type":"just_professional", "issuance_serie_key":"UUID", "minimum_share_capital":0.0, "accounting_date":"YYYY-MM-DD", "sub_class":{ "name":"COTA SUBORDINADA", "sub_class_key":"UUID", "subordination_level":0, "fund_class":{ "name":"SAMPLE FUND CLASS NAME", "fund_class_key":"UUID", "document_number":"00.000.000/0000-00" } } } } ], "limit":50, "page":0, "is_last_page":true } ``` ### Response Fields | Campo | Tipo | Descrição | |---------------|--------|----------------------------------------------------------------| | `data` | array | Lista de objetos de **[Investor Position](#investor_position)**| | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última | ### Investor Position {#investor_position} | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------------| | `investor` | JSON | Objeto de **[Investor](#investor)** | | `total_net_worth` | float | Patrimônio Líquido da posição do investidor | | `total_number_of_quotas` | float | Número de cotas da posição do investidor | | `issuance_serie` | JSON | Objeto de **[Issuance Serie](#issuance_serie)** | | `investor_position_key` | JSON | Chave única de identificação da posição do investidor | ### Investor | Campo | Tipo | Descrição | Caracteres | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome do investidor | até 255 | | `investor_key` | string | Chave única de identificação do investidor | 36 | | `document_number` | string | CPF/CNPJ do investidor | 14 ou 18 | | `person_type` | string | Pessoa Física / Pessoa Jurídica / Classe de Fundo | até 50 | | `investor_sub_type` | string | Default / Instituição Financeira | até 50 | | `distributor` | JSON | Objeto de **[Distributor](#distributor)** | - | | `account_data` | JSON | Objeto de **[Account Data](#account_data)** | - | ### Distributor | Campo | Tipo | Descrição | Caracteres | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome do distribuidor | até 255 | | `distributor_key` | string | Chave única de identificação do distribuidor | - | | `document_number` | string | CPF/CNPJ do distribuidor | 14 ou 18 | | `account_data` | JSON | Objeto de **[Account Data](#account_data)** | - | ### Account Data {#account_data} | Campo | Tipo | Descrição | |------------------------------|----------|-----------------------------------------------------------------------------| | `account_digit` | string | Dígito da conta bancária | | `account_branch` | string | N° da agência da conta bancária | | `account_number` | string | N° da conta bancária | | `financial_institution_code` | string | Código da instituição financeira | | `financial_institution_ispb` | string | Identificador no Sistema de Pagamento Brasileiro da instituição financeira | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da série de emissão | até 255 | | `issuance_serie_key` | string | Chave única de identificação da série de emissão | 36 | | `cetip_code` | string | Código da série de emissão como ativo na CETIP | 10 | | `start_date` | string | Data de início da série de emissão | 10 | | `maturity_date` | string | Data de vencimento da série de emissão | 10 | | `original_quota_value` | float | Valor de cota original | - | | `remuneration_type` | string | Curva de rendimento / Residual | até 50 | | `investment_category` | string | FIDC / Multimercado | até 50 | | `condominum_type` | string | Aberto / Fechado | até 50 | | `tax_classification` | string | Curto prazo / Longo prazo | até 50 | | `investment_restriction_type` | string | Sem restrição / Qualificado / Profissional | até 50 | | `minimum_share_capital` | float | Valor mínimo para aplicação | - | | `accounting_date` | string | Data contábil da série de emissão | 10 | | `sub_class` | JSON | Objeto de **[Sub Class](#sub_class)** | - | ### Sub Class {#sub_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da sub classe | até 255 | | `sub_class_key` | string | Chave única de identificação da sub classe | 36 | | `subordination_level` | int | Nível de subordinação da sub classe | - | | `fund_class` | JSON | Objeto de **[Fund Class](#fund_class)** | - | ### Fund Class {#fund_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da classe de fundo | até 255 | | `fund_class_key` | string | Chave única de identificação da classe de fundo | 36 | | `document_number` | string | CNPJ da classe de fundo | - | --- # Layout CNAB 444 — Baixa URL: /documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa Layout do arquivo de **remessa de baixa** (liquidação) aceito pela QI CTVM. A estrutura é a mesma do [arquivo de cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444): 444 posições, header `0`, detalhes `1` e trailer `9`. O que muda é o **código de ocorrência**, o **valor pago** e a **data da liquidação**. :::tip Reaproveite a linha da cessão A forma mais segura de montar o arquivo de baixa é partir da linha enviada na cessão e alterar apenas três campos: ocorrência (109–110), valor pago (083–092) e data da liquidação (095–100). O identificador do ativo — nº de controle do participante — **precisa ser exatamente o mesmo** usado na cessão. ::: ## O que muda em relação ao arquivo de cessão | Posição | Campo | Na cessão | Na baixa | |---|---|---|---| | 083–092 | Valor pago | Zeros | **Valor efetivamente pago**, 2 decimais | | 095–100 | Data da liquidação | Zeros | **Data do pagamento**, `DDMMAA` | | 109–110 | Identificação da ocorrência | `01` | `04`, `14`, `75` ou `77` | | 150–150 | Identificação | Livre | Branco ou `0` | | 157–158 | 1ª instrução | Livre | `00` | | 159–159 | 2ª instrução | Livre | `0` | | 381–394 | CNPJ do cedente | Conferido o nome | **CNPJ conferido com dígito verificador** | Todos os demais campos seguem as mesmas regras de preenchimento, domínios e obrigatoriedades da [tabela do registro de detalhe da cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444#registro-detalhe). ## Ocorrências aceitas | Código | Significado | Efeito na carteira | Origem do recurso | |---|---|---|---| | `77` | **Baixa por depósito do sacado** | Liquidação integral do ativo (`asset_settlement`) | Sacado | | `14` | **Pagamento parcial** | Amortização do ativo (`asset_amortization`) | Sacado | | `75` | **Baixa por depósito do cedente** | Liquidação integral do ativo (`asset_settlement`) | Cedente | | `04` | **Pagamento a menor** | Liquidação do ativo (`asset_settlement`) | Sacado | :::caution Só essas quatro Qualquer outro código de ocorrência recusa o arquivo com a mensagem *"This field only allows one of this values: ['04', '14', '75', '77']"*. Ocorrências de aquisição (`01`, `80`, `81`, `84`) pertencem ao [arquivo de cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444). ::: ## Como o ativo é identificado | Tipo de ativo | Campo usado como identificador | Complemento | |---|---|---| | Duplicatas, CT-e e contratos | **Nº de controle do participante** (038–062) | — | | CCB e demais operações de crédito | **Nº do documento** (111–120), que corresponde ao número do contrato | A parcela é identificada pela **data de vencimento** (121–126) | :::caution O identificador precisa bater com o da cessão Se o número de controle do participante não corresponder a um ativo encarteirado no fundo, aquela liquidação falha individualmente no processamento — o lote continua, mas termina como `processed_with_failures`. ::: ## Exemplo comentado Baixa de dois títulos cedidos no exemplo de cessão: o primeiro liquidado integralmente pelo sacado, o segundo com pagamento parcial. ```text title="CB101001.REM" 01REMESSA01COBRANCA 00000011222333000181INDUSTRIA EXEMPLO S/A ...MX...000001 1...0CTRL000001...0000151000 101025 77000100001101025...COMERCIO EXEMPLO ALFA LTDA...000002 1...0CTRL000002...0000050000 101025 14000200002101025...COMERCIO EXEMPLO BETA LTDA...000003 9 ...000004 ``` | Linha | Leitura | |---|---| | Detalhe 1 | Ativo `CTRL000001` liquidado em 10/10/2025 — ocorrência `77`, valor pago R$ 1.510,00 (integral) | | Detalhe 2 | Ativo `CTRL000002` amortizado em 10/10/2025 — ocorrência `14`, valor pago R$ 500,00 (parcial) | ### Arquivos de exemplo | Arquivo | Espécie | O que traz | |---|---|---| | [Baixa de duplicatas](/downloads/modelos_arquivo/exemplo_baixa_duplicatas_cnab444.rem) | `01` | Uma liquidação integral (`77`) e um pagamento parcial (`14`), identificados pelo nº de controle do participante | | [Baixa de CCB](/downloads/modelos_arquivo/exemplo_baixa_ccb_cnab444.rem) | `41` | Duas parcelas identificadas pelo número do contrato e pela data de vencimento | ## Checklist antes de enviar - [ ] Todas as linhas com exatamente 444 caracteres - [ ] Ocorrência `04`, `14`, `75` ou `77` nas posições 109–110 - [ ] Valor pago preenchido nas posições 083–092, com 2 decimais e sem vírgula - [ ] Data da liquidação preenchida nas posições 095–100, no formato `DDMMAA` - [ ] Nº de controle do participante idêntico ao enviado na cessão - [ ] CNPJ do cedente (381–394) e CPF/CNPJ do sacado (221–234) com dígito verificador válido - [ ] 1ª instrução `00`, 2ª instrução `0` e identificação (150) em branco - [ ] Sem acentos, `Ç` ou caracteres especiais - [ ] Trailer fechando o arquivo com o sequencial da última linha --- # Baixa por Arquivo URL: /documentation/iaas/liquidacao_ativos/arquivo/inicio A baixa (liquidação) de ativos já encarteirados no fundo pode ser feita de duas formas: **enviando um arquivo** com todas as liquidações do dia, pelo portal do gestor/consultor, ou **inserindo liquidação a liquidação pela API**. As duas produzem o mesmo lote de pagamento e passam pela mesma conciliação. | | Envio por arquivo | Inserção pela API | |---|---|---| | **Como funciona** | Um arquivo com todas as liquidações | Uma requisição por liquidação | | **Formatos** | CNAB 444 e CSV | JSON | | **Disponível em** | Portal do gestor e do consultor | [API de Liquidação de Ativos](/documentation/iaas/liquidacao_ativos/inicio) | | **Indicado para** | Rotina diária de baixas em volume, a partir do retorno bancário | Baixas pontuais e integrações em tempo real | :::info Baixa por arquivo é um fluxo de tela Hoje o envio de arquivo de baixa está disponível no **portal**. Pela API de integração, a baixa é feita pelo fluxo de [lote de pagamento + liquidações](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao), sem arquivo. ::: ## Formatos aceitos | Formato | Extensão | Indicado para | Modelo | |---|---|---|---| | **CNAB 444** — duplicatas e CT-e | `.rem` · `.txt` | Quem já recebe retorno CNAB do banco cobrador. Layout em [Layout CNAB 444 — Baixa](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa) | [Exemplo](/downloads/modelos_arquivo/exemplo_baixa_duplicatas_cnab444.rem) | | **CNAB 444** — CCB e operações de crédito | `.rem` · `.txt` | Mesmo layout, com o ativo identificado pelo número do contrato | [Exemplo](/downloads/modelos_arquivo/exemplo_baixa_ccb_cnab444.rem) | | **CSV** | `.csv` | Planilha simples, com uma linha por liquidação, para qualquer tipo de ativo. Layout na seção [CSV de baixa](#csv-de-baixa) | [Exemplo](/downloads/modelos_arquivo/exemplo_baixa_liquidacoes.csv) | ## Passo a passo pela tela 1. Acesse **Ativos › Liquidações** e clique em **Novo lote por arquivo**. 2. Informe uma **descrição** para identificar o lote. 3. Selecione a **conta do fundo** que receberá o crédito das liquidações. 4. Arraste o arquivo (`.rem`, `.txt` ou `.csv`) e confirme. O portal cria o lote de pagamento, envia o arquivo e dispara a validação. A tela passa a mostrar o lote com o progresso — total de liquidações, processadas e falhas. ## O que acontece depois do envio | Etapa do lote | O que significa | |---|---| | Aguardando arquivo | Lote criado, arquivo ainda não enviado | | Validação em andamento | Arquivo recebido, sendo conferido linha a linha | | Criando o lote | Arquivo válido, lote de pagamento sendo criado | | Inserindo as liquidações | Cada linha está virando uma liquidação | | Concluído | Todas as liquidações processadas | | Concluído com falhas | Lote processado, mas com liquidações que falharam individualmente | | Recusado | Arquivo recusado na validação — nada foi processado | :::caution Validação é tudo ou nada Uma linha inválida recusa o arquivo inteiro. O portal informa o número da linha e a descrição do erro. Corrija e envie um lote novo, com um novo identificador. ::: Depois que o lote é encerrado e o pagamento confirmado, cada liquidação é conciliada individualmente na carteira do fundo — o mesmo comportamento descrito no [Fluxo de liquidação](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao). Uma liquidação pode falhar sozinha (por exemplo, ativo não encontrado na carteira) sem derrubar as demais. ## CSV de baixa Arquivo com cabeçalho na primeira linha, separado por `;` ou `,`. Limite de 850.000 linhas. ```csv title="exemplo_baixa_liquidacoes.csv" asset_type;total_value;settlement_type;external_id;installment_number;collection_origin_type duplicata_mercantil;1510.00;asset_settlement;CTRL000001;;borrower duplicata_mercantil;500.00;asset_amortization;CTRL000002;;borrower ccb;350.75;installment_settlement;CONTRATO-0001;3;borrower ``` ### Colunas | Coluna | Obrigatoriedade | Descrição | |---|---|---| | `asset_type` | obrigatória | Tipo do ativo. Ver [valores aceitos](#tipos-de-ativo-aceitos) | | `total_value` | obrigatória | Valor da liquidação. Aceita `.` ou `,` como separador decimal | | `settlement_type` | obrigatória | Tipo de liquidação. Ver [tipos de liquidação](#tipos-de-liquidação) | | `installment_number` | obrigatória (coluna) | Número da parcela. Preencha para ativos com parcelas (CCB); deixe vazio para duplicatas e contratos | | `external_id` **ou** `contract_number` | obrigatória | Identificador do ativo. Use `external_id` para duplicatas/contratos (o mesmo número de controle enviado na cessão) e `contract_number` para CCBs | | `collection_origin_type` | opcional | Quem pagou: `borrower` (sacado), `assignor` (cedente) ou `collection_agent` (agente de cobrança) | | `remaining_face_value` | opcional | Saldo remanescente do valor de face. Aceito **somente** com `settlement_type: installment_amortization` | :::caution A coluna de identificação define o lote inteiro Um mesmo arquivo usa `external_id` **ou** `contract_number` — não os dois. Se nenhuma das duas colunas existir, o arquivo é recusado. ::: ### Tipos de liquidação | Valor | Significado | |---|---| | `asset_settlement` | Liquidação integral do ativo | | `asset_amortization` | Pagamento parcial do ativo | | `installment_settlement` | Liquidação integral de uma parcela | | `installment_amortization` | Pagamento parcial de uma parcela | | `installment_partial_refund` / `asset_partial_refund` | Devolução parcial | | `installment_refund` / `asset_refund` | Devolução integral | | `fine_payment` / `installment_fine_payment` | Pagamento de multa | | `gloss` | Glosa | | `canceled` | Cancelamento | | `rco_revenue` | Receita de RCO | ### Tipos de ativo aceitos `ccb` · `cce` · `structured_ccb` · `structured_cce` · `structured_nce` · `structured_cci` · `duplicata_mercantil` · `duplicata_servicos` · `discounted_contract` · `cte` **[📄 Baixar CSV de exemplo](/downloads/modelos_arquivo/exemplo_baixa_liquidacoes.csv)** ## Erros mais comuns | Erro | Causa | |---|---| | `missing_fields: [...]` | Faltou uma coluna obrigatória no cabeçalho do CSV | | `invalid asset_type: ...` | Tipo de ativo fora da lista aceita | | `invalid settlement_type: ...` | Tipo de liquidação fora da lista aceita | | `invalid total_value: ...` | Valor com caractere inesperado ou vazio | | `invalid external_id` / `contract_number` | Identificador em branco | | `remaining_face_value is only allowed for settlement_type installment_amortization` | Saldo remanescente informado no tipo errado | | `unmapped cnab layout` | Arquivo CNAB com linhas fora de 444 ou 500 posições | --- # Inserção de Liquidações URL: /documentation/iaas/liquidacao_ativos/ativos/ Endpoint para inserir liquidações individuais em um lote de pagamento previamente criado. Cada liquidação representa um pagamento (total ou parcial) referente a um ativo da carteira do fundo — como liquidação de parcela, amortização, recompra ou pagamento de juros. :::info Liquidação vs Recompra Tanto a liquidação quanto a recompra de ativos são realizadas através deste endpoint. O campo `collection_origin_type` diferencia as duas operações: - `borrower` — para **liquidações** (pagamento realizado pelo sacado/devedor). - `assignor` — para **recompras** (pagamento realizado pelo cedente). ::: :::tip Onde estou no fluxo? Este é o **2º passo** do fluxo de liquidação. Antes deste passo, você deve ter [criado o lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `external_id` | string | O `external_id` do lote de pagamento onde a liquidação será inserida. | ```json title="Request Body" { "asset_type": "ccb", "total_value": 130.50, "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "settlement_type": "installment_settlement", "contract_number": "0123456789/ABC", "installment_number": 1, "collection_date": "2025-01-01", "collection_origin_type": "borrower" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_type` | string | obrigatório | Tipo de ativo. Veja [enumeradores de `asset_type`](#enumeradores-de-asset_type). Máximo de 255 caracteres. | | `total_value` | number | obrigatório | Valor total do pagamento (com duas casas decimais). | | `external_id` | string | obrigatório | Chave única de identificação desta liquidação no sistema do parceiro integrador. Máximo de 50 caracteres. | | `settlement_type` | string | obrigatório | Tipo de liquidação. Veja [enumeradores de `settlement_type`](#enumeradores-de-settlement_type). Máximo de 50 caracteres. | | `collection_origin_type` | string | obrigatório | Determina se a operação é uma liquidação (`borrower`) ou uma recompra (`assignor`). Veja [enumeradores de `collection_origin_type`](#enumeradores-de-collection_origin_type). | | `contract_number` | string | opcional | Número do contrato referente ao ativo. Máximo de 50 caracteres. | | `asset_external_id` | string | opcional | Chave única de identificação do ativo no sistema, fornecida na cessão. Máximo de 50 caracteres. | | `asset_key` | string | opcional | Chave interna do ativo na QI Tech (UUID, 36 caracteres). | | `if_code` | string | opcional | Código de instrumento financeiro (B3). Máximo de 36 caracteres. | | `participant_control_number` | string | opcional | Número de controle do participante fornecido na cessão. Máximo de 50 caracteres. | | `installment_number` | integer | opcional | Número da parcela a ser paga. Obrigatório para tipos de liquidação por parcela. | | `installment_maturity_date` | string | opcional | Data de vencimento da parcela no formato `YYYY-MM-DD`. | | `installment_external_id` | string | opcional | Identificador externo da parcela. Máximo de 50 caracteres. | | `collection_date` | string | opcional | Data de pagamento no formato `YYYY-MM-DD`. Campo destinado para controle do integrador. | :::caution Atenção Os campos `asset_external_id`, `contract_number` e `asset_key` são formas alternativas de identificar o ativo no sistema. Informe **apenas um** deles — não envie múltiplos simultaneamente. ::: :::info Diferença entre external_id O campo `external_id` no corpo da requisição se refere ao identificador da **liquidação**. O campo `external_id` na URL se refere ao identificador do **lote de pagamento**. ::: #### Enumeradores de `asset_type` | Valor | Descrição | |---|---| | `ccb` | Cédula de Crédito Bancário | | `cce` | Cédula de Crédito à Exportação | | `structured_ccb` | Cédula de Crédito Bancário Estruturada | | `structured_cce` | Cédula de Crédito à Exportação Estruturada | | `structured_nce` | Nota de Crédito à Exportação Estruturada | | `structured_cci` | Cédula de Crédito Imobiliário Estruturada | | `duplicata_mercantil` | Duplicata Mercantil | | `duplicata_servicos` | Duplicata de Serviços | | `discounted_contract` | Contrato | #### Enumeradores de `settlement_type` | Valor | Descrição | |---|---| | `asset_settlement` | Liquidação total do ativo. | | `asset_amortization` | Amortização do ativo (carência). | | `fine_payment` | Pagamento de juros ou mora do ativo. | | `installment_settlement` | Liquidação de parcela. Obrigatório informar `installment_number`. | | `installment_amortization` | Amortização de parcela. Obrigatório informar `installment_number`. | | `installment_fine_payment` | Pagamento de juros ou mora de parcela. Obrigatório informar `installment_number`. | | `gloss` | Glosa de parcela. Obrigatório informar `installment_number`. | #### Enumeradores de `collection_origin_type` | Valor | Descrição | |---|---| | `borrower` | Liquidação — pagamento realizado pelo sacado/devedor. | | `assignor` | Recompra — pagamento realizado pelo cedente. | ## Response STATUS 201 ```json title="Response Body" { "status": "validated", "total_value": 130.50, "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "type": "installment_settlement", "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890", "installment_number": 1, "settlement_result": 0.0, "total_number_of_units": 1, "collection_origin_type": "borrower", "assets": [ { "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361", "number_of_units": 1, "present_value": 1250.00, "installment_face_value": 130.50 } ] } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Status da liquidação. Após inserção bem-sucedida, retorna `validated`. | | `total_value` | number | Valor total do pagamento. | | `external_id` | string | Chave externa da liquidação fornecida pelo parceiro. | | `type` | string | Tipo de liquidação. | | `settlement_key` | string | Identificador único da liquidação gerado pela QI Tech (UUID). | | `installment_number` | integer | Número da parcela. Presente quando aplicável. | | `settlement_result` | number | Resultado da liquidação. Presente quando calculado. | | `total_number_of_units` | integer | Quantidade total de unidades de ativo afetadas pela liquidação. | | `collection_origin_type` | string | Tipo de origem da cobrança (`borrower` ou `assignor`). Presente quando informado na requisição. | | `assets` | array | Lista de ativos afetados pela liquidação. Veja [Atributos de `assets`](#atributos-de-assets). | #### Atributos de `assets` | Campo | Tipo | Descrição | |---|---|---| | `asset_key` | string | Identificador único do ativo (UUID). | | `number_of_units` | integer | Quantidade de unidades do ativo. | | `present_value` | number | Valor presente do ativo em reais. | | `installment_face_value` | number | Valor de face da parcela. Presente quando aplicável. | | `installment_post_maturity_interest_value` | number | Valor de juros pós-vencimento da parcela. Presente quando aplicável. | | `installment_delay_interest_value` | number | Valor de juros de atraso da parcela. Presente quando aplicável. | | `installment_delay_fine_value` | number | Valor de multa de atraso da parcela. Presente quando aplicável. | ## Possíveis erros STATUS 404 **Lote de pagamento não encontrado** O `external_id` do lote informado na URL não corresponde a nenhum lote cadastrado para este fundo. Verifique se o identificador está correto. ```json { "title": "Payment batch not found", "description": "The Payment Batch with external_id {payment_batch_external_id} was not found", "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado", "code": "SET000010" } ``` STATUS 400 **Liquidação com external_id duplicado** Já existe uma liquidação cadastrada com o `external_id` informado neste lote. Cada liquidação deve ter um identificador único. Gere um novo `external_id` e tente novamente. ```json { "title": "Already Exists Settlement With External Id", "description": "The settlement with external_id {settlement_external_id} in payment batch with external id {payment_batch_external_id} already exists", "translation": "a liquidação com identificador {settlement_external_id} no lote de identificador {payment_batch_external_id} já existe", "code": "SET000013" } ``` ## Próximos passos Após inserir todas as liquidações desejadas, o fluxo continua com: 1. **[Encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado. --- # Remoção de Liquidações URL: /documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes Endpoint para descartar uma liquidação individual previamente inserida em um lote de pagamento. Somente liquidações em lotes que ainda não foram encerrados podem ser removidas. :::tip Quando utilizar Use este endpoint quando precisar remover uma liquidação incorreta ou indesejada antes de [encerrar o lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento). Após o encerramento do lote, não é possível remover liquidações individuais. ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `external_id` | string | O `external_id` do lote de pagamento. | | `settlement_external_id` | string | O `external_id` da liquidação que será descartada. | ```json title="Request Body" { "status": "discarded" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `status` | string | obrigatório | Novo status da liquidação. Para descartar, envie `discarded`. | ## Response STATUS 200 ```json title="Response Body" { "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "status": "discarded" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | Chave externa da liquidação fornecida pelo parceiro. | | `status` | string | Novo status da liquidação: `discarded`. | ## Possíveis erros STATUS 404 **Liquidação não encontrada** O `settlement_external_id` informado na URL não corresponde a nenhuma liquidação cadastrada neste lote. Verifique se os identificadores do lote e da liquidação estão corretos. ```json { "title": "Settlement not found", "description": "The Settlement with external_id {external_id} was not found", "translation": "A Liquidação com identificador externo {external_id} não foi encontrada", "code": "SET000011" } ``` STATUS 400 **Status inválido** O valor informado no campo `status` não é válido. Para remoção, utilize apenas `discarded`. ```json { "title": "Invalid status", "description": "The status given: {status} is not suported.", "translation": "O status: {status} não possui suporte.", "code": "SET000026" } ``` STATUS 400 **Lote já encerrado** O lote de pagamento já foi encerrado e não permite mais alterações nas liquidações. Não é possível remover liquidações de lotes que já passaram do status `pending_settlements_insertion`. ```json { "title": "Payment Batch Status mismatch", "description": "Payment batch of key: {payment_batch_key} with status: {current} was expected to be: {expected}", "translation": "O lote de pagamento com chave: {payment_batch_key} e com status: {current} não passou, era esperado que fosse: {expected}", "code": "SET000016" } ``` STATUS 400 **Status da liquidação incompatível** A liquidação está em um status que não permite ser descartada. Apenas liquidações com status `validated` podem ser removidas. ```json { "title": "Settlement type mismatch", "description": "The settlement given has the status: {current_status} and was expected: {expected_status}", "translation": "A liquidação com status: {current_status} era esperado ter: {expected_status}", "code": "SET000024" } ``` --- # Webhooks de Liquidação URL: /documentation/iaas/liquidacao_ativos/ativos/webhook Ao longo do processamento das liquidações, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status de cada liquidação individual. Todos os webhooks possuem o tipo `settlement.settlement_status_change` e identificam a liquidação pelo `settlement_external_id` fornecido na criação. :::info Configuração de webhooks Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. ::: ## Fluxo de status da liquidação Cada liquidação inserida no lote fica em `validated` e só é processada depois que o lote de pagamento atinge `paid`. A partir daí ela chega a um dos dois status finais que geram webhook: `settled` ou `discarded`. O status `validated` **não** dispara notificação — ele é o resultado da própria chamada de [inserção da liquidação](/documentation/iaas/liquidacao_ativos/ativos). ![Fluxo de status da liquidação, destacando os dois status finais que geram webhook](/img/diagrams/iaas-liquidacao-ativos-ativos-webhook.svg) _Como ler o diagrama: **contorno tracejado** = status sem webhook · **verde** = conclusão com sucesso · **vermelho** = encerramento sem movimentação financeira._ ## Estrutura do webhook Todos os webhooks de liquidação seguem a mesma estrutura base: | Campo | Tipo | Descrição | |---|---|---| | `webhook_type` | string | Sempre `settlement.settlement_status_change`. | | `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. | | `data` | array | Lista com os dados do evento. Veja tabela abaixo. | #### Atributos de cada objeto em `data` Os campos condicionais são ecoados diretamente do que foi enviado na criação da liquidação. O payload varia conforme o `settlement_type` e o método de identificação do ativo utilizado. **Campos sempre presentes:** | Campo | Tipo | Descrição | |---|---|---| | `payment_batch_external_id` | string | O `external_id` do lote de pagamento. | | `settlement_external_id` | string | O `external_id` da liquidação. | | `settlement_status` | string | Novo status da liquidação. | | `settlement_type` | string | Tipo de liquidação. | | `total_value` | number | Valor total da liquidação em reais. | | `fund_class_document_number` | string | CNPJ do fundo associado. | | `fund_class_key` | string | Chave do fundo na QI Tech (UUID). | | `asset_key` | string | Chave interna do ativo na QI Tech (UUID). | **Identificação do ativo — apenas um dos campos abaixo estará presente, conforme o que foi informado na criação:** | Campo | Tipo | Descrição | |---|---|---| | `contract_number` | string | Número do contrato. Presente se informado na criação. | | `asset_external_id` | string | `external_id` do ativo no sistema do parceiro. Presente se informado na criação. | **Demais campos ecoados quando informados:** | Campo | Tipo | Descrição | |---|---|---| | `if_code` | string | Código de instrumento financeiro (B3). Presente se informado na criação da liquidação. | | `participant_control_number` | string | Número de controle do participante. Presente se informado na criação da liquidação. | | `source_document_number` | string | CPF ou CNPJ da contraparte financeira. Presente se informado na [criação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). | **Campos de parcela — presentes apenas para tipos de liquidação por parcela (`installment_settlement`, `installment_amortization`, `installment_fine_payment`, `gloss`):** | Campo | Tipo | Descrição | |---|---|---| | `installment_number` | integer | Número da parcela. | | `installment_maturity_date` | string | Data de vencimento da parcela no formato `YYYY-MM-DD`. Presente quando informado na criação. | | `installment_external_id` | string | `external_id` da parcela. Presente quando informado na criação. | ```json title="Estrutura padrão do webhook" { "data": [ { "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "settlement_status": "STATUS", "settlement_type": "installment_settlement", "total_value": 130.50, "fund_class_document_number": "60.910.091/0001-24", "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f", "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c", "contract_number": "0032226586/NNT", "installment_number": 3 } ], "webhook_type": "settlement.settlement_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ## Eventos por status ### Liquidação Concluída STATUS settled Enviado quando a liquidação é processada com sucesso e o valor foi devidamente conciliado na carteira do fundo. Este é o status final de uma liquidação bem-sucedida — a partir desse momento, a movimentação financeira está efetivada. ```json title="Webhook Body" { "data": [ { "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "settlement_status": "settled", "settlement_type": "installment_settlement", "total_value": 130.50, "fund_class_document_number": "60.910.091/0001-24", "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f", "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c", "contract_number": "0032226586/NNT", "installment_number": 3 } ], "webhook_type": "settlement.settlement_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Liquidação Descartada STATUS discarded Enviado quando a liquidação é descartada do fluxo de processamento. Liquidações descartadas não geram movimentação financeira. Existem três situações que causam esse status: 1. **Remoção manual antes do encerramento do lote** — o parceiro integrador remove a liquidação via endpoint de [remoção de liquidações](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes) enquanto o lote ainda está aberto. 2. **Descarte interno após revisão** — a equipe QI Tech descarta uma liquidação que estava em revisão manual (`pending_validation`), por exemplo por inconsistência nos dados. 3. **Rejeição** — durante o processamento, a carteira do fundo retorna uma rejeição definitiva para uma liquidação com valor zero. Nesses casos, o sistema determina que reprocessar a liquidação produziria o mesmo resultado e a descarta. ```json title="Webhook Body" { "data": [ { "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "settlement_status": "discarded", "settlement_type": "installment_settlement", "total_value": 130.50, "fund_class_document_number": "60.910.091/0001-24", "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f", "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c", "contract_number": "0032226586/NNT", "installment_number": 3 } ], "webhook_type": "settlement.settlement_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- --- # Fluxo de liquidação de ativos URL: /documentation/iaas/liquidacao_ativos/fluxo_liquidacao Esta página oferece uma visão holística do fluxo de liquidação de ativos já encarteirados no fundo: desde a criação do lote de pagamento até a conclusão das liquidações e a atualização da carteira. Acompanhe a evolução dos **status do lote**, dos **status de cada liquidação** e dos **webhooks** em cada etapa. :::tip Como usar este fluxograma Passe o mouse sobre cada etapa para ver os detalhes do endpoint e acessar a documentação completa. As trilhas coloridas mostram simultaneamente o que acontece com o lote, com cada liquidação e quais webhooks você receberá após o processamento. ::: {` .cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px} .cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600} .cf-legend-dot{width:12px;height:12px;border-radius:3px} .cf-step{position:relative;margin-bottom:4px} .cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)} .cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))} .cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)} .cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap} .cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0} .cf-num-int{background:#3b82f6} .cf-num-qi{background:#8b5cf6} .cf-num-ges{background:#d946ef} .cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)} .cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto} .cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb} .cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed} .cf-actor-ges{background:rgba(217,70,239,0.12);color:#c026d3} .cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px} .cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px} .cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid} .cf-track-lote{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)} .cf-track-ativo{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)} .cf-track-wh{background:rgba(245,158,11,0.1);color:#b45309;border-color:rgba(245,158,11,0.25)} .cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)} .cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em} .cf-new{font-weight:700} .cf-unchanged{opacity:0.5} .cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px} .cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)} .cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap} .cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem} .cf-method-post{background:#f97316;color:#fff} .cf-method-put{background:#3b82f6;color:#fff} .cf-method-get{background:#22c55e;color:#fff} .cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px} .cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none} .cf-link:hover{text-decoration:underline} .cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap} .cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed} .cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)} .cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)} .cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px} .cf-branch-label-ok{color:#16a34a} .cf-branch-label-err{color:#dc2626} html[data-theme='dark'] .cf-track-lote{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)} html[data-theme='dark'] .cf-track-ativo{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)} html[data-theme='dark'] .cf-track-wh{background:rgba(245,158,11,0.15);color:#fbbf24;border-color:rgba(245,158,11,0.3)} html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)} html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)} html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)} html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa} html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa} html[data-theme='dark'] .cf-actor-ges{background:rgba(217,70,239,0.2);color:#e879f9} `} ## Legenda Agente Integrador QI Tech (automático) Status do Lote Status da Liquidação Webhook ## Fluxograma 1 Criação do lote de pagamento Agente Integrador Cria um lote com identificador único ( external_id ) por fundo, contendo conta de crédito opcional e demais metadados. Lote: pending_settlements_insertion POST /settlement/fund_class/{fund_class_key}/payment_batch O lote fica pronto para receber liquidações. Ver documentação completa → 2 Inserção das liquidações Agente Integrador Insere cada liquidação (parcela, amortização, liquidação total, etc.) no lote. Repita para todas as operações desejadas. Lote: pending_settlements_insertion Liquidação: validated POST /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement Cada liquidação recebe status validated após inserção bem-sucedida. Não há webhook neste momento; os webhooks são enviados após o encerramento e o processamento. Ver documentação completa → 3 Remoção de liquidação (opcional) Agente Integrador Antes de encerrar o lote, você pode descartar uma liquidação inserida por engano. Somente liquidações em status validated podem ser removidas. Lote: pending_settlements_insertion Liquidação: validated Removeu uma liquidação discarded A liquidação deixa de entrar no processamento. Não aplicável Pule este passo se não precisar remover nenhuma liquidação. PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id} Corpo: {"status": "discarded"} . Após o encerramento do lote não é possível remover liquidações individuais. Ver documentação completa → 4 Encerramento do lote Agente Integrador Sinaliza que todas as liquidações foram inseridas (e ajustadas) e que o processamento pode iniciar — ou descarta o lote inteiro. Lote: pending_payment / discarded Liquidação: validated (ou discarded) Processar lote pending_payment É necessário ter ao menos uma liquidação no lote. Descartar lote discarded Nenhuma liquidação será processada. Fluxo encerrado. PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id} Envie {"batch_status": "pending_payment"} para encerrar e processar, ou {"batch_status": "discarded"} para descartar o lote. Ver documentação completa → 5 Pagamento do lote QI Tech A QI Tech confirma o pagamento do lote. Em seguida as liquidações individuais são processadas e os webhooks de liquidação são disparados. Lote: paid Webhook: payment_batch_status_change Webhook settlement.payment_batch_status_change com status paid . Opcionalmente, use a listagem de lotes para acompanhar o lote. GET /settlement/fund_class/{fund_class_key}/payment_batches Consulta opcional para acompanhar o lote por status ou data de referência. Webhooks do lote → 6 Conclusão das liquidações QI Tech Cada liquidação processada com sucesso é conciliada na carteira do fundo. Este é o status final de sucesso por liquidação. Liquidação: settled Webhook: settlement_status_change Webhook settlement.settlement_status_change com settlement_status settled para cada liquidação concluída (após o pagamento do lote). Ver documentação de webhooks de liquidação → --- ## Resumo de webhooks A tabela abaixo consolida todos os webhooks da API de liquidação: | # | Tipo do webhook | Campo de status | Valor | Momento no fluxo | Ação esperada | |---|---|---|---|---|---| | 1 | `settlement.payment_batch_status_change` | `status` | `paid` | Após confirmação do pagamento do lote (passo 5) | A partir deste evento, as liquidações são processadas e os webhooks por liquidação passam a ser enviados. | | 2 | `settlement.settlement_status_change` | `settlement_status` | `settled` | Por liquidação, após processamento bem-sucedido (passo 6) | Liquidação concluída e conciliada na carteira. | | 3 | `settlement.settlement_status_change` | `settlement_status` | `discarded` | Por liquidação, quando descartada por remoção manual, descarte interno ou rejeição permanente da carteira | Liquidação não será processada. Nenhuma movimentação financeira é gerada. | | 4 | `settlement.payment_batch_status_change` | `status` | `completed` | Após todas as liquidações do lote atingirem status final (`settled` ou `discarded`) | O ciclo do lote está encerrado. Todas as liquidações foram processadas. | | 5 | `settlement.payment_batch_status_change` | `status` | `discarded` | Quando o lote é descartado (por solicitação do parceiro, descarte automático ou falha no cancelamento em conta caixa) | Nenhuma liquidação do lote será processada. | :::info Payload do webhook de liquidação O payload do webhook `settlement_status_change` varia conforme os dados enviados na criação da liquidação: - **Identificação do ativo:** apenas um dos campos `contract_number` ou `asset_external_id` estará presente, conforme o método de identificação usado na criação. Nunca os dois simultaneamente. - **Campos de parcela** (`installment_number`, `installment_maturity_date`, `installment_external_id`): presentes somente para tipos de liquidação por parcela — `installment_settlement`, `installment_amortization`, `installment_fine_payment` e `gloss`. Ausentes em tipos de ativo total (`asset_settlement`, `asset_amortization`, `fine_payment`). Para a estrutura completa dos payloads, consulte [Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) e [Webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook). ::: --- # Liquidação de Ativos URL: /documentation/iaas/liquidacao_ativos/inicio Esta seção documenta as APIs que viabilizam o processo de Liquidação de Ativos para Fundos de Investimento administrados pela QI CTVM. Por meio dessas APIs, é possível registrar pagamentos de parcelas, amortizações, recompras e demais eventos de liquidação dos ativos que compõem a carteira do fundo. :::tip Contexto A liquidação de ativos descrita nesta seção aplica-se exclusivamente a direitos creditórios (CCBs, duplicatas, contratos, etc.) já encarteirados no fundo. Letras do Tesouro, Debêntures e outros ativos de renda fixa não se aplicam a esse fluxo. ::: :::info Pré-requisitos - Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de Homologação (Sandbox) e Produção. - Você precisará da `fund_class_key` (chave do fundo), que compõe a URL base de todos os endpoints desta API: ``` /settlement/fund_class/{fund_class_key} ``` ::: ## Como enviar as baixas | Caminho | Como funciona | Onde | |---|---|---| | **Pela API, liquidação a liquidação** | Criação do lote de pagamento, uma requisição por liquidação e encerramento do lote. É o fluxo detalhado nesta seção | API de integração | | **Por arquivo** | Um único arquivo com todas as liquidações: **CNAB 444** ou **CSV** | Portal do gestor/consultor | :::tip Baixa por arquivo Se você já recebe o retorno CNAB do banco cobrador, pode enviá-lo direto. Veja [Baixa por Arquivo](/documentation/iaas/liquidacao_ativos/arquivo/inicio) e o [Layout CNAB 444 — Baixa](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa). ::: ## Fluxo de liquidação O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação. :::tip Fluxo completo Para todas as transições de status, os payloads dos webhooks e os caminhos de exceção, consulte o [Fluxo de liquidação de ativos](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao). ::: ## Passo a passo ### 1. Criação do Lote de Pagamento Crie um lote de pagamento informando um identificador único (`external_id`). O lote será o contêiner para todas as liquidações que serão processadas em conjunto. **[Acessar documentação da criação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)** ### 2. Inserção das Liquidações Adicione as liquidações ao lote criado. Cada liquidação deve ser inserida individualmente, informando o tipo de ativo, o valor, o tipo de liquidação e os identificadores necessários. **[Acessar documentação da inserção de liquidações](/documentation/iaas/liquidacao_ativos/ativos)** Enquanto o lote não é encerrado, uma liquidação inserida por engano pode ser removida. **[Acessar documentação da remoção de liquidações](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes)** ### 3. Encerramento do Lote Após inserir todas as liquidações, encerre o lote para que o processamento interno seja iniciado. A conciliação de caixa e a atualização do portfólio de ativos serão realizadas automaticamente. No mesmo endpoint é possível, alternativamente, descartar o lote inteiro — nesse caso nenhuma liquidação é processada. **[Acessar documentação do encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** ### 4. Acompanhamento via Webhooks Acompanhe o progresso através dos webhooks: - **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificações sobre o status do lote. - **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificações sobre o status individual de cada liquidação. :::info Processamento automático O procedimento de conciliação de caixa e a atualização do portfólio de ativos é feito de forma automática pela API após o encerramento do lote. ::: --- # Criação do Lote de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/criacao Este é o **primeiro passo** do fluxo de liquidação de ativos. A criação do lote de pagamento reserva um agrupamento onde as liquidações que serão processadas serão inseridas nas etapas seguintes. :::info Pré-requisitos Antes de criar um lote, você precisa ter em mãos a `fund_class_key` — chave única do fundo no qual os ativos serão liquidados. Essa chave compõe o endpoint utilizado em toda esta API: ``` /settlement/fund_class/{fund_class_key} ``` Para mais detalhes sobre o fluxo completo, consulte a [página de introdução](/documentation/iaas/liquidacao_ativos/inicio). ::: :::caution Atenção Cada lote deve possuir um `external_id` **único** por fundo. O sistema não permitirá a criação de dois lotes com o mesmo identificador. ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch MÉTODO POST ```json title="Request Body" { "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "description": "PAGAMENTOS - ABC - 2025-01-01", "account": { "account_number": "123456", "account_digit": "0", "account_branch": "0001", "financial_institution_code": "329" } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `external_id` | string | obrigatório | Chave única de identificação deste lote no sistema do parceiro integrador. Máximo de 50 caracteres. | | `description` | string | opcional | Descrição do lote de liquidação. Máximo de 255 caracteres. | | `account` | object | opcional | Dados da conta onde a liquidação será creditada. Quando não informado, a liquidação será gerada na conta principal do fundo. Veja [Atributos de `account`](#atributos-de-account). | | `account_key` | string | opcional | Chave da conta onde a liquidação será creditada (UUID, 36 caracteres). Alternativa ao campo `account`. | | `reference_date` | string | opcional | Data de referência da liquidação no formato `YYYY-MM-DD`. | | `end_to_end_id` | string | opcional | Identificador end-to-end do PIX da contraparte financeira da liquidação. Máximo de 32 caracteres. | | `source_document_number` | string | opcional | CPF ou CNPJ da contraparte financeira da liquidação, com pontuação (ex: `12.345.678/0001-90` ou `123.456.789-00`). | :::caution Atenção Os campos `account` e `account_key` não devem ser passados simultaneamente. Caso nenhum dos dois seja informado, a liquidação será gerada na conta principal do fundo. As informações da conta devem ser referentes a uma conta pertencente ao fundo. ::: #### Atributos de `account` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `account_number` | string | obrigatório | Número da conta. Máximo de 20 caracteres. | | `account_digit` | string | obrigatório | Dígito da conta. 1 caractere. | | `account_branch` | string | obrigatório | Agência da conta. Máximo de 4 caracteres. | | `financial_institution_code` | string | obrigatório | Código da instituição financeira. Máximo de 20 caracteres. | ## Response STATUS 201 ```json title="Response Body" { "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "description": "PAGAMENTOS - ABC - 2025-01-01", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "EXEMPLO CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" }, "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b", "status": "pending_settlements_insertion", "reference_date": "2025-01-01", "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | A mesma chave externa fornecida na requisição. | | `description` | string | Descrição do lote. | | `fund_class` | object | Dados do fundo associado ao lote. Veja [Atributos de `fund_class`](#atributos-de-fund_class). | | `payment_batch_key` | string | Identificador único do lote gerado pela QI Tech (UUID). | | `status` | string | Status inicial do lote. Sempre retorna `pending_settlements_insertion`, indicando que o lote está pronto para receber liquidações. | | `reference_date` | string | Data de referência da liquidação no formato `YYYY-MM-DD`. | | `account_key` | string | Chave da conta associada ao lote (UUID). | #### Atributos de `fund_class` | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome do fundo. | | `manager` | object | Dados do gestor do fundo. Veja [Atributos de `manager`](#atributos-de-manager). | | `fund_class_key` | string | Chave única do fundo (UUID). | | `document_number` | string | CNPJ do fundo. | #### Atributos de `manager` | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome do gestor. | | `manager_key` | string | Chave única do gestor (UUID). | | `document_number` | string | CNPJ do gestor. | ## Possíveis erros STATUS 404 **Fundo não encontrado** A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado. Verifique se a chave está correta. ```json { "title": "Fund Class not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "A Classe de Fundo com chave {fund_class_key} nao foi encontrado.", "code": "SET000005" } ``` STATUS 409 **External ID duplicado** Já existe um lote cadastrado com o `external_id` informado. Cada lote deve ter um identificador único. Gere um novo `external_id` e tente novamente. ```json { "title": "Payment batch external id already exists", "description": "The Payment Batch with external id {payment_batch_external_id} already exists", "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} ja existe", "code": "SET000009" } ``` STATUS 400 **Data contábil divergente** O lote está sendo criado em uma data diferente da data contábil vigente do fundo. Verifique a data contábil do fundo e tente novamente. ```json { "title": "Bad Request", "description": "Payment batch is being created in {accounting_date}, while fund is in {fund_class_accounting_date}", "translation": "Payment batch esta sendo criado em {accounting_date}, fundo esta em {fund_class_accounting_date}", "code": "SET000044" } ``` STATUS 404 **Conta não encontrada** A `account_key` informada não corresponde a nenhuma conta cadastrada. Verifique se a chave está correta e se a conta pertence ao fundo. ```json { "title": "Account not found", "description": "The account with key ({account_key}) was not found.", "translation": "A conta com chave({account_key}) não foi encontrada.", "code": "SET000009" } ``` ## Próximos passos Após criar o lote, o fluxo continua com: 1. **[Inserção das liquidações](/documentation/iaas/liquidacao_ativos/ativos)** — adicione as liquidações (pagamentos de parcelas, amortizações, etc.) ao lote. 2. **[Encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado. --- # Encerrar Inserção no Lote de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento Após inserir todas as liquidações desejadas no lote, utilize este endpoint para sinalizar que a inserção foi concluída e o processamento pode ser iniciado. Também é possível descartar o lote por completo. :::tip Onde estou no fluxo? Este é o **3º passo** do fluxo de liquidação. Antes deste passo, você deve ter: 1. [Criado o lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) 2. [Inserido as liquidações](/documentation/iaas/liquidacao_ativos/ativos) ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `external_id` | string | O `external_id` informado na criação do lote. | ```json title="Request Body" { "batch_status": "pending_payment" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `batch_status` | string | obrigatório | Status para o qual o lote será atualizado. Veja [enumeradores](#enumeradores-de-batch_status) abaixo. | #### Enumeradores de `batch_status` | Valor | Descrição | |---|---| | `pending_payment` | Encerra a inserção e inicia o processamento do lote. | | `discarded` | Descarta o lote inteiro. Nenhuma liquidação será processada. | ## Response STATUS 200 ```json title="Response Body" { "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "pending_payment" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | Chave externa do lote fornecida pelo parceiro. | | `status` | string | Novo status do lote. | ## Possíveis erros STATUS 404 **Lote não encontrado** O `external_id` informado na URL não corresponde a nenhum lote cadastrado para este fundo. Verifique se o identificador está correto. ```json { "title": "Payment batch not found", "description": "The Payment Batch with external_id {payment_batch_external_id} was not found", "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado", "code": "SET000010" } ``` STATUS 400 **Status inválido** O valor informado no campo `batch_status` não é válido. Utilize apenas `pending_payment` ou `discarded`. ```json { "title": "Invalid status", "description": "The status given: {status} is not suported.", "translation": "O status: {status} não possui suporte.", "code": "SET000026" } ``` STATUS 400 **Lote sem liquidações** Você tentou encerrar o lote, mas ele ainda não possui nenhuma liquidação inserida. É necessário [inserir pelo menos uma liquidação](/documentation/iaas/liquidacao_ativos/ativos) antes de encerrar o lote. ```json { "title": "Payment Batch with no settlement", "description": "Payment batch of external_id: {payment_batch_external_id} have no settlements to be settled", "translation": "O lote de pagamento com identificador: {payment_batch_external_id} não possui liquidações", "code": "SET000017" } ``` ## Próximos passos Após encerrar o lote, o processamento é iniciado automaticamente. Acompanhe o resultado através dos webhooks: 1. **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificação quando o lote for pago. 2. **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificação individual de cada liquidação processada. --- # Listagem de Lotes de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/listagem Endpoint de consulta paginada que retorna os lotes de pagamento de uma determinada classe de fundo. Utilize os filtros disponíveis para buscar lotes por status ou data de referência. ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batches MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `status` | string | opcional | Filtra por um status específico do lote. Consulte os [enumeradores de status](#enumeradores-de-status-do-lote). | | `reference_date` | string | opcional | Filtra por data de referência no formato `YYYY-MM-DD`. | | `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `10`. Máximo: `50`. | ```python title="Exemplo de chamada" GET /settlement/fund_class/{fund_class_key}/payment_batches?status=completed&reference_date=2025-01-01&page=0&limit=10 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "description": "LOTE DE LIQUIDAÇÃO 08/08", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "EXEMPLO CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "a3ecf74b-d280-4d3c-aefd-cb223dbf0451", "document_number": "60.910.091/0001-24" }, "payment_batch_key": "50859e88-544c-4c79-a7aa-d373d90aa571", "status": "completed", "external_id": "5910209c-9cb5-4569-9069-f2dbc8060434", "reference_date": "2025-08-08", "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "total_value": 143.18 } ], "limit": 10, "page": 0, "is_last_page": false } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de objetos de lote de pagamento. Veja tabela abaixo. | | `page` | integer | Número da página atual. | | `limit` | integer | Quantidade de registros por página. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada lote (objetos dentro de `data`) | Campo | Tipo | Descrição | |---|---|---| | `description` | string | Descrição do lote. | | `fund_class` | object | Dados do fundo associado ao lote. Consulte os [atributos de `fund_class`](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao#atributos-de-fund_class) na página de Criação. | | `payment_batch_key` | string | Identificador único do lote (UUID). | | `status` | string | Status atual do lote. Consulte os [enumeradores de status](#enumeradores-de-status-do-lote) abaixo. | | `external_id` | string | Chave externa fornecida pelo parceiro. | | `reference_date` | string | Data de referência no formato `YYYY-MM-DD`. | | `account_key` | string | Chave da conta associada ao lote (UUID). | | `total_value` | number | Valor total das liquidações do lote em reais. Pode não estar presente caso o lote ainda não tenha sido processado. | ## Enumeradores de status do lote | Status | Descrição | |---|---| | `pending_settlements_insertion` | Lote criado, aguardando inserção de liquidações. | | `pending_payment` | Lote encerrado, aguardando processamento do pagamento. | | `paid` | Pagamento do lote realizado. | | `completed` | Processamento do lote finalizado com sucesso. | | `discarded` | Lote descartado. | --- # Webhooks do Lote de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/webhook Ao longo do fluxo de liquidação, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status do lote de pagamento. Todos os webhooks possuem o tipo `settlement.payment_batch_status_change` e identificam o lote pelo `external_id` fornecido na criação. :::info Configuração de webhooks Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. ::: ## Fluxo de status do lote O lote passa pelos status abaixo até o encerramento. Três deles geram webhook: `paid`, `completed` e `discarded`. Os dois primeiros — `pending_settlements_insertion` e `pending_payment` — são resultado das suas próprias chamadas de [criação](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) e [encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) do lote e **não** disparam notificação. ![Fluxo de status do lote de pagamento, destacando os três status que geram webhook](/img/diagrams/iaas-liquidacao-ativos-lote-pagamento-webhook.svg) _Como ler o diagrama: **contorno tracejado** = status sem webhook · **azul** = webhook de andamento · **verde** = encerramento com sucesso · **vermelho** = encerramento sem processamento._ ## Estrutura do webhook Todos os webhooks do lote de pagamento seguem a mesma estrutura: | Campo | Tipo | Descrição | |---|---|---| | `webhook_type` | string | Sempre `settlement.payment_batch_status_change`. | | `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. | | `data` | object | Dados do evento. Veja tabela abaixo. | #### Atributos de `data` | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | Identificador do lote. Veja [Como o `external_id` é formado](#como-o-external_id-é-formado). | | `status` | string | Novo status do lote. | | `fund_class_document_number` | string | CNPJ do fundo associado ao lote. | | `fund_class_key` | string | Chave do fundo na QI Tech (UUID). | | `payment_batch_key` | string | Identificador único do lote gerado pela QI Tech (UUID). | | `reference_date` | string | Data de referência do lote, no formato `AAAA-MM-DD`. | | `total_value` | number | Valor total do lote em reais. Presente depois que o total é apurado, no encerramento do lote — ou seja, nos webhooks de `paid` e `completed`. | | `description` | string | Descrição do lote. Presente quando o lote possui descrição. | ```json title="Estrutura padrão do webhook" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "STATUS", "fund_class_document_number": "60.910.091/0001-24", "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f", "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a", "reference_date": "2024-04-23", "total_value": 4520.75, "description": "PAGAMENTOS - ABC - 2024-04-23" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ## Como o `external_id` é formado O `external_id` é a chave de correlação entre o lote na QI CTVM e o seu próprio controle. A origem do valor depende de como o lote foi criado: | Origem do lote | Valor do `external_id` | |---|---| | [Criação via API](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) | Exatamente o `external_id` que você informou no corpo da requisição. | | Arquivo de liquidação enviado via SFTP | O nome do arquivo **sem a extensão**. | :::info Lotes criados a partir de um arquivo de liquidação O webhook **não traz um campo com o nome do arquivo**. Para correlacionar o evento ao arquivo que você enviou, compare o `external_id` com o nome do arquivo sem a extensão: | Arquivo enviado | `external_id` do lote | |---|---| | `liquidacoes_20260811_001.REM` | `liquidacoes_20260811_001` | | `CNAB_BAIXAS_liquidacoes_20260811_001.REM` | `liquidacoes_20260811_001` | Como mostra a segunda linha, o prefixo `CNAB_BAIXAS_`, quando presente, também é removido. O arquivo de retorno com as inconsistências encontradas no processamento, quando gerado, segue a mesma convenção — `retorno_liquidacoes_20260811_001.csv`. ::: --- ## Eventos por status ### Lote Pago STATUS paid Enviado quando o pagamento do lote é confirmado pela QI Tech. A partir desse momento, as liquidações individuais são processadas em sequência e os respectivos [webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook) são enviados conforme cada uma for concluída. ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "paid", "fund_class_document_number": "60.910.091/0001-24", "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f", "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a", "reference_date": "2024-04-23", "total_value": 4520.75, "description": "PAGAMENTOS - ABC - 2024-04-23" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Lote Concluído STATUS completed Enviado quando todas as liquidações do lote atingiram um status final (`settled` ou `discarded`). Este é o status terminal do lote após a conclusão bem-sucedida do ciclo de liquidação. Ao receber este evento, o parceiro integrador pode considerar o lote integralmente processado. Para identificar a que lote o evento se refere, use o `external_id` — veja [Como o `external_id` é formado](#como-o-external_id-é-formado). ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "completed", "fund_class_document_number": "60.910.091/0001-24", "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f", "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a", "reference_date": "2024-04-23", "total_value": 4520.75, "description": "PAGAMENTOS - ABC - 2024-04-23" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Lote Descartado STATUS discarded Enviado quando o lote é descartado. Isso pode ocorrer por solicitação explícita do parceiro integrador no [encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento), por descarte automático de lotes em aberto pela QI Tech, ou após cancelamento junto à conta caixa. Nenhuma liquidação associada ao lote será processada após este status. Quando o lote é descartado antes do encerramento, o valor total não chega a ser apurado e o campo `total_value` não vem no payload. ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "discarded", "fund_class_document_number": "60.910.091/0001-24", "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f", "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a", "reference_date": "2024-04-23", "description": "PAGAMENTOS - ABC - 2024-04-23" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- # Layout CNAB 444 — Cessão URL: /documentation/iaas/negociacao_recebiveis/arquivo/cnab444 Layout do arquivo de **remessa de cessão** aceito pela QI CTVM. É o padrão CNAB 444 de cobrança usado no mercado de FIDCs, com as regras de preenchimento e os domínios efetivamente validados pela nossa plataforma. :::info Onde este arquivo é usado Este é o arquivo enviado no fluxo descrito em [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), pelo portal do gestor ou do consultor. Para dar baixa em ativos já encarteirados, o layout é outro: veja [Layout CNAB 444 — Baixa](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa). ::: ## Estrutura do arquivo | Registro | Identificação (posição 1) | Quantidade | |---|---|---| | **Header** | `0` | 1, sempre a primeira linha | | **Detalhe** | `1` | 1 por título cedido | | **Trailer** | `9` | 1, sempre a última linha | Todas as linhas têm **exatamente 444 caracteres**, sem contar a quebra de linha. ## Nome do arquivo `CBDDMMxx.REM` ou `CBDDMMxx.TXT` — `CB` fixo, `DD` dia, `MM` mês e `xx` sequencial alfanumérico. Exemplos: `CB120801.REM`, `CB1208AE.TXT`. Aceitamos qualquer nome, desde que a extensão seja `.rem` ou `.txt`. A convenção acima é apenas a recomendada. ## Regras gerais de preenchimento | Regra | Detalhe | |---|---| | **Tamanho fixo** | Toda linha tem 444 posições. Linhas mais curtas ou mais longas recusam o arquivo. | | **Campos numéricos** | Alinhados à direita, completados com **zeros** à esquerda. | | **Campos alfanuméricos** | Alinhados à esquerda, completados com **espaços** à direita. | | **Valores monetários** | Sempre com 2 casas decimais, **sem** vírgula ou ponto. `R$ 2.470,56` → `000000000247056`. | | **Datas** | Formato `DDMMAA`. Ex.: 12/08/2025 → `120825`. | | **Caracteres permitidos** | Apenas `A-Z`, `a-z`, `0-9`, espaço e `. / - , ( ) &`. **Não use acentos nem `Ç`** — troque `SÃO PAULO` por `SAO PAULO` e `AÇOS` por `ACOS`. | | **Codificação** | UTF-8 ou ASCII. Quebra de linha `CRLF` ou `LF`. | :::caution O erro mais comum Acento ou cedilha em nome de sacado, razão social ou endereço. A mensagem devolvida aponta a posição exata e o nome do campo — por exemplo: *"Caracteres inválidos encontrados na posição 240, dentro do campo 'Nome do sacado'."* ::: ## Registro Header | # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito | |---|---|---|---|---|---| | 1 | 001–001 | 1 | Identificação do registro | Sim | `0` | | 2 | 002–002 | 1 | Identificação do arquivo remessa | Sim | `1` | | 3 | 003–009 | 7 | Literal remessa | Sim | `REMESSA` | | 4 | 010–011 | 2 | Código do serviço | Sim | `01` | | 5 | 012–026 | 15 | Literal do serviço | Sim | `COBRANCA` + 7 espaços | | 6 | 027–046 | 20 | **Código do originador** | Sim | Código fornecido pela QI CTVM no cadastro, alinhado à direita com zeros | | 7 | 047–076 | 30 | Nome do originador | Sim | Razão social | | 8 | 077–079 | 3 | Número do banco | Não | Livre | | 9 | 080–094 | 15 | Nome do banco | Não | Livre | | 10 | 095–100 | 6 | Data de gravação do arquivo | Sim | `DDMMAA` | | 11 | 101–108 | 8 | Brancos | Sim | 8 espaços | | 12 | 109–110 | 2 | Identificação do sistema | Sim | `MX` | | 13 | 111–117 | 7 | Nº sequencial do arquivo | Não | Livre | | 14 | 118–120 | 3 | Banco do cedente | Não | Dígitos ou brancos | | 15 | 121–125 | 5 | Agência do cedente | Não | Dígitos ou brancos | | 16 | 126–126 | 1 | DV da agência | Não | Livre | | 17 | 127–138 | 12 | Conta corrente do cedente | Não | Dígitos ou brancos | | 18 | 139–139 | 1 | DV da conta corrente | Não | Livre | | 19 | 140–377 | 238 | Brancos | Sim | Exatamente 238 espaços | | 20 | 378–391 | 14 | **CPF/CNPJ do cedente original** | Não | CNPJ com 14 caracteres, CPF com 11 dígitos + 3 espaços, ou 14 espaços | | 21 | 392–438 | 47 | Brancos | Sim | Exatamente 47 espaços | | 22 | 439–444 | 6 | Nº sequencial do registro | Sim | `000001` | :::info Código do originador (posições 27–46) É o identificador do originador **cadastrado na configuração de cessão**. Um código não cadastrado ou vinculado a outra configuração recusa o arquivo com a mensagem *"O código do originador '…' não foi encontrado"*. Solicite o código no processo de homologação do cedente. ::: :::tip Cedente original (posições 378–391) Campo específico da QI CTVM, que **não existe no layout de mercado**. Use quando o título já tiver passado por um endosso anterior e você precisar registrar o CNPJ/CPF do cedente de origem. Se não se aplica, deixe em branco. ::: ## Registro Detalhe Um registro por título. Os campos em **negrito** são os que alimentam o ativo criado na carteira do fundo. | # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito | |---|---|---|---|---|---| | 1 | 001–001 | 1 | Identificação do registro | Sim | `1` | | 2 | 002–007 | 6 | Data de carência | Não | `DDMMAA` ou zeros | | 3 | 008–008 | 1 | Tipo de juros | Não | `0` sem correção, `1` juros fixo, `2` CDI, `3` IPCA-15, `4` IPCA, `5` IGPM, ou branco | | 4 | 009–010 | 2 | Brancos | Sim | 2 espaços | | 5 | 011–020 | 10 | Taxa de juros | Não | Dígitos (7 decimais) ou 10 espaços | | 6 | 021–022 | 2 | Coobrigação | Sim | `01` com coobrigação, `02` sem coobrigação | | 7 | 023–024 | 2 | Característica especial (SCR) | Não | Anexo 8 do SCR 3040, `00` ou brancos | | 8 | 025–028 | 4 | Modalidade da operação (SCR) | Condicional | Anexo 3 do SCR 3040. Pode ficar em branco para duplicatas e CTe | | 9 | 029–030 | 2 | Natureza da operação (SCR) | Não | Anexo 2 do SCR 3040, `00` ou brancos | | 10 | 031–034 | 4 | Origem do recurso (SCR) | Não | Anexo 4 do SCR 3040, `0000` ou brancos | | 11 | 035–036 | 2 | Classe de risco (SCR) | Não | `AA`, `A`…`H`, `HH`, `01`, `00` ou brancos | | 12 | 037–037 | 1 | Zeros | Não | `0` ou branco | | 13 | 038–062 | 25 | **Nº de controle do participante** | Sim | Identificador único do ativo no seu sistema. Alinhado à esquerda | | 14 | 063–065 | 3 | Número do banco | Não | Dígitos ou brancos | | 15 | 066–070 | 5 | Zeros | Não | Zeros ou brancos | | 16 | 071–081 | 11 | Identificação do título no banco | Não | Dígitos ou 11 espaços | | 17 | 082–082 | 1 | Dígito do nosso número | Não | Livre | | 18 | 083–092 | 10 | Valor pago | Não | **Zeros** na cessão | | 19 | 093–093 | 1 | Condição de emissão da papeleta | Não | Branco | | 20 | 094–094 | 1 | Papeleta para débito automático | Não | Branco | | 21 | 095–100 | 6 | Data da liquidação | Não | **Zeros** na cessão | | 22 | 101–104 | 4 | Identificação da operação do banco | Não | 4 espaços ou `0000` | | 23 | 105–105 | 1 | Indicador de rateio de crédito | Não | Branco ou `0` | | 24 | 106–106 | 1 | Endereçamento de aviso de débito | Não | Branco | | 25 | 107–108 | 2 | Brancos | Não | 2 espaços ou `00` | | 26 | 109–110 | 2 | **Identificação da ocorrência** | Sim | Ver [Ocorrências](#ocorrências-aceitas) | | 27 | 111–120 | 10 | **Nº do documento** | Sim | Número do título/duplicata. Exatamente 10 caracteres | | 28 | 121–126 | 6 | **Data de vencimento** | Sim | `DDMMAA` | | 29 | 127–139 | 13 | **Valor de face** | Sim | Valor nominal do título, 2 decimais | | 30 | 140–142 | 3 | Banco encarregado da cobrança | Não | Dígitos, zeros ou brancos | | 31 | 143–147 | 5 | Agência depositária | Não | 5 dígitos, `00000` ou brancos | | 32 | 148–149 | 2 | **Espécie de título** | Sim | Ver [Espécies](#especies-de-titulo) | | 33 | 150–150 | 1 | Identificação | Não | Branco | | 34 | 151–156 | 6 | **Data de emissão do título** | Sim | `DDMMAA` | | 35 | 157–158 | 2 | 1ª instrução | Não | `00` | | 36 | 159–159 | 1 | 2ª instrução | Não | `0` | | 37 | 160–161 | 2 | Tipo de pessoa do cedente | Sim | `01` pessoa física, `02` pessoa jurídica | | 38 | 162–173 | 12 | Juros/mora por dia de atraso | Não | 12 caracteres alfanuméricos **ou** 12 espaços | | 39 | 174–192 | 19 | Nº do termo de cessão | Não | Livre ou brancos | | 40 | 193–205 | 13 | **Valor presente (aquisição)** | Sim | Valor pago pelo fundo por este título, 2 decimais | | 41 | 206–218 | 13 | Valor do abatimento | Não | Zeros ou dígitos | | 42 | 219–220 | 2 | **Tipo de inscrição do sacado** | Sim | `01` pessoa física (CPF), `02` pessoa jurídica (CNPJ) | | 43 | 221–234 | 14 | **Nº de inscrição do sacado** | Sim | CNPJ com 14 posições; CPF com 11 dígitos alinhados à direita. **O dígito verificador é conferido** | | 44 | 235–274 | 40 | **Nome do sacado** | Sim | Não pode ficar em branco | | 45 | 275–314 | 40 | **Endereço do sacado** | Sim | Não pode ficar em branco. Ex.: `AV EXEMPLO, 100` | | 46 | 315–323 | 9 | **Nº da nota fiscal** | Condicional | Obrigatório para duplicatas e CTe | | 47 | 324–326 | 3 | Série da nota fiscal | Não | 3 alfanuméricos ou 3 espaços. Em branco assume `1` | | 48 | 327–334 | 8 | **CEP do sacado** | Sim | 8 dígitos, sem hífen | | 49 | 335–394 | 60 | **Cedente** | Sim | `335–380` nome do cedente (46) · `381–394` CNPJ do cedente (14) | | 50 | 395–438 | 44 | **Chave da NF-e** | Condicional | 44 dígitos. Obrigatória para `duplicata_mercantil` e `cte` nas ocorrências `01`, `81` e `84` | | 51 | 439–444 | 6 | Nº sequencial do registro | Sim | Sequencial da linha, começando em `000002` | ## Registro Trailer | # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito | |---|---|---|---|---|---| | 1 | 001–001 | 1 | Identificação do registro | Sim | `9` | | 2 | 002–438 | 437 | Brancos | Sim | Exatamente 437 espaços | | 3 | 439–444 | 6 | Nº sequencial do registro | Sim | Número da última linha do arquivo | ## Ocorrências aceitas A ocorrência (posições 109–110) diz o que fazer com o título. | Código | Significado | Quando usar | |---|---|---| | `01` | **Remessa — aquisição de títulos** | Padrão da cessão. É o que você usa em quase todos os casos | | `80` | Remessa — aquisição com liquidação para a consultoria | Tratada como aquisição | | `81` | Entrada por troca de títulos, com liquidação para a consultoria | Contrapartida de recompra dentro do mesmo arquivo | | `84` | Entrada por troca de títulos, com liquidação para o cedente | Contrapartida de recompra dentro do mesmo arquivo | | `72` | **Recompra parcial** | Só em lote de substituição. Gera amortização do ativo recomprado | | `74` | **Baixa por recompra** | Só em lote de substituição. Gera liquidação do ativo recomprado | :::caution Recompra exige lote de substituição As ocorrências `72` e `74` só são aceitas quando a configuração de cessão é do tipo substituição e o lote foi criado com `assignment_type: substitution_assignment`. Em um lote comum, o arquivo é recusado com a mensagem *"A ocorrência de recompra '…' só é permitida em configurações de cessão de recompra (substituição)"*. ::: :::info Ocorrências de baixa não entram aqui Códigos como `04`, `14`, `75` e `77` pertencem ao arquivo de **baixa** e são processados por outro fluxo. Enviá-los em um arquivo de cessão faz o ativo falhar no processamento, mesmo que a linha passe na validação de estrutura. Veja [Baixa por Arquivo](/documentation/iaas/liquidacao_ativos/arquivo/inicio). ::: ## Espécies de título {#especies-de-titulo} A espécie, nas posições 148–149, define como o título é lido. **Três códigos são processados no fluxo de cessão por arquivo:** | Código | Espécie | Tipo de ativo | Nota fiscal | Chave da NF-e | Exemplo | |---|---|---|---|---|---| | `01` | Duplicata | `duplicata_mercantil` | Obrigatória | Obrigatória | [Baixar](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) | | `14` | Duplicata de serviço | `duplicata_servicos` | Obrigatória | Dispensada | [Baixar](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) | | `53` | CT-e | `cte` | Obrigatória | Obrigatória | [Baixar](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) | :::caution Outros códigos passam na estrutura, mas não são processados O layout CNAB 444 prevê dezenas de espécies — `02` nota promissória, `41` CCB digital, `51` cheque, `60` contrato, entre outras. Elas passam pela validação estrutural do arquivo, mas **não são convertidas em ativo no fluxo de cessão por arquivo**: o processamento devolve *"Asset type … was not expected"* e o lote não avança. Se o seu produto usa uma dessas espécies, ceda pela API de integração, ativo a ativo, ou confirme o caminho com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) antes de montar o arquivo. ::: :::info A espécie precisa combinar com a configuração de cessão Uma configuração de `duplicata_mercantil` espera espécie `01`. Enviar uma espécie incompatível com o tipo de ativo da configuração faz o ativo ser recusado na inserção. ::: ## De-para: do CNAB para o ativo na carteira Cada linha de detalhe vira um ativo idêntico ao que seria criado pelo endpoint de [Criação de Ativo — Duplicata](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata). | Posição no CNAB | Campo do ativo (API) | |---|---| | 038–062 Nº de controle do participante | `discounted_credit_right.external_id` e `participant_control_number` — é por ele que o ativo é referenciado depois, inclusive na baixa | | 111–120 Nº do documento | `discounted_credit_right.order_number` — identifica a linha dentro do arquivo e **não pode se repetir** | | 121–126 Data de vencimento | `discounted_credit_right.maturity_date` | | 127–139 Valor de face | `discounted_credit_right.face_value` | | 148–149 Espécie de título | `asset_type` | | 151–156 Data de emissão | `discounted_credit_right.invoice.issue_date` | | 193–205 Valor presente | `total_purchase_value` | | 219–220 / 221–234 Sacado | `borrower.person_type` e `borrower.document_number` | | 235–274 Nome do sacado | `borrower.name` | | 275–314 Endereço do sacado | `borrower.address.street` e `number` | | 315–323 / 324–326 Nota fiscal | `invoice.number` e `invoice.serie` | | 327–334 CEP | `borrower.address.postal_code` | | 395–438 Chave da NF-e | `invoice.access_key` | | Header 027–046 Código do originador | `originator_document_number` | | Header 378–391 Cedente original | `original_assignor_document_number` | :::tip Endereço do sacado O logradouro e o número são extraídos do texto das posições 275–314, e o restante do endereço (bairro, cidade e UF) é completado automaticamente a partir do CEP. Escreva no formato `LOGRADOURO, NUMERO`. ::: ## Exemplo comentado Cessão de duas duplicatas mercantis do cedente `11.222.333/0001-81`, com vencimento em 10/10/2025. ```text title="CB120801.REM" 01REMESSA01COBRANCA 00000011222333000181INDUSTRIA EXEMPLO S/A ...MX...000001 1...0CTRL000001...01000100001101025000000015100...0245678912000155COMERCIO EXEMPLO ALFA LTDA...000002 1...0CTRL000002...01000200002101025000000015200...0278912345000109COMERCIO EXEMPLO BETA LTDA...000003 9 ...000004 ``` | Linha | Leitura | |---|---| | Header | Originador `00000011222333000181`, arquivo gerado em 12/08/2025, sistema `MX` | | Detalhe 1 | Ativo `CTRL000001`, documento `0001000010`, vence em 10/10/2025, face R$ 1.510,00, aquisição R$ 1.480,00, sacado CNPJ `45.678.912/0001-55` | | Detalhe 2 | Ativo `CTRL000002`, documento `0002000020`, face R$ 1.520,00, aquisição R$ 1.490,00, sacado CNPJ `78.912.345/0001-09` | | Trailer | Fecha o arquivo com o sequencial `000004` | ### Arquivos de exemplo | Arquivo | Espécie | O que traz | |---|---|---| | [Duplicata mercantil](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) | `01` | Dois títulos com nota fiscal e chave da NF-e preenchidas | | [Duplicata de serviços](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) | `14` | Dois títulos com nota fiscal e sem chave da NF-e | | [CT-e](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) | `53` | Dois conhecimentos de transporte com chave preenchida | :::info Sobre os exemplos Os três arquivos passam integralmente pela nossa validação. Os CNPJs são fictícios, mas têm dígito verificador válido — se você trocar por documentos "redondos" tipo `45678912000199`, o arquivo será recusado. ::: ## Checklist antes de enviar - [ ] Todas as linhas com exatamente 444 caracteres - [ ] Header começa com `01REMESSA01COBRANCA` e tem `MX` nas posições 109–110 - [ ] Código do originador cadastrado, alinhado à direita com zeros - [ ] Sem acentos, `Ç` ou caracteres especiais em qualquer campo - [ ] CPF/CNPJ do sacado com dígito verificador válido - [ ] Nome e endereço do sacado preenchidos - [ ] Chave da NF-e com 44 dígitos nas duplicatas mercantis e CT-e - [ ] Nº de controle do participante único por ativo - [ ] Valores monetários sem vírgula, com 2 decimais - [ ] Ocorrência `01` (ou `72`/`74` apenas em lote de substituição) - [ ] Sequencial de registro correto, com o trailer fechando na última linha --- # Layout CSV — Contratos Parcelados URL: /documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado Layout do arquivo de **cessão de contratos parcelados** (`asset_type` igual a `contract`) aceito pela QI CTVM. É um CSV com **uma linha por parcela**: as linhas que compartilham o mesmo `external_id` são as parcelas de um mesmo contrato e formam um único ativo. :::info Onde este arquivo é usado Este é o arquivo enviado no fluxo descrito em [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), pelo portal do gestor ou do consultor. Para ceder contrato parcelado ativo a ativo pela API, veja [Criação de Ativo — Contrato Parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract). ::: **[📄 Baixar modelo CSV](/downloads/modelos_arquivo/modelo_cessao_contrato_parcelado.csv)** O modelo já vem com linhas de exemplo preenchidas — dois contratos, um pré-fixado de pessoa física com duas parcelas e um pós-fixado de pessoa jurídica com uma parcela. Apague as linhas de exemplo antes de colocar os seus dados. ## Estrutura do arquivo | Item | Regra | |---|---| | **Cabeçalho** | 1 linha, sempre a primeira, com os nomes das colunas exatamente como no modelo | | **Linhas de dados** | 1 por **parcela**. Um contrato com 12 parcelas ocupa 12 linhas | | **Agrupamento** | Linhas com o mesmo `external_id` são o mesmo ativo. O lote é contado em ativos, não em linhas | | **Extensão** | `.csv` | | **Separador** | Vírgula (`,`) ou ponto e vírgula (`;`) — detectado a partir da linha de cabeçalho | | **Codificação** | UTF-8 (com ou sem BOM) | | **Datas** | Formato `AAAA-MM-DD` | | **Valores** | Ponto como separador decimal, sem separador de milhar. `R$ 900,00` → `900.00` | | **Documentos** | CPF em `000.000.000-00` e CNPJ em `00.000.000/0000-00`, sempre com a pontuação | :::caution O cabeçalho é fechado Use o cabeçalho do modelo sem alterações: não traduza, não renomeie e não acrescente colunas. Qualquer coluna fora do modelo, ou a falta de uma coluna obrigatória, recusa o arquivo inteiro antes de qualquer linha ser conferida. ::: ## Colunas ### Identificação | Coluna | Obrigatoriedade | Descrição | |---|---|---| | `asset_type` | obrigatória | Tipo do ativo. Para contrato parcelado, o único valor aceito é `contract`, em todas as linhas | | `external_id` | obrigatória | Identificador do contrato no seu sistema, até 50 caracteres. É a chave do ativo: as parcelas do mesmo contrato repetem o mesmo valor | | `originator_document_number` | obrigatória | CPF ou CNPJ do originador, com pontuação. Precisa estar cadastrado e vinculado à configuração de cessão, e ser o mesmo em todas as linhas do arquivo | | `contract_number` | obrigatória | Número do contrato, até 50 caracteres. Enviado exatamente como escrito, sem normalização | | `contract_issue_date` | opcional | Data de emissão do contrato, em `AAAA-MM-DD` | ### Valores e juros | Coluna | Obrigatoriedade | Descrição | |---|---|---| | `total_purchase_value` | obrigatória | Valor que o fundo paga pelo contrato inteiro. Repita o mesmo valor em todas as linhas do contrato | | `interest_rate_type` | obrigatória | `pre_fixed` ou `post_fixed`. Define quais colunas de taxa passam a ser obrigatórias | | `calendar_base` | opcional | Base de contagem de dias do contrato: `workdays`, `calendar_360` ou `calendar_365`. Em branco, é assumido `workdays` | | `pre_fixed_calendar_base` | condicional | Base de contagem de dias da taxa pré-fixada. Obrigatória quando `interest_rate_type` é `pre_fixed` | | `pre_fixed_monthly_rate` | condicional | Taxa mensal pré-fixada, em fração decimal menor que 1 e com até 8 casas: `0.015` significa 1,5% ao mês. Obrigatória quando `interest_rate_type` é `pre_fixed` | | `post_fixed_calendar_base` | condicional | Base de contagem de dias da correção pós-fixada. Obrigatória quando `interest_rate_type` é `post_fixed` | | `post_fixed_indexer` | condicional | Índice que corrige o contrato: `di`, `selic` ou `ipca`. Obrigatória quando `interest_rate_type` é `post_fixed` | | `post_fixed_rate` | condicional | Taxa aplicada sobre o indexador. `1` significa 100% do índice. Obrigatória quando `interest_rate_type` é `post_fixed` | | `post_fixed_lag_reference` | condicional | Unidade da defasagem do índice: `daily` ou `monthly`. Obrigatória quando `interest_rate_type` é `post_fixed` | | `post_fixed_lag_amount` | condicional | Quantidade de defasagem, em número inteiro (ex.: `2` com `monthly` usa o índice de dois meses antes). Obrigatória quando `interest_rate_type` é `post_fixed` | :::caution Ágio e dedução não entram no arquivo O CSV de contrato parcelado não tem colunas de ágio ou dedução — elas não se aplicam a este tipo de ativo. O valor de aquisição é sempre o `total_purchase_value`. ::: ### Parcelas | Coluna | Obrigatoriedade | Descrição | |---|---|---| | `installment_number` | obrigatória | Número da parcela, inteiro começando em 1. Uma linha por parcela | | `installment_maturity_date` | obrigatória | Data de vencimento da parcela, em `AAAA-MM-DD`. As datas precisam crescer junto com o número da parcela | | `installment_face_value` | obrigatória | Valor de face da parcela — quanto o sacado paga no vencimento. Ponto como separador decimal, até 8 casas | | `installment_principal_value` | opcional | Parte do principal amortizada nesta parcela | | `installment_external_id` | opcional | Identificador da parcela no seu sistema, até 50 caracteres | ### Sacado | Coluna | Obrigatoriedade | Descrição | |---|---|---| | `borrower_name` | obrigatória | Nome completo do sacado, até 255 caracteres | | `borrower_document_number` | obrigatória | CPF ou CNPJ do sacado, com pontuação e compatível com o `borrower_person_type` | | `borrower_person_type` | obrigatória | `natural_person` (pessoa física) ou `legal_person` (pessoa jurídica) | | `borrower_gender` | condicional | `male` ou `female`. Obrigatória quando `borrower_person_type` é `natural_person`; deixe em branco para pessoa jurídica | | `borrower_mother_name` | opcional | Nome da mãe do sacado. Usado apenas para pessoa física | | `borrower_birthdate` | opcional | Data de nascimento do sacado, em `AAAA-MM-DD`. Usada apenas para pessoa física | | `borrower_email` | opcional | E-mail do sacado | | `borrower_phone_area_code` | opcional | DDD do telefone, exatamente 2 dígitos. Se informar o DDD, informe também o número | | `borrower_phone_number` | opcional | Telefone do sacado, 8 ou 9 dígitos, sem DDD e sem pontuação | | `borrower_address_postal_code` | opcional | CEP no formato `00000-000`. Se preencher qualquer outro campo de endereço, o CEP passa a ser obrigatório | | `borrower_address_street` | opcional | Logradouro, até 255 caracteres | | `borrower_address_number` | opcional | Número do endereço, até 40 caracteres | | `borrower_address_neighborhood` | opcional | Bairro, até 255 caracteres | | `borrower_address_city` | opcional | Cidade, até 255 caracteres | | `borrower_address_uf` | opcional | Sigla de 2 letras do estado, em maiúsculas (ex.: `SP`) | | `borrower_address_country` | opcional | País em 3 letras (ex.: `BRA`) | ## Regras do arquivo - **Uma linha por parcela, um `external_id` por contrato.** O contador de ativos do lote usa os `external_id` distintos. - **As linhas do mesmo contrato precisam ser idênticas fora das colunas de parcela.** Todas as colunas cujo nome **não** contém `installment` são conferidas entre as linhas que compartilham o `external_id`; qualquer divergência aponta os campos diferentes e recusa o arquivo. - **O fluxo de pagamento precisa ser crescente.** Parcela maior com vencimento anterior ao de uma parcela menor recusa o arquivo. - **`installment_number` precisa formar a sequência `1, 2, 3, …`** dentro de cada contrato, ordenado por vencimento. Uma numeração com salto ou repetição faz o ativo ser recusado com o código `TRC000174`, sem derrubar os demais ativos do arquivo. - **Todas as linhas precisam ter o mesmo `originator_document_number`**, e esse originador precisa estar cadastrado e vinculado à configuração de cessão. - **Não inclua as colunas de recompra** (`assignor_document_number` e `settlement_type`): com elas o arquivo passa a ser lido como substituição e é recusado. Lote de substituição de contrato parcelado não é aceito por arquivo hoje. - **O identificador do lote é único e definitivo.** Um lote recusado não pode ser reenviado com o mesmo identificador — envie um lote novo. - **A validação é tudo ou nada na etapa de arquivo.** Uma linha inválida recusa o arquivo inteiro, e o relatório lista no máximo **50 erros** por envio. ## Erros mais comuns | Mensagem | Causa | |---|---| | Coluna obrigatória ausente no cabeçalho | O cabeçalho foi editado ou salvo de um modelo antigo | | Linhas com o mesmo identificador possuem dados inconsistentes nos campos: … | Alguma coluna que não é de parcela mudou entre as linhas do mesmo contrato | | Fluxo de pagamento inválido para o ativo … | Vencimentos fora de ordem em relação ao número da parcela | | Número da parcela … inválido | `installment_number` com texto, decimal ou em branco | | O contrato … deve ter os números das parcelas em sequência iniciando em 1 | Salto ou repetição na numeração das parcelas (`TRC000174`) | | O número de documento … não é válido | CPF ou CNPJ sem pontuação ou com dígito verificador inválido | | Esse lote não pode receber esse tipo de ativo | O `asset_type` do arquivo não é o da configuração de cessão selecionada | ## Exemplo ```csv title="modelo_cessao_contrato_parcelado.csv (colunas principais)" asset_type,external_id,contract_number,total_purchase_value,interest_rate_type,borrower_name,borrower_document_number,installment_number,installment_maturity_date,installment_face_value contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,Jove de Souza,593.607.530-33,1,2026-12-25,500.46 contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,Jove de Souza,593.607.530-33,2,2027-01-25,500.46 contract,CONTRATO_0002,2244927986/XXX,450.00,post_fixed,Empresa Souza LTDA,53.020.654/0001-43,1,2026-12-25,500.46 ``` O trecho acima mostra apenas as colunas principais, para leitura. O arquivo enviado precisa ter **todas** as colunas do modelo no cabeçalho — baixe o [modelo completo](/downloads/modelos_arquivo/modelo_cessao_contrato_parcelado.csv). ## Checklist antes de enviar - [ ] Cabeçalho igual ao do modelo, sem colunas extras nem faltando - [ ] `asset_type` igual a `contract` em todas as linhas, e igual ao tipo da configuração de cessão - [ ] Uma linha por parcela, com o `external_id` repetido nas parcelas do mesmo contrato - [ ] Colunas que não são de parcela idênticas entre as linhas do mesmo contrato - [ ] `installment_number` em sequência de 1 a N, com vencimentos crescentes - [ ] Colunas `pre_fixed_*` **ou** `post_fixed_*` preenchidas conforme o `interest_rate_type` - [ ] `borrower_gender` preenchido para sacado pessoa física - [ ] CPF/CNPJ com pontuação e dígito verificador válido - [ ] Valores com ponto decimal e sem separador de milhar - [ ] Arquivo salvo como CSV em UTF-8 --- # Cessão por Arquivo URL: /documentation/iaas/negociacao_recebiveis/arquivo/inicio Além da inserção ativo a ativo pela API, é possível ceder um lote inteiro **enviando um único arquivo** pelo portal do gestor ou do consultor. O arquivo é validado linha a linha, convertido em ativos e segue exatamente o mesmo fluxo de elegibilidade, aprovação, termo de cessão e pagamento descrito na [Introdução](/documentation/iaas/negociacao_recebiveis/inicio). :::info Envio por arquivo é um fluxo de tela O envio de arquivo de cessão é feito **pelo portal**, não pela API de integração. Pela API, a cessão é feita pelo fluxo de [criação de lote + inserção de ativos](/documentation/iaas/negociacao_recebiveis/fluxo_cessao), ativo a ativo, sem arquivo. ::: | | Envio por arquivo | Inserção pela API | |---|---|---| | **Como funciona** | Um arquivo com todos os ativos do lote | Uma requisição por ativo | | **Formatos** | CNAB 444 (duplicatas, contratos, CTe) e CSV (CCB, honorários e contratos parcelados) | JSON | | **Indicado para** | Quem já gera CNAB para bancos/FIDCs e quer reaproveitar o layout | Quem quer controle e retorno por ativo, em tempo real | | **Retorno de erro** | Consolidado ao final da validação do arquivo | Imediato, na resposta de cada ativo | | **Disponível em** | Portal do gestor e do consultor | API de integração | Os dois caminhos produzem o mesmo lote e o mesmo resultado. Escolha um por lote — não é possível misturar arquivo e API no mesmo lote. ## Formatos aceitos O formato é determinado pelo **tipo de ativo da configuração de cessão** que você seleciona na tela. | Tipo de ativo da configuração | Formato do arquivo | Extensão | Modelo | |---|---|---|---| | `duplicata_mercantil` | **CNAB 444**, espécie `01` | `.rem` · `.txt` | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) | | `duplicata_servicos` | **CNAB 444**, espécie `14` | `.rem` · `.txt` | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) | | `cte` | **CNAB 444**, espécie `53` | `.rem` · `.txt` | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) | | `ccb` e `structured_cci` | **CSV** | `.csv` | [Modelo](/downloads/modelos_arquivo/modelo_cessao_ccb.csv) | | `legal_fees` (honorários advocatícios) | **CSV** | `.csv` | [Modelo](/downloads/modelos_arquivo/modelo_cessao_honorarios.csv) | | `contract` (contratos parcelados) | **CSV** | `.csv` | [Modelo](/downloads/modelos_arquivo/modelo_cessao_contrato_parcelado.csv) | Em lotes de substituição, as linhas de recompra entram no mesmo CSV, com as colunas de recompra: [modelo de substituição](/downloads/modelos_arquivo/modelo_cessao_substituicao.csv). :::caution Cada formato atende tipos específicos O CSV é aceito apenas para `ccb`, `structured_cci`, `legal_fees` e `contract`. Para **cessão de duplicatas e CT-e o formato é o CNAB 444** — o mesmo layout de remessa de cobrança usado no mercado, descrito em [Layout CNAB 444 — Cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444). O layout do CSV de contratos parcelados está em [Layout CSV — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado). Demais tipos de ativo, como `discounted_contract`, são cedidos **pela API**, ativo a ativo — não há formato de arquivo para eles hoje. ::: ## Fluxo do envio ## Passo a passo pela tela No **portal do gestor** e no **portal do consultor**: 1. Acesse **Ativos › Cessões** e clique em **Nova cessão**. 2. Informe o **cedente** (CPF/CNPJ) e selecione a **configuração de cessão** — é ela que define o fundo, o tipo de ativo e, portanto, o formato de arquivo aceito. 3. Informe o **identificador do lote** e a **data da cessão**, que precisa ser a data contábil aberta do fundo — normalmente o dia útil corrente. 4. Marque **Substituição** se o lote tiver ativos de recompra. 5. Escolha o **meio de pagamento** ao cedente (Pix ou TED), quando aplicável. 6. Arraste o arquivo (`.rem`, `.txt` ou `.csv`) para a área de upload e confirme. O lote passa a aparecer na listagem de cessões, com o status atualizado em tempo real conforme a validação avança. :::info Permissões O usuário precisa da permissão de criação de cessão por arquivo no fundo em questão. A concessão é feita pelo administrador do portal em **Usuários › Associações do fundo**. ::: ## Acompanhamento e retorno de erros A listagem de cessões mostra o andamento do lote de arquivo: | Etapa | O que significa | O que fazer | |---|---|---| | Aguardando arquivo | Lote criado, arquivo ainda não enviado | Faça o upload e confirme o envio | | Validação em andamento | Arquivo recebido, sendo conferido linha a linha | Aguarde | | Criando o lote | Arquivo válido, lote sendo criado | Aguarde | | Inserindo os ativos | Cada linha está virando um ativo | Aguarde | | Concluído | Todos os ativos inseridos | Acompanhe o lote pelo [fluxo de cessão](/documentation/iaas/negociacao_recebiveis/fluxo_cessao) | | Recusado | Arquivo recusado na validação | Corrija o arquivo e envie um **lote novo**, com um novo identificador | Quando o arquivo é recusado, o portal lista as linhas inválidas e, para cada uma, o campo, as posições no registro e a descrição do erro em português — por exemplo: > Linha 1, posições 218–234: o CNPJ do sacado '45678912000199' é inválido. Verifique o número do documento e tente novamente. :::caution Validação é tudo ou nada Uma única linha inválida recusa o arquivo inteiro — não existe processamento parcial. A análise para após **50 erros encontrados**, então corrija os erros apontados e reenvie: podem existir outros adiante. ::: ## Regras que valem para qualquer arquivo - **O identificador do lote é único e definitivo.** Um lote recusado não pode ser reenviado com o mesmo identificador. - **A data da cessão precisa ser a data contábil aberta do fundo.** Outra data devolve erro na criação do lote. - **O arquivo é imutável.** Para alterar qualquer informação, envie um lote novo. - **Cada linha vira um ativo**, identificado pelo número do documento (posições 111–120 no CNAB). Em arquivos de duplicata e CT-e, **duas linhas com o mesmo número de documento derrubam a cessão inteira** — cada título precisa de um número próprio. Em CSV de CCB e de contrato parcelado, ao contrário, várias linhas com o mesmo identificador são lidas como as parcelas de um mesmo contrato. - **O cedente e o originador precisam estar previamente cadastrados** e vinculados à configuração de cessão — veja [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato). :::info Envio por SFTP Para operações de alto volume, a QI CTVM também disponibiliza a esteira de remessa por SFTP, com diretório dedicado por fundo e cedente e arquivo de retorno com os erros. É uma configuração sob demanda — fale com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). ::: --- # Criação de Ativo — CCB URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_co Endpoint para inserir um ativo do tipo **CCB** (Cédula de Crédito Bancário) em um lote de cessão. Cada ativo representa uma operação de crédito que será cedida ao fundo. :::tip Onde estou no fluxo? Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::caution Atenção O campo `external_id` da operação de crédito deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset MÉTODO POST ```json title="Request Body" { "asset_type": "ccb", "total_purchase_value": 1351.66, "premiums": [ { "premium_type": "spread", "total_value": 13.38 } ], "credit_operation": { "contract": { "number": "0008309052/NBF", "disbursement_date": "2023-07-06", "issue_date": "2023-07-06", "signature_date": "2023-07-06", "issue_value": 1338.28 }, "amortization_type": "sac", "borrower": { "name": "QI CTVM", "document_number": "19.845.976/0001-93", "person_type": "legal_person", "email": "qidtvm@qitech.com.br", "address": { "street": "Pátio de Teixeira", "number": "1", "neighborhood": "Estrela do Oriente", "city": "Rondônia", "postal_code": "01012-030", "uf": "RO", "country": "BRA" }, "phone": { "area_code": "11", "number": "936360268" }, "legal_person": { "activity_code": "11.11-1-11" } }, "delay": { "fine": { "fine_type": "percentage", "percentage_value": 0.0 }, "interest": { "method": "compound", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360" } } }, "principal_value": 1338.28, "interest_rate_type": "pre_fixed", "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2", "originator_document_number": "75.723.105/0001-78", "pre_fixed": { "calendar_base": "calendar_365", "monthly_rate": 0.018 }, "installments": [ { "maturity_date": "2023-10-01", "installment_number": 1, "face_value": 689.33 }, { "maturity_date": "2024-10-01", "installment_number": 2, "face_value": 482.53 }, { "maturity_date": "2025-10-01", "installment_number": 3, "face_value": 300.36 }, { "maturity_date": "2026-10-01", "installment_number": 4, "face_value": 162.77 }, { "maturity_date": "2027-10-01", "installment_number": 5, "face_value": 81.39 }, { "maturity_date": "2028-10-01", "installment_number": 6, "face_value": 40.69 } ], "modality_code": "0202", "consignee": { "consignee_type": "inss", "name": "Consignee name", "document_number": "11.620.231/3105-71" }, "collaterals": [ { "collateral_type": "social_security", "benefit_number": "0000000000", "benefit_type": "benefit_type", "status": "reserved" } ] } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_type` | string | obrigatório | Tipo do ativo. Para CCB, informar `ccb`. | | `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. | | `premiums` | array | opcional | Lista de ágios envolvidos na venda. Informação apenas para visualização posterior — não é utilizada em cálculos. | | `credit_operation` | object | obrigatório | Dados da operação de crédito. Veja [Atributos de `credit_operation`](#atributos-de-credit_operation). | #### Atributos de `premiums` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `premium_type` | string | obrigatório | Tipo do ágio. | | `total_value` | number | obrigatório | Valor total do ágio. Até 2 casas decimais. | **Enumeradores de `premium_type`:** | Valor | Descrição | |---|---| | `spread` | Spread vinculado à originação e emissão do crédito. | #### Atributos de `credit_operation` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. | | `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. | | `principal_value` | number | obrigatório | Principal total em aberto da operação. Até 8 casas decimais. | | `contract` | object | obrigatório | Dados do contrato. Veja [Atributos de `contract`](#atributos-de-contract). | | `borrower` | object | obrigatório | Dados do sacado/devedor. Veja [Atributos de `borrower`](#atributos-de-borrower). | | `amortization_type` | string | obrigatório | Tipo de amortização utilizado no cálculo. | | `interest_rate_type` | string | obrigatório | Tipo de juros da operação. | | `pre_fixed` | object | obrigatório | Dados do cálculo da parte pré-fixada. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). | | `installments` | array | obrigatório | Lista de parcelas da operação. Veja [Atributos de `installments`](#atributos-de-installments). | | `delay` | object | opcional | Dados de multa e juros por atraso. Veja [Atributos de `delay`](#atributos-de-delay). | | `modality_code` | string | opcional | Código de 4 dígitos que especifica a categoria ou tipo de operação financeira associada ao ativo. | | `consignee` | object | opcional | Dados do ente consignante. Veja [Atributos de `consignee`](#atributos-de-consignee). | | `collaterals` | array | opcional | Lista de garantias associadas à operação. Veja [Atributos de `collaterals`](#atributos-de-collaterals). | **Enumeradores de `amortization_type`:** | Valor | Descrição | |---|---| | `sac` | Amortização do tipo SAC. | | `price` | Amortização do tipo Price. | **Enumeradores de `interest_rate_type`:** | Valor | Descrição | |---|---| | `pre_fixed` | Para operações pré-fixadas. | | `post_fixed` | Para operações pós-fixadas. | #### Atributos de `contract` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `number` | string | obrigatório | Número do contrato. Máximo de 50 caracteres. | | `disbursement_date` | string | obrigatório | Data de desembolso no formato `YYYY-MM-DD`. | | `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. | | `signature_date` | string | opcional | Data de assinatura do contrato no formato `YYYY-MM-DD`. | | `issue_value` | number | obrigatório | Valor de emissão do contrato. Até 2 casas decimais. | #### Atributos de `borrower` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do sacado. Máximo de 255 caracteres. | | `document_number` | string | obrigatório | CPF ou CNPJ do sacado. | | `person_type` | string | obrigatório | Tipo de pessoa. | | `email` | string | opcional | E-mail do sacado. Máximo de 255 caracteres. | | `address` | object | obrigatório | Endereço do sacado. Veja [Atributos de `address`](#atributos-de-address). | | `phone` | object | opcional | Telefone do sacado. Veja [Atributos de `phone`](#atributos-de-phone). | **Enumeradores de `person_type`:** | Valor | Descrição | |---|---| | `natural_person` | Pessoa Física. Quando informado, incluir o objeto `natural_person` dentro de `borrower`. Veja [Atributos de `natural_person`](#atributos-de-natural_person). | | `legal_person` | Pessoa Jurídica. Quando informado, incluir o objeto `legal_person` dentro de `borrower`. Veja [Atributos de `legal_person`](#atributos-de-legal_person). | #### Atributos de `address` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `street` | string | obrigatório | Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres. | | `number` | string | opcional | Número do endereço. Máximo de 40 caracteres. | | `neighborhood` | string | opcional | Bairro. Máximo de 255 caracteres. | | `city` | string | opcional | Cidade. Máximo de 255 caracteres. | | `uf` | string | opcional | Sigla do estado. 2 caracteres. | | `complement` | string | opcional | Complemento. Máximo de 255 caracteres. | | `postal_code` | string | obrigatório | CEP. 9 caracteres (com hífen). | | `country` | string | opcional | País no formato ISO 3166-1 alpha-3. 3 caracteres. | #### Atributos de `phone` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `area_code` | string | obrigatório | Código de área (DDD). 2 dígitos. | | `number` | string | obrigatório | Número de telefone. Até 9 dígitos. | #### Atributos de `natural_person` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `birthdate` | string | opcional | Data de nascimento no formato `YYYY-MM-DD`. | | `gender` | string | opcional | Gênero. | | `mother_name` | string | opcional | Nome da mãe. Máximo de 255 caracteres. | **Enumeradores de `gender`:** | Valor | Descrição | |---|---| | `male` | Masculino. | | `female` | Feminino. | #### Atributos de `legal_person` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `foundation_date` | string | opcional | Data de fundação no formato `YYYY-MM-DD`. | | `activity_code` | string | obrigatório | Código de atividade no formato `11.11-1-11`. | | `annual_revenues` | integer | opcional | Receita anual em centavos. | | `representatives` | array | opcional | Lista de representantes legais. Veja [Atributos de `representatives`](#atributos-de-representatives). | #### Atributos de `representatives` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do representante. Máximo de 255 caracteres. | | `document_number` | string | obrigatório | CPF ou CNPJ do representante. | | `email` | string | opcional | E-mail do representante. Máximo de 255 caracteres. | | `phone` | object | opcional | Telefone. Mesma estrutura de [Atributos de `phone`](#atributos-de-phone). | | `address` | object | opcional | Endereço. Mesma estrutura de [Atributos de `address`](#atributos-de-address). | | `person_type` | string | obrigatório | Tipo de pessoa (`natural_person` ou `legal_person`). | | `representative_type` | string | opcional | Tipo do representante. Máximo de 50 caracteres. | #### Atributos de `pre_fixed` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `calendar_base` | string | obrigatório | Base de cálculo utilizada. | | `monthly_rate` | number | obrigatório | Taxa mensal do contrato. Para 1%, informar `0.01`. Até 8 casas decimais. | **Enumeradores de `calendar_base`:** | Valor | Descrição | |---|---| | `workdays` | Base de cálculo em dias úteis (252). | | `calendar_365` | Base de cálculo em 365 dias. | | `calendar_360` | Base de cálculo em 360 dias. | #### Atributos de `installments` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `maturity_date` | string | obrigatório | Data de vencimento da parcela no formato `YYYY-MM-DD`. | | `installment_number` | integer | obrigatório | Número da parcela. | | `face_value` | number | opcional | Valor de face da parcela. Até 8 casas decimais. | | `principal_value` | number | opcional | Principal esperado a ser amortizado na data de vencimento. Até 8 casas decimais. | #### Atributos de `delay` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `fine` | object | opcional | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). | | `interest` | object | opcional | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). | #### Atributos de `fine` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `fine_type` | string | obrigatório | Tipo da multa. | | `percentage_value` | number | condicional | Valor da multa quando `fine_type` for `percentage`. De 0 a 1, representando 0% a 100%. Até 2 casas decimais. | | `amount` | number | condicional | Valor fixo da multa quando `fine_type` for `fixed`. Até 2 casas decimais. | **Enumeradores de `fine_type`:** | Valor | Descrição | |---|---| | `percentage` | Multa percentual sobre o valor da parcela. | | `fixed` | Valor fixo de multa. | #### Atributos de `interest` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `method` | string | obrigatório | Método do juros de mora. | | `pre_fixed` | object | obrigatório | Dados da taxa pré-fixada. Mesma estrutura de [Atributos de `pre_fixed`](#atributos-de-pre_fixed). | **Enumeradores de `method`:** | Valor | Descrição | |---|---| | `compound` | Juros de mora composto. | | `simple` | Juros de mora simples. | #### Atributos de `consignee` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do ente consignante. Máximo de 255 caracteres. | | `document_number` | string | obrigatório | CPF ou CNPJ do ente consignante. | | `consignee_type` | string | obrigatório | Tipo de consignado. | **Enumeradores de `consignee_type`:** | Valor | Descrição | |---|---| | `public` | Consignado público. | | `private` | Consignado privado. | | `inss` | Consignado INSS. | #### Atributos de `collaterals` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `collateral_type` | string | obrigatório | Tipo de garantia. | :::info Como montar `collaterals` `collaterals` é uma lista e cada item representa **uma** garantia. O `collateral_type` determina quais campos aquele item aceita — os campos de um tipo não são aceitos em outro. Qualquer propriedade fora do conjunto do tipo informado é recusada com `QIT000001`. ::: **Enumeradores de `collateral_type`:** | Valor | Descrição | |---|---| | `fgts` | Garantia de FGTS. Incluir os campos de [Atributos de garantia FGTS](#atributos-de-garantia-fgts). | | `social_security` | Garantia de INSS. Incluir os campos de [Atributos de garantia INSS](#atributos-de-garantia-inss). | | `home_equity` | Garantia de imóveis. Incluir os campos de [Atributos de garantia imóvel](#atributos-de-garantia-imóvel). | | `vehicle` | Garantia de veículo. Incluir os campos de [Atributos de garantia veículo](#atributos-de-garantia-veículo). | #### Atributos de garantia FGTS | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `protocol_number` | string | obrigatório | Número do protocolo. | | `status` | string | obrigatório | Status da garantia. | #### Atributos de garantia INSS | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `benefit_number` | string | obrigatório | Número do benefício. | | `benefit_type` | string | obrigatório | Tipo do benefício. | | `status` | string | obrigatório | Status da garantia. | #### Atributos de garantia imóvel | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `enterprise_name` | string | obrigatório | Nome do empreendimento. | | `registration_number` | string | obrigatório | Número do registro do imóvel. | | `enterprise_document_number` | string | opcional | CPF ou CNPJ associado ao empreendimento. | | `collateral_properties` | array | obrigatório | Lista de propriedades do imóvel. Veja [Atributos de `collateral_properties`](#atributos-de-collateral_properties). | #### Atributos de `collateral_properties` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `address` | object | obrigatório | Endereço do imóvel. Mesma estrutura de [Atributos de `address`](#atributos-de-address). | | `total_collateral_value` | number | obrigatório | Valor do imóvel. Até 8 casas decimais. | #### Atributos de garantia veículo | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `vehicle_loan_value` | number | opcional | Valor financiado do veículo. Não pode ser negativo. | | `vehicle_total_market_value` | number | opcional | Valor de mercado total do veículo. Não pode ser negativo. | | `vehicle_identification` | object | obrigatório | Identificação do veículo. Veja [Atributos de `vehicle_identification`](#atributos-de-vehicle_identification). | ```json title="Exemplo de garantia de veículo" { "collateral_type": "vehicle", "vehicle_loan_value": 30000.00, "vehicle_total_market_value": 55000.00, "vehicle_identification": { "brand": "Toyota", "model": "Corolla XEi 2.0", "manufacturing_year": 2022, "chassis_number": "9BRBLWHEXK0123456", "license_plate": "ABC1D23", "renavam": "12345678901" } } ``` #### Atributos de `vehicle_identification` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `brand` | string | opcional | Marca do veículo. | | `model` | string | obrigatório | Modelo do veículo. | | `manufacturing_year` | integer | obrigatório | Ano de fabricação do veículo. Mínimo 1900. | | `chassis_number` | string | obrigatório | Número do chassi do veículo. | | `license_plate` | string | opcional | Placa do veículo. | | `renavam` | string | opcional | Código RENAVAM do veículo. | ## Response STATUS 201 ```json title="Response Body" { "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2", "status": "pending_eligibility" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). | | `external_id` | string | A mesma chave externa fornecida no campo `external_id` da `credit_operation`. | | `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. | ## Possíveis erros STATUS 404 **Lote não encontrado** O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto. ```json { "title": "Assignment not found", "description": "Assignment not found", "translation": "Lote não encontrado", "code": "TRC000018" } ``` STATUS 404 **Tipo de ativo não existe** O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `ccb`, `duplicata_mercantil`, `discounted_contract`). ```json { "title": "Asset type does not exist", "description": "Asset type 'invalid_asset_type' does not exist", "translation": "Tipo do ativo 'invalid_asset_type' nao existe", "code": "TRC000015" } ``` STATUS 400 **Tipo de ativo incompatível com o lote** O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada. ```json { "title": "Invalid asset type configuration", "description": "This assignment can not receive this asset type: ccb", "translation": "Esse lote não pode receber esse tipo de ativo: ccb", "code": "TRC000025" } ``` STATUS 400 **Lote fechado para inserção** O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos. ```json { "title": "Assignment is closed", "description": "Assignment is closed to insert new assets", "translation": "Lote esta fechado para inserir novos ativos", "code": "TRC000022" } ``` STATUS 400 **Número de documento inválido** Um dos números de documento informados (CPF ou CNPJ) é inválido. Verifique os campos `document_number`, `originator_document_number` e demais campos de documento no request body. ```json { "title": "Invalid Document number", "description": "Given '000.000.000-00' document number is invalid.", "translation": "O numero de document '000.000.000-00' fornecido não é valido.", "code": "TRC000009" } ``` STATUS 400 **External ID duplicado** Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente. ```json { "title": "Already Exist This External Id", "description": "Already exist an asset with this External Id", "translation": "Ja existe um ativo com esse External Id", "code": "TRC000054" } ``` ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade. 2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade. --- # Criação de Ativo — Contrato Parcelado URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_contract Endpoint para inserir um ativo do tipo **Contrato Parcelado** em um lote de cessão. Cada ativo representa um contrato com um fluxo de parcelas — o contrato inteiro é cedido ao fundo em uma única requisição, com todas as suas parcelas. :::tip Onde estou no fluxo? Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::info Um ativo, várias parcelas Diferente do [Contrato Descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract) — em que cada parcela é um ativo independente — no contrato parcelado **o ativo é o contrato**, e as parcelas são o fluxo de pagamentos dele. O array `installments` precisa conter todas as parcelas do contrato que estão sendo cedidas. ::: :::caution Atenção O campo `external_id` do contrato deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset MÉTODO POST ```json title="Request Body" { "asset_type": "contract", "total_purchase_value": 900.00, "contract": { "external_id": "80187a08-ea7d-44b2-b65c-131f1318e904", "originator_document_number": "53.020.654/0001-43", "contract_number": "1144927986/XXX", "issue_date": "2026-11-01", "interest_rate_type": "pre_fixed", "calendar_base": "calendar_365", "pre_fixed": { "calendar_base": "calendar_365", "monthly_rate": 0.015 }, "borrower": { "name": "Jove de Souza", "document_number": "593.607.530-33", "person_type": "natural_person", "email": "jose.souza@yopmail.com", "address": { "street": "Rua Gilberto Sabino", "number": "215", "neighborhood": "Pinheiros", "city": "São Paulo", "postal_code": "05245-020", "uf": "SP", "country": "BRA" }, "phone": { "area_code": "11", "number": "26260447" }, "natural_person": { "birthdate": "1999-01-01", "gender": "male", "mother_name": "Maria de Souza" } }, "installments": [ { "installment_number": 1, "maturity_date": "2026-12-25", "face_value": 500.46, "principal_value": 450.00, "external_id": "parcela-1" }, { "installment_number": 2, "maturity_date": "2027-01-25", "face_value": 500.46, "principal_value": 450.00, "external_id": "parcela-2" } ], "contract_data": { "cost_center": "SP-01" } } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_type` | string | obrigatório | Tipo do ativo. Para contrato parcelado, informar `contract`. | | `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar pelo contrato inteiro. Até 2 casas decimais. | | `contract` | object | obrigatório | Dados do contrato. Veja [Atributos de `contract`](#atributos-de-contract). | :::caution Ágios e deduções não se aplicam Os campos `premiums` e `deductions` **não são utilizados** em cessão de contrato parcelado. O valor de aquisição do ativo é sempre o `total_purchase_value` informado. ::: #### Atributos de `contract` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. | | `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. Precisa estar cadastrado e vinculado à configuração de cessão. | | `contract_number` | string | obrigatório | Número do contrato. Máximo de 50 caracteres. Enviado exatamente como informado, sem normalização. | | `borrower` | object | obrigatório | Dados do sacado/devedor do contrato. Veja [Atributos de `borrower`](#atributos-de-borrower). | | `interest_rate_type` | string | obrigatório | Tipo de juros do contrato. | | `installments` | array | obrigatório | Lista das parcelas do contrato. Precisa ter ao menos uma parcela. Veja [Atributos de `installments`](#atributos-de-installments). | | `issue_date` | string | opcional | Data de emissão do contrato no formato `YYYY-MM-DD`. | | `calendar_base` | string | opcional | Base de contagem de dias do contrato. Quando omitido, é assumido `workdays`. | | `pre_fixed` | object | condicional | Dados da parte pré-fixada. Obrigatório quando `interest_rate_type` for `pre_fixed`. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). | | `post_fixed` | object | condicional | Dados da parte pós-fixada. Obrigatório quando `interest_rate_type` for `post_fixed`. Veja [Atributos de `post_fixed`](#atributos-de-post_fixed). | | `contract_data` | object | opcional | Objeto livre para informações adicionais do contrato. É armazenado e devolvido nas consultas e webhooks, sem interferir nos cálculos. | **Enumeradores de `interest_rate_type`:** | Valor | Descrição | |---|---| | `pre_fixed` | Para contratos pré-fixados. Informe o objeto `pre_fixed`. | | `post_fixed` | Para contratos pós-fixados. Informe o objeto `post_fixed`. | **Enumeradores de `calendar_base`:** | Valor | Descrição | |---|---| | `workdays` | Base de cálculo em dias úteis (252). | | `calendar_365` | Base de cálculo em 365 dias. | | `calendar_360` | Base de cálculo em 360 dias. | #### Atributos de `installments` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `installment_number` | integer | obrigatório | Número da parcela, começando em 1. Veja a regra de sequência abaixo. | | `maturity_date` | string | obrigatório | Data de vencimento da parcela no formato `YYYY-MM-DD`. | | `face_value` | number | obrigatório | Valor de face da parcela — quanto o sacado paga no vencimento. Maior que zero e até 8 casas decimais. | | `principal_value` | number | opcional | Principal esperado a ser amortizado na data de vencimento. Até 8 casas decimais. | | `external_id` | string | opcional | Chave de identificação da parcela no sistema do parceiro. Máximo de 50 caracteres. | :::caution Sequência das parcelas Ordenando as parcelas pela `maturity_date`, os `installment_number` precisam formar a sequência `1, 2, 3, …` sem repetições e sem saltos. Uma numeração fora de ordem devolve o erro `TRC000174`. ::: #### Atributos de `pre_fixed` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `calendar_base` | string | obrigatório | Base de contagem de dias utilizada na taxa. Mesmos enumeradores de [`calendar_base`](#atributos-de-contract). | | `monthly_rate` | number | obrigatório | Taxa mensal do contrato, em fração decimal entre 0 e 1. Para 1,5% ao mês, informar `0.015`. Até 8 casas decimais. | #### Atributos de `post_fixed` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `calendar_base` | string | obrigatório | Base de contagem de dias da correção. Mesmos enumeradores de [`calendar_base`](#atributos-de-contract). | | `indexer` | string | obrigatório | Índice que corrige o contrato. | | `rate` | number | obrigatório | Taxa aplicada sobre o indexador. Para 100% do DI, informar `1`. | | `lag` | object | obrigatório | Defasagem entre a data do índice e a data da correção. Veja [Atributos de `lag`](#atributos-de-lag). | **Enumeradores de `indexer`:** | Valor | Descrição | |---|---| | `di` | Taxa DI, apurada pela B3. | | `selic` | Taxa Selic. | | `ipca` | IPCA. | #### Atributos de `lag` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `reference` | string | obrigatório | Unidade da defasagem: `daily` (dias) ou `monthly` (meses). | | `amount` | number | obrigatório | Quantidade de defasagem. Para usar o índice de dois meses antes, informar `2` com `reference` igual a `monthly`. | #### Atributos de `borrower` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do sacado. Máximo de 255 caracteres. | | `document_number` | string | obrigatório | CPF ou CNPJ formatado do sacado. | | `person_type` | string | obrigatório | Tipo de pessoa. | | `email` | string | opcional | E-mail do sacado. Máximo de 255 caracteres. | | `address` | object | opcional | Endereço do sacado. Veja [Atributos de `address`](#atributos-de-address). | | `phone` | object | opcional | Telefone do sacado. Veja [Atributos de `phone`](#atributos-de-phone). | **Enumeradores de `person_type`:** | Valor | Descrição | |---|---| | `natural_person` | Pessoa Física. Quando informado, inclua o objeto `natural_person` dentro de `borrower`. Veja [Atributos de `natural_person`](#atributos-de-natural_person). | | `legal_person` | Pessoa Jurídica. Quando informado, inclua o objeto `legal_person` dentro de `borrower`. Veja [Atributos de `legal_person`](#atributos-de-legal_person). | #### Atributos de `address` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `postal_code` | string | obrigatório | CEP. 9 caracteres, no formato `00000-000`. Obrigatório sempre que o objeto `address` for informado. | | `street` | string | opcional | Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres. | | `number` | string | opcional | Número do endereço. Máximo de 40 caracteres. | | `neighborhood` | string | opcional | Bairro. Máximo de 255 caracteres. | | `city` | string | opcional | Cidade. Máximo de 255 caracteres. | | `uf` | string | opcional | Sigla do estado. 2 caracteres. | | `complement` | string | opcional | Complemento. Máximo de 255 caracteres. | | `country` | string | opcional | País no formato ISO 3166-1 alpha-3. 3 caracteres. | #### Atributos de `phone` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `area_code` | string | obrigatório | Código de área (DDD). 2 dígitos. | | `number` | string | obrigatório | Número de telefone. 8 ou 9 dígitos. | #### Atributos de `natural_person` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `birthdate` | string | opcional | Data de nascimento no formato `YYYY-MM-DD`. | | `gender` | string | opcional | Gênero: `male` ou `female`. | | `mother_name` | string | opcional | Nome da mãe. Máximo de 255 caracteres. | #### Atributos de `legal_person` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `foundation_date` | string | opcional | Data de fundação no formato `YYYY-MM-DD`. | | `activity_code` | string | opcional | Código de atividade (CNAE) no formato `11.11-1-11`. | | `annual_revenues` | integer | opcional | Receita anual em centavos. | | `representatives` | array | opcional | Lista de representantes legais. | ## Response STATUS 201 ```json title="Response Body" { "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "80187a08-ea7d-44b2-b65c-131f1318e904", "status": "pending_eligibility" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). | | `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `contract`. | | `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. | :::info Valores calculados pela QI Tech Na inserção do ativo, a QI Tech calcula e passa a devolver nas consultas e nos webhooks a taxa interna de retorno da compra (`purchase_irr`), a duration do contrato e o `purchase_value` de cada parcela — a fatia do `total_purchase_value` alocada a cada vencimento. Esses campos não devem ser enviados no request. ::: ## Possíveis erros STATUS 400 **Parcelas fora de sequência** Ordenando as parcelas pela data de vencimento, os `installment_number` não formam a sequência `1, 2, 3, …`. Verifique se há número repetido, salto na numeração ou parcela com vencimento fora da ordem. ```json { "title": "Contract must have an installment number sequence", "description": "Contract 80187a08-ea7d-44b2-b65c-131f1318e904 must have installment numbers as a sequence starting at 1 ordered by maturity date", "translation": "O contrato 80187a08-ea7d-44b2-b65c-131f1318e904 deve ter os numeros das parcelas em sequencia iniciando em 1 e ordenados pela data de vencimento", "code": "TRC000174" } ``` STATUS 400 **Tipo de ativo incompatível com o lote** O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada. ```json { "title": "Invalid asset type configuration", "description": "This assignment can not receive this asset type: contract", "translation": "Esse lote não pode receber esse tipo de ativo: contract", "code": "TRC000025" } ``` STATUS 400 **Payload incompatível com o tipo de ativo** O objeto `contract` só é aceito para o tipo de ativo `contract`. Outros tipos de contrato — como `financing_contract` e `debt_acknowledgment` — não são cedidos por este fluxo. ```json { "title": "Invalid assignment date.", "description": "The provided asset_type does not match the specific information passed.", "translation": "o asset_type fornecido não coincide com as informações especificas passadas", "code": "TRC000084" } ``` STATUS 404 **Lote não encontrado** O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto. ```json { "title": "Assignment not found", "description": "Assignment not found", "translation": "Lote não encontrado", "code": "TRC000018" } ``` STATUS 400 **Lote fechado para inserção** O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos. ```json { "title": "Assignment is closed", "description": "Assignment is closed to insert new assets", "translation": "Lote esta fechado para inserir novos ativos", "code": "TRC000022" } ``` STATUS 400 **Número de documento inválido** Um dos números de documento informados (CPF ou CNPJ) é inválido. Verifique os campos `originator_document_number` e `borrower.document_number`. ```json { "title": "Invalid Document number", "description": "Given '000.000.000-00' document number is invalid.", "translation": "O numero de document '000.000.000-00' fornecido não é valido.", "code": "TRC000009" } ``` STATUS 400 **External ID duplicado** Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente. ```json { "title": "Already Exist This External Id", "description": "Already exist an asset with this External Id", "translation": "Ja existe um ativo com esse External Id", "code": "TRC000054" } ``` ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie o contrato assinado, com `document_type` igual a `contract`. 2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade. Para ceder contratos parcelados em volume, sem uma requisição por ativo, use a [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado). --- # Criação de Ativo — CTE URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_cte Endpoint para inserir um ativo do tipo **CTE** (Conhecimento de Transporte Eletrônico) em um lote de cessão. O CTE é um documento fiscal eletrônico que comprova a prestação de serviço de transporte, utilizado como direito creditório na operação de cessão. :::tip Onde estou no fluxo? Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::caution Atenção O campo `external_id` do direito creditório deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset MÉTODO POST ```json title="Request Body" { "asset_type": "cte", "total_purchase_value": 1231.21, "discounted_credit_right": { "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2", "originator_document_number": "46.282.154/0001-14", "maturity_date": "2023-12-10", "order_number": "18923619954796912", "face_value": 1023.01, "person_type": "legal_person", "borrower": { "name": "Transportadora Exemplo Ltda", "document_number": "46.282.154/0001-14", "person_type": "legal_person", "email": "contato@transportadora.com.br", "address": { "street": "Avenida Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "postal_code": "01310-100", "uf": "SP", "country": "BRA" }, "phone": { "area_code": "11", "number": "936360268" }, "legal_person": { "activity_code": "49.30-2-01" } }, "participant_control_number": "ICX841HWCPUGU4U101XPLDW8D", "bankslip": { "our_number": { "number": 2, "digit": "P" } }, "delay": { "fine": { "fine_type": "percentage", "percentage_value": 0.0 }, "interest": { "method": "pre_fixed", "pre_fixed": { "daily_rate": 0.0, "calendar_base": "calendar_360" } } }, "invoice": { "access_key": "35231146282154000114570000000001189236199547", "total_value": 1231.21, "serie": "001", "number": "958431587", "issue_date": "2023-10-10" } } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_type` | string | obrigatório | Tipo do ativo. Para CTE, informar `cte`. | | `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. | | `discounted_credit_right` | object | obrigatório | Dados do direito creditório. Veja [Atributos de `discounted_credit_right`](#atributos-de-discounted_credit_right). | #### Atributos de `discounted_credit_right` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. | | `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. | | `maturity_date` | string | obrigatório | Data de vencimento no formato `YYYY-MM-DD`. | | `order_number` | string | obrigatório | Número do pedido. Máximo de 45 caracteres. | | `face_value` | number | obrigatório | Valor de face. Até 8 casas decimais. | | `person_type` | string | opcional | Tipo de pessoa do sacado (`natural_person` ou `legal_person`). | | `borrower` | object | obrigatório | Dados do sacado. Consulte os [Atributos de `borrower`](#atributos-de-borrower). | | `invoice` | object | obrigatório | Dados do CT-e. Veja [Atributos de `invoice`](#atributos-de-invoice). | | `participant_control_number` | string | opcional | Número de controle do participante no sistema do parceiro. Máximo de 25 caracteres alfanuméricos. | | `bankslip` | object | opcional | Dados do boleto. Veja [Atributos de `bankslip`](#atributos-de-bankslip). | | `delay` | object | opcional | Dados de multa e juros por atraso. Veja [Atributos de `delay`](#atributos-de-delay). | #### Atributos de `invoice` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `access_key` | string | obrigatório | Chave de acesso do CT-e. 44 caracteres. Os caracteres de posição 20 a 22 devem corresponder ao modelo do documento (`57` ou `67`). | | `total_value` | number | opcional | Valor total do CT-e. Até 2 casas decimais. | | `serie` | string | obrigatório | Número de série do CT-e. Máximo de 3 caracteres. | | `number` | string | obrigatório | Número do CT-e. Máximo de 9 caracteres. | | `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. | #### Atributos de `borrower` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do sacado. Máximo de 255 caracteres. | | `document_number` | string | obrigatório | CPF ou CNPJ do sacado. | | `person_type` | string | obrigatório | Tipo de pessoa. | | `email` | string | opcional | E-mail do sacado. Máximo de 255 caracteres. | | `address` | object | obrigatório | Endereço do sacado. Veja [Atributos de `address`](#atributos-de-address). | | `phone` | object | opcional | Telefone do sacado. Veja [Atributos de `phone`](#atributos-de-phone). | **Enumeradores de `person_type`:** | Valor | Descrição | |---|---| | `natural_person` | Pessoa Física. Quando informado, incluir o objeto `natural_person` dentro de `borrower`. Veja [Atributos de `natural_person`](#atributos-de-natural_person). | | `legal_person` | Pessoa Jurídica. Quando informado, incluir o objeto `legal_person` dentro de `borrower`. Veja [Atributos de `legal_person`](#atributos-de-legal_person). | #### Atributos de `address` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `street` | string | obrigatório | Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres. | | `number` | string | opcional | Número do endereço. Máximo de 40 caracteres. | | `neighborhood` | string | opcional | Bairro. Máximo de 255 caracteres. | | `city` | string | opcional | Cidade. Máximo de 255 caracteres. | | `uf` | string | opcional | Sigla do estado. 2 caracteres. | | `complement` | string | opcional | Complemento. Máximo de 255 caracteres. | | `postal_code` | string | obrigatório | CEP. 9 caracteres (com hífen). | | `country` | string | opcional | País no formato ISO 3166-1 alpha-3. 3 caracteres. | #### Atributos de `phone` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `area_code` | string | obrigatório | Código de área (DDD). 2 dígitos. | | `number` | string | obrigatório | Número de telefone. Até 9 dígitos. | #### Atributos de `natural_person` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `birthdate` | string | opcional | Data de nascimento no formato `YYYY-MM-DD`. | | `gender` | string | opcional | Gênero. | | `mother_name` | string | opcional | Nome da mãe. Máximo de 255 caracteres. | **Enumeradores de `gender`:** | Valor | Descrição | |---|---| | `male` | Masculino. | | `female` | Feminino. | #### Atributos de `legal_person` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `foundation_date` | string | opcional | Data de fundação no formato `YYYY-MM-DD`. | | `activity_code` | string | obrigatório | Código de atividade no formato `11.11-1-11`. | | `annual_revenues` | integer | opcional | Receita anual em centavos. | | `representatives` | array | opcional | Lista de representantes legais. Veja [Atributos de `representatives`](#atributos-de-representatives). | #### Atributos de `representatives` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | obrigatório | Nome do representante. Máximo de 255 caracteres. | | `document_number` | string | obrigatório | CPF ou CNPJ do representante. | | `email` | string | opcional | E-mail do representante. Máximo de 255 caracteres. | | `phone` | object | opcional | Telefone. Mesma estrutura de [Atributos de `phone`](#atributos-de-phone). | | `address` | object | opcional | Endereço. Mesma estrutura de [Atributos de `address`](#atributos-de-address). | | `person_type` | string | obrigatório | Tipo de pessoa (`natural_person` ou `legal_person`). | | `representative_type` | string | opcional | Tipo do representante. Máximo de 50 caracteres. | #### Atributos de `bankslip` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `our_number` | object | opcional | Dados do nosso número. Aplicável apenas quando o nosso número é emitido pelo cliente. Veja [Atributos de `our_number`](#atributos-de-our_number). | #### Atributos de `our_number` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `number` | number | obrigatório | Nosso número. Número bancário para cobrança com registro. 1 a 11 caracteres numéricos. | | `digit` | string | obrigatório | Dígito verificador de auto conferência do nosso número. 1 caractere alfanumérico. | #### Atributos de `delay` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `fine` | object | opcional | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). | | `interest` | object | opcional | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). | #### Atributos de `fine` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `fine_type` | string | obrigatório | Tipo da multa. | | `percentage_value` | number | condicional | Valor da multa quando `fine_type` for `percentage`. De 0 a 1, representando 0% a 100%. Até 2 casas decimais. | | `amount` | number | condicional | Valor fixo da multa quando `fine_type` for `fixed`. Até 2 casas decimais. | **Enumeradores de `fine_type`:** | Valor | Descrição | |---|---| | `percentage` | Multa percentual sobre o valor da parcela. | | `fixed` | Valor fixo de multa. | #### Atributos de `interest` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `method` | string | obrigatório | Método do juros de mora. | | `pre_fixed` | object | obrigatório | Dados da taxa pré-fixada. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). | **Enumeradores de `method`:** | Valor | Descrição | |---|---| | `compound` | Juros de mora composto. | | `simple` | Juros de mora simples. | | `pre_fixed` | Juros de mora pré-fixado. | #### Atributos de `pre_fixed` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `daily_rate` | number | condicional | Taxa diária. Informar quando `method` for `pre_fixed`. Para 1%, informar `0.01`. Até 8 casas decimais. | | `calendar_base` | string | obrigatório | Base de cálculo utilizada. | **Enumeradores de `calendar_base`:** | Valor | Descrição | |---|---| | `workdays` | Base de cálculo em dias úteis (252). | | `calendar_365` | Base de cálculo em 365 dias. | | `calendar_360` | Base de cálculo em 360 dias. | ## Response STATUS 201 ```json title="Response Body" { "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2", "status": "pending_eligibility" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). | | `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `discounted_credit_right`. | | `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. | ## Possíveis erros STATUS 404 **Lote não encontrado** O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto. ```json { "title": "Assignment not found", "description": "Assignment not found", "translation": "Lote não encontrado", "code": "TRC000018" } ``` STATUS 404 **Tipo de ativo não existe** O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `cte`). ```json { "title": "Asset type does not exist", "description": "Asset type 'invalid_asset_type' does not exist", "translation": "Tipo do ativo 'invalid_asset_type' nao existe", "code": "TRC000015" } ``` STATUS 400 **Tipo de ativo incompatível com o lote** O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada. ```json { "title": "Invalid asset type configuration", "description": "This assignment can not receive this asset type: cte", "translation": "Esse lote não pode receber esse tipo de ativo: cte", "code": "TRC000025" } ``` STATUS 400 **Lote fechado para inserção** O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos. ```json { "title": "Assignment is closed", "description": "Assignment is closed to insert new assets", "translation": "Lote esta fechado para inserir novos ativos", "code": "TRC000022" } ``` STATUS 400 **Chave de acesso do CT-e ausente** O campo `access_key` dentro de `invoice` é obrigatório para ativos do tipo `cte`. Inclua a chave de acesso do CT-e no request body. ```json { "title": "Access Key Required", "description": "Access key is required for cte asset type", "translation": "Chave de acesso é obrigatória para o tipo de ativo cte", "code": "TRC000134" } ``` STATUS 400 **Chave de acesso do CT-e inválida** A `access_key` informada não corresponde a um CT-e válido. Os caracteres de posição 20 a 22 da chave de acesso devem ser `57` ou `67`, que identificam o modelo do documento fiscal CT-e. ```json { "title": "Invalid CTE Access Key", "description": "Access key is not valid for a CTE document", "translation": "Chave de acesso não é válida para um documento CT-e", "code": "TRC000133" } ``` STATUS 400 **External ID duplicado** Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente. ```json { "title": "Already Exist This External Id", "description": "Already exist an asset with this External Id", "translation": "Ja existe um ativo com esse External Id", "code": "TRC000054" } ``` ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade. 2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade. --- # Criação de Ativo — Contrato Descontado URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract Endpoint para inserir um ativo do tipo **Contrato Descontado** em um lote de cessão. Este tipo de ativo representa uma parcela de um contrato de crédito cujo direito creditório será cedido ao fundo. :::tip Onde estou no fluxo? Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::caution Atenção O campo `external_id` do direito creditório deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset MÉTODO POST ```json title="Request Body" { "asset_type": "discounted_contract", "total_purchase_value": 1231.21, "discounted_credit_right": { "external_id": "mdf27za1-ra5f-46c0-a32f-fb909884dbb2", "originator_document_number": "46.282.154/0001-14", "face_value": 1231.21, "maturity_date": "2025-12-10", "installment_number": 1, "borrower": { "name": "Natália Nascimento", "document_number": "19.845.976/0001-93", "person_type": "natural_person", "email": "natália.nascimento@yopmail.com", "address": { "street": "Gilberto Sabino", "number": "215", "neighborhood": "Pinheiros", "city": "São Paulo", "postal_code": "05425-020", "uf": "SP", "country": "BRA" }, "phone": { "area_code": "11", "number": "36360268" }, "natural_person": { "mother_name": "Lívia Santos", "birthdate": "2001-01-05" } }, "contract": { "number_of_installments": 5, "total_face_value": 1231.21, "number": "958431587", "issue_date": "2023-10-10" } } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_type` | string | obrigatório | Tipo do ativo. Para contrato descontado, informar `discounted_contract`. | | `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. | | `discounted_credit_right` | object | obrigatório | Dados do direito creditório. Veja [Atributos de `discounted_credit_right`](#atributos-de-discounted_credit_right). | #### Atributos de `discounted_credit_right` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. | | `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. | | `face_value` | number | obrigatório | Valor de face. Até 8 casas decimais. | | `maturity_date` | string | obrigatório | Data de vencimento da parcela no formato `YYYY-MM-DD`. | | `installment_number` | integer | opcional | Número da parcela. | | `borrower` | object | obrigatório | Dados do sacado. Consulte os [Atributos de `borrower`](/documentation/iaas/negociacao_recebiveis/asset/criacao_co#atributos-de-borrower) na página de Criação de Ativo — CCB. | | `contract` | object | obrigatório | Dados do contrato. Veja [Atributos de `contract`](#atributos-de-contract). | #### Atributos de `contract` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `number_of_installments` | integer | obrigatório | Número total de parcelas do contrato. | | `total_face_value` | number | obrigatório | Valor de face total do contrato. Até 2 casas decimais. | | `number` | string | obrigatório | Número do contrato. Máximo de 50 caracteres. | | `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. | ## Response STATUS 201 ```json title="Response Body" { "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "mdf27za1-ra5f-46c0-a32f-fb909884dbb2", "status": "pending_eligibility" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). | | `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `discounted_credit_right`. | | `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. | ## Possíveis erros STATUS 404 **Lote não encontrado** O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto. ```json { "title": "Assignment not found", "description": "Assignment not found", "translation": "Lote não encontrado", "code": "TRC000018" } ``` STATUS 404 **Tipo de ativo não existe** O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `discounted_contract`). ```json { "title": "Asset type does not exist", "description": "Asset type 'invalid_asset_type' does not exist", "translation": "Tipo do ativo 'invalid_asset_type' nao existe", "code": "TRC000015" } ``` STATUS 400 **Tipo de ativo incompatível com o lote** O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada. ```json { "title": "Invalid asset type configuration", "description": "This assignment can not receive this asset type: discounted_contract", "translation": "Esse lote não pode receber esse tipo de ativo: discounted_contract", "code": "TRC000025" } ``` STATUS 400 **Lote fechado para inserção** O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos. ```json { "title": "Assignment is closed", "description": "Assignment is closed to insert new assets", "translation": "Lote esta fechado para inserir novos ativos", "code": "TRC000022" } ``` STATUS 400 **External ID duplicado** Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente. ```json { "title": "Already Exist This External Id", "description": "Already exist an asset with this External Id", "translation": "Ja existe um ativo com esse External Id", "code": "TRC000054" } ``` ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade. 2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade. --- # Criação de Ativo — Duplicata URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata Endpoint para inserir um ativo do tipo **Duplicata** em um lote de cessão. Existem dois subtipos aceitos: **Duplicata Mercantil** (`duplicata_mercantil`) — vinculada a uma nota fiscal de venda de mercadorias — e **Duplicata de Serviços** (`duplicata_servicos`) — vinculada a uma nota fiscal de prestação de serviços. :::info Diferença entre os tipos Ambos os tipos utilizam a mesma estrutura de request body. A principal diferença é que a **duplicata mercantil** não exige envio de documentos após a elegibilidade, enquanto a **duplicata de serviços** exige. Consulte a página de [Inserção de Documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) para mais detalhes. ::: :::tip Onde estou no fluxo? Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::caution Atenção O campo `external_id` do direito creditório deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset MÉTODO POST ```json title="Request Body" { "asset_type": "duplicata_mercantil", "total_purchase_value": 1231.21, "discounted_credit_right": { "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2", "originator_document_number": "46.282.154/0001-14", "maturity_date": "2023-12-10", "order_number": "18923619954796912", "face_value": 1023.01, "person_type": "natural_person", "borrower": { "name": "Natália Nascimento", "document_number": "805.359.140-08", "person_type": "natural_person", "email": "natália.nascimento@yopmail.com", "address": { "street": "Gilberto Sabino", "number": "215", "neighborhood": "Pinheiros", "city": "São Paulo", "postal_code": "05425-020", "uf": "SP", "country": "BRA" }, "phone": { "area_code": "11", "number": "36360268" }, "natural_person": { "mother_name": "Lívia Santos", "birthdate": "2001-01-05" } }, "participant_control_number": "ICX841HWCPUGU4U101XPLDW8D", "bankslip": { "our_number": { "number": 2, "digit": "P" } }, "delay": { "fine": { "fine_type": "percentage", "percentage_value": 0.0 }, "interest": { "method": "pre_fixed", "pre_fixed": { "daily_rate": 0.0, "calendar_base": "calendar_360" } } }, "invoice": { "access_key": "69037229347091328617032722238810300308237163", "total_value": 1231.21, "serie": "123", "number": "958431587", "issue_date": "2023-10-10" } } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_type` | string | obrigatório | Tipo do ativo. Valores aceitos: `duplicata_mercantil` ou `duplicata_servicos`. | | `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. | | `discounted_credit_right` | object | obrigatório | Dados do direito creditório. Veja [Atributos de `discounted_credit_right`](#atributos-de-discounted_credit_right). | #### Atributos de `discounted_credit_right` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. | | `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. | | `maturity_date` | string | obrigatório | Data de vencimento no formato `YYYY-MM-DD`. | | `order_number` | string | obrigatório | Número do pedido. Máximo de 45 caracteres. | | `face_value` | number | obrigatório | Valor de face. Até 8 casas decimais. | | `person_type` | string | opcional | Tipo de pessoa do sacado (`natural_person` ou `legal_person`). | | `borrower` | object | obrigatório | Dados do sacado. Consulte os [Atributos de `borrower`](/documentation/iaas/negociacao_recebiveis/asset/criacao_co#atributos-de-borrower) na página de Criação de Ativo — CCB. | | `participant_control_number` | string | opcional | Número de controle do participante no sistema do parceiro. Máximo de 50 caracteres alfanuméricos. | | `bankslip` | object | opcional | Dados do boleto. Veja [Atributos de `bankslip`](#atributos-de-bankslip). | | `delay` | object | opcional | Dados de multa e juros por atraso. Consulte os [Atributos de `delay`](/documentation/iaas/negociacao_recebiveis/asset/criacao_co#atributos-de-delay) na página de Criação de Ativo — CCB. | | `invoice` | object | obrigatório | Dados da nota fiscal. Veja [Atributos de `invoice`](#atributos-de-invoice). | #### Atributos de `bankslip` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `our_number` | object | opcional | Dados do nosso número. Aplicável apenas quando o nosso número é emitido pelo cliente. Veja [Atributos de `our_number`](#atributos-de-our_number). | #### Atributos de `our_number` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `number` | number | obrigatório | Nosso número. Número bancário para cobrança com registro. 1 a 11 caracteres numéricos. | | `digit` | string | obrigatório | Dígito verificador de auto conferência do nosso número. 1 caractere alfanumérico. | #### Atributos de `invoice` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `access_key` | string | obrigatório | Chave de acesso da nota fiscal. 44 caracteres. | | `total_value` | number | opcional | Valor total da nota fiscal. Até 2 casas decimais. | | `serie` | string | obrigatório | Número de série da nota fiscal. Máximo de 3 caracteres. | | `number` | string | obrigatório | Número da nota fiscal. Máximo de 50 caracteres. | | `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. | ## Response STATUS 201 ```json title="Response Body" { "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2", "status": "pending_eligibility" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). | | `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `discounted_credit_right`. | | `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. | ## Possíveis erros STATUS 404 **Lote não encontrado** O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto. ```json { "title": "Assignment not found", "description": "Assignment not found", "translation": "Lote não encontrado", "code": "TRC000018" } ``` STATUS 404 **Tipo de ativo não existe** O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `duplicata_mercantil`, `duplicata_servicos`). ```json { "title": "Asset type does not exist", "description": "Asset type 'invalid_asset_type' does not exist", "translation": "Tipo do ativo 'invalid_asset_type' nao existe", "code": "TRC000015" } ``` STATUS 400 **Tipo de ativo incompatível com o lote** O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada. ```json { "title": "Invalid asset type configuration", "description": "This assignment can not receive this asset type: duplicata_mercantil", "translation": "Esse lote não pode receber esse tipo de ativo: duplicata_mercantil", "code": "TRC000025" } ``` STATUS 400 **Lote fechado para inserção** O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos. ```json { "title": "Assignment is closed", "description": "Assignment is closed to insert new assets", "translation": "Lote esta fechado para inserir novos ativos", "code": "TRC000022" } ``` STATUS 400 **External ID duplicado** Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente. ```json { "title": "Already Exist This External Id", "description": "Already exist an asset with this External Id", "translation": "Ja existe um ativo com esse External Id", "code": "TRC000054" } ``` ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade. 2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade. --- # Inserção de Ativo para Recompra URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset Endpoint para inserir um ativo que será **recomprado** pelo cedente em um lote de substituição. A recompra ocorre quando o cedente precisa retirar um ativo da carteira do fundo, substituindo-o por novos ativos. :::info Lotes de substituição Este endpoint é utilizado exclusivamente em **lotes de substituição**. O fluxo de substituição difere do fluxo de cessão padrão por incluir um passo adicional: a inserção dos ativos a serem recomprados, antes da inserção dos novos ativos. Para mais detalhes, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api). ::: :::tip Onde estou no fluxo? Este é o **2º passo** do fluxo de substituição. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos de recompra, insira os [novos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) que substituirão os recomprados. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/repurchased_asset MÉTODO POST ```json title="Request Body" { "asset_type": "duplicata_mercantil", "external_id": "88c2304e-8eb3-44e0-acb4-25811ae20cf1", "assignor_document_number": "66.642.277/0001-26", "repurchase_value": 1000.00, "settlement_type": "asset_settlement" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_type` | string | obrigatório | Tipo do ativo que será recomprado (ex: `ccb`, `duplicata_mercantil`, `discounted_contract`). | | `external_id` | string | obrigatório | Identificador externo do ativo que será recomprado. Deve ser o mesmo `external_id` utilizado quando o ativo foi originalmente inserido. | | `assignor_document_number` | string | obrigatório | CPF ou CNPJ do cedente que originalmente cedeu o ativo ao fundo. | | `repurchase_value` | number | obrigatório | Valor de recompra do ativo. Até 2 casas decimais. | | `settlement_type` | string | obrigatório | Modalidade de substituição [settlement_type](#settlement-type). | ### Settlement Type | Enumerador | descrição | |---|---| | `asset_settlement` | Substituição total do ativo. | | `asset_amortization` | Substituição parcial do ativo. | ## Response STATUS 201 ```json title="Response Body" { "repurchased_asset_key": "a6115a17-8b4d-49a3-aed6-47c9574eab88", "asset_type": "duplicata_mercantil", "asset_key": "65bbce6d-e0b4-4471-a702-e0ced4542e5b", "external_id": "88c2304e-8eb3-44e0-acb4-25811ae20cf1", "assignor": { "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "document_number": "66.642.277/0001-26", "name": "Cedente Exemplo Ltda" }, "status": "pending_eligibility", "assignment": { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "name": "CESSÃO #12345", "assignment_number": "00012345", "assignment_date": "2024-04-01", "status": "pending_assets_insertion", "origin_type": "client" }, "repurchase_value": 1000.00 } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `repurchased_asset_key` | string | Identificador único do registro de recompra gerado pela QI Tech (UUID). | | `asset_type` | string | Tipo do ativo recomprado. | | `asset_key` | string | Identificador único do ativo original na carteira do fundo (UUID). | | `external_id` | string | Identificador externo do ativo, conforme informado na requisição. | | `assignor` | object | Dados do cedente que originalmente cedeu o ativo. | | `status` | string | Status atual do ativo de recompra. | | `assignment` | object | Dados do lote de substituição ao qual o ativo de recompra pertence. Consulte os [atributos do lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao) na página de Recuperação do Lote. | | `repurchase_value` | number | Valor de recompra do ativo, conforme informado na requisição. | #### Atributos de `assignor` | Campo | Tipo | Descrição | |---|---|---| | `assignor_key` | string | Identificador único do cedente (UUID). | | `document_number` | string | CPF ou CNPJ do cedente. | | `name` | string | Nome do cedente. | ## Possíveis erros STATUS 404 **Lote não encontrado** ```json { "title": "Assignment not found", "description": "Assignment not found", "translation": "Lote não encontrado", "code": "TRC000018" } ``` STATUS 404 **Ativo não encontrado** ```json { "title": "Asset not found", "description": "Asset not found", "translation": "Ativo não foi encontrado", "code": "TRC000020" } ``` STATUS 400 **Lote fechado para inserção** ```json { "title": "Assignment is closed", "description": "Assignment is closed to insert new assets", "translation": "Lote esta fechado para inserir novos ativos", "code": "TRC000022" } ``` ## Próximos passos Após inserir os ativos de recompra, o fluxo continua com: 1. **[Inserção dos novos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** — adicione os ativos que substituirão os recomprados. 2. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada novo ativo. 3. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade. --- # Inserção de Documentos do Ativo URL: /documentation/iaas/negociacao_recebiveis/asset/documents Endpoint para enviar os documentos obrigatórios associados a um ativo do lote de cessão. Os documentos devem ser enviados em formato PDF codificado em Base64. :::tip Onde estou no fluxo? O envio de documentos ocorre após a inserção do ativo e após o ativo ter sido aprovado na elegibilidade individual. Você receberá um [webhook](/documentation/iaas/negociacao_recebiveis/asset/webhooks) com o status `pending_documentation` indicando que o ativo está aguardando documentação. ::: :::info Quais ativos exigem documentos? - **CCB** (`ccb`): o envio de documentos é sempre obrigatório. - **Duplicata de serviços** (`duplicata_servicos`): o envio de documentos é obrigatório. - **Duplicata mercantil** (`duplicata_mercantil`): o envio de documentos **não** é obrigatório — a documentação é gerada automaticamente pelo sistema a partir dos dados da nota fiscal. - **Contrato descontado** (`discounted_contract`): consulte a configuração do produto no Contrato de Cessão. O ativo só avança para o status `pre_approved` depois que todos os documentos exigidos forem enviados. ::: :::info Formato do documento O arquivo enviado deve ser um **PDF válido** codificado em Base64. Outros formatos serão rejeitados com erro. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}/document MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID). | | `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). | | `assignment_external_id` | string | Identificador externo do lote, informado na criação do lote. | | `asset_external_id` | string | O `external_id` informado na criação do ativo. | ```json title="Request Body" { "document_type": "ccb", "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `document_type` | string | obrigatório | Tipo do documento que está sendo enviado. Os valores aceitos são os configurados na configuração de cessão utilizada — veja os enumeradores abaixo. | | `document_b64` | string | obrigatório | Conteúdo do arquivo PDF codificado em Base64. | **Enumeradores de `document_type`:** | Valor | Descrição | |---|---| | `ccb` | Cédula de Crédito Bancário — usado em ativos do tipo CCB. | | `duplicata_servicos` | Duplicata de serviços — usado em ativos de duplicata de serviços. | | `contract` | Contrato parcelado — usado em ativos do tipo `contract`. | | `vehicle_reservation_receipt` | Comprovante de reserva do veículo — usado em operações de crédito com garantia de veículo. É um documento **pós-cessão**. | :::info Dois momentos de envio de documento Este endpoint atende a **dois momentos distintos** do fluxo, e o que muda entre eles é apenas o status do ativo: - **Antes da cessão.** O ativo entra em `pending_documentation` depois de aprovado na elegibilidade individual e aguarda os documentos configurados como obrigatórios do produto. Com todos enviados, ele avança para `pre_approved`. - **Depois da cessão.** Se a configuração de cessão exigir documentos pós-cessão, o ativo entra em `pending_after_assignment_documentation` após a liquidação do lote. É aqui que entra o **comprovante de reserva do veículo** (`vehicle_reservation_receipt`) das operações com garantia de veículo. Com todos enviados, o ativo avança para `completed`. **Este segundo momento não é notificado por webhook** — diferente do primeiro: acompanhe pela [recuperação do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos) e trate o `completed` como confirmação. A lista de documentos exigidos em cada momento é definida por produto e vem na resposta da [configuração de cessão](/documentation/iaas/negociacao_recebiveis/listagem), nos campos `required_documents` (antes da cessão) e `after_assignment_required_documents` (depois da cessão). Enviar um `document_type` que existe no sistema mas não está configurado para aquela cessão devolve `TRC000032`; enviar um valor que o sistema não conhece devolve `TRC000033`. ::: ## Response STATUS 201 ```json title="Response Body" { "document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `document_key` | string | Identificador único do documento gerado pela QI Tech (UUID). | ## Possíveis erros STATUS 404 **Ativo não encontrado** O `asset_external_id` informado na URL não corresponde a nenhum ativo do lote. Verifique se o identificador está correto e se o ativo pertence ao lote informado. ```json { "title": "Asset not found", "description": "Asset not found", "translation": "Ativo não foi encontrado", "code": "TRC000020" } ``` STATUS 400 **Tipo de documento inválido para esta configuração** O valor informado em `document_type` não corresponde a nenhum tipo de documento configurado para esta cessão. Verifique quais tipos de documento são aceitos na configuração de cessão utilizada. ```json { "title": "Invalid documents", "description": "Required documents type are invalid", "translation": "Tipo de Documentos requeridos sao inválidos", "code": "TRC000032" } ``` STATUS 400 **Tipo de documento não reconhecido** O tipo de documento informado não é reconhecido pelo sistema. Verifique se o valor de `document_type` está correto. ```json { "title": "Invalid document type", "description": "Invalid document type", "translation": "Tipo de documento invalido", "code": "TRC000033" } ``` STATUS 400 **Formato do documento inválido** O arquivo enviado não está em formato PDF válido ou a codificação Base64 está incorreta. Verifique se o arquivo é um PDF válido e se a codificação Base64 foi feita corretamente. ```json { "title": "Invalid document format", "description": "Invalid document format", "translation": "Formato do documento invalido", "code": "TRC000034" } ``` STATUS 400 **Status do ativo inválido para envio de documento** O ativo não está em um status que permita o envio de documentos. Normalmente isso significa que o ativo ainda não foi aprovado na elegibilidade ou já foi descartado. ```json { "title": "Invalid operation", "description": "Asset is not in a valid status to receive documents", "translation": "Ativo não está em status válido para receber documentos", "code": "TRC000024" } ``` ## Próximos passos Após enviar todos os documentos exigidos, o fluxo continua com: 1. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos e documentos foram inseridos para que o lote siga para a análise de elegibilidade. --- # Consulta de Ativos do Lote URL: /documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos Endpoints para consultar os ativos inseridos em um lote de cessão. Existem dois modos de consulta: a **listagem paginada** de todos os ativos de um lote, e a **consulta individual** de um ativo específico. :::tip Quando utilizar Utilize estes endpoints para acompanhar o status dos ativos após a inserção, verificar quais foram aprovados ou reprovados na elegibilidade, e consultar os motivos de reprovação quando houver. A listagem aceita **filtros** — inclusive por status — o que permite consultar diretamente apenas os ativos reprovados, sem precisar paginar o lote inteiro. Veja [Consultar apenas os ativos reprovados](#consultar-apenas-os-ativos-reprovados). ::: ## Listagem de ativos Retorna a lista paginada dos ativos de um lote, com suporte a filtros. ### Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets MÉTODO GET ### Query params Todos os filtros são opcionais e podem ser combinados entre si. Quando nenhum filtro é informado, a rota devolve todos os ativos do lote. | Parâmetro | Tipo | Padrão | Descrição | |---|---|---|---| | `page` | integer | `0` | Número da página (começa em 0). | | `limit` | integer | `10` | Quantidade de registros por página. Máximo: `100`. | | `status` | string | — | Filtra por um status de ativo. Aceita **um único valor**, que deve ser um dos [enumeradores de status](#enumeradores-de-status-do-ativo). Use `denied` para obter apenas os ativos reprovados. | | `external_id` | string | — | Filtra pelo `external_id` do ativo informado na criação. | | `contract_number` | string | — | Filtra pelo número do contrato da operação. | | `borrower_document_number` | string | — | Filtra pelo CPF/CNPJ do devedor (sacado ou tomador, conforme o tipo de ativo). | | `purchase_value_min` | number | — | Valor mínimo de compra do ativo (inclusive). | | `purchase_value_max` | number | — | Valor máximo de compra do ativo (inclusive). | | `maturity_date_start` | string (`AAAA-MM-DD`) | — | Data de vencimento inicial do intervalo. | | `maturity_date_end` | string (`AAAA-MM-DD`) | — | Data de vencimento final do intervalo. | ```python title="Exemplo — listagem simples" GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?page=0&limit=10 ``` ```python title="Exemplo — filtros combinados" GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?status=denied&limit=100&maturity_date_start=2024-01-01&maturity_date_end=2024-12-31 ``` :::warning Status inválido Se o valor enviado em `status` não corresponder a nenhum enumerador válido, a requisição retorna erro. Consulte a [tabela de enumeradores](#enumeradores-de-status-do-ativo) antes de montar o filtro. ::: ### Response STATUS 200 ```json title="Response Body" { "data": [ { "asset_key": "f4348106-01c4-4c59-a261-7c09db811c47", "external_id": "e292656f-f7fb-44dc-96f3-667c36c88442", "total_purchase_value": 1231.21, "asset_type": "duplicata_mercantil", "status": "denied", "duration": 9177, "denied_by": "document", "denial_reason": "Invalid documents" } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de objetos de ativo. Veja tabela abaixo. | | `page` | integer | Número da página atual. | | `limit` | integer | Quantidade de registros por página. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada ativo (objetos dentro de `data`) | Campo | Tipo | Descrição | |---|---|---| | `asset_key` | string | Identificador único do ativo (UUID). | | `external_id` | string | Chave externa fornecida pelo parceiro na criação. | | `total_purchase_value` | number | Valor total de compra do ativo. | | `asset_type` | string | Tipo do ativo (ex: `ccb`, `duplicata_mercantil`, `discounted_contract`). | | `status` | string | Status atual do ativo. Consulte a [tabela de status](#enumeradores-de-status-do-ativo) abaixo. | | `duration` | integer | Duração do ativo em dias. Pode não estar presente se ainda não foi calculada. | | `denied_by` | string | Origem da reprovação. Presente apenas quando o ativo foi reprovado. Consulte a [tabela de origens](#origens-de-reprovação-denied_by). | | `denial_reason` | string | Descrição do motivo da reprovação. Presente apenas quando o ativo foi reprovado. | :::info Objetos aninhados Dependendo do tipo de ativo, a resposta incluirá o objeto `credit_operation` (para CCBs) ou `discounted_credit_right` (para duplicatas e contratos descontados) com todos os dados da operação de crédito. ::: ## Consultar apenas os ativos reprovados Este é o uso mais comum da listagem: descobrir **quais contratos do lote foram reprovados**, para refletir a decisão da QI Tech no controle interno do parceiro e decidir se algum ativo precisa ser [removido do lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). Basta informar `status=denied`: ```python title="Request" GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?status=denied&limit=100 ``` A resposta traz somente os ativos reprovados, cada um com `denied_by` (a origem da reprovação) e `denial_reason` (a descrição): ```json title="Response Body" { "data": [ { "asset_key": "f4348106-01c4-4c59-a261-7c09db811c47", "external_id": "e292656f-f7fb-44dc-96f3-667c36c88442", "total_purchase_value": 1231.21, "asset_type": "ccb", "status": "denied", "duration": 9177, "denied_by": "eligibility", "denial_reason": "Prazo do contrato acima do permitido pela política do fundo" } ], "limit": 100, "page": 0, "is_last_page": true } ``` :::tip Recomendações de uso - Use `limit=100` (o máximo permitido) para reduzir o número de páginas e pagine até `is_last_page` ser `true`. - Consulte após receber o webhook [`pending_manager_approval`](/documentation/iaas/negociacao_recebiveis/assignment/webhooks#pendente-aprovação-do-gestor) — nesse momento a análise de elegibilidade de todos os ativos já foi concluída e a lista de reprovados está estável. - Para o inverso — os ativos aprovados na elegibilidade — use `status=pre_approved`. ::: ### Origens de reprovação (`denied_by`) | Valor | Significado | |---|---| | `eligibility` | Reprovado na análise de elegibilidade. | | `document` | Reprovado na validação dos documentos enviados. | | `inconsistency` | Reprovado por inconsistência nos dados da operação identificada na validação. | | `invalid_invoice` | Reprovado na validação da nota fiscal. | | `registry` | Reprovado no processo de registro do ativo. | | `term` | Reprovado na etapa do Termo de Cessão. | | `manager` | Reprovado/removido por ação do gestor do fundo. | | `consultant` | Reprovado/removido por ação do consultor. | | `assignor` | Reprovado/removido por ação do cedente. | | `accounting_close` | Reprovado por fechamento contábil do fundo. | | `denial_file` | Reprovado por arquivo de reprovação processado em lote. | ## Consulta de ativo específico Retorna os dados completos de um ativo específico do lote. ### Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `asset_external_id` | string | O `external_id` informado na criação do ativo. | ### Response STATUS 200 ```json title="Response Body" { "asset_key": "074f8786-447f-4524-9f4f-a5cf8a890bb4", "external_id": "acfbc329-4e67-40ea-bd8d-5debdaebe144", "total_purchase_value": 1231.21, "asset_type": "duplicata_mercantil", "status": "denied", "duration": 9184, "denied_by": "document", "denial_reason": "Invalid documents" } ``` ### Atributos da resposta A resposta possui a mesma estrutura de cada objeto do array `data` retornado pela [listagem de ativos](#atributos-de-cada-ativo-objetos-dentro-de-data), acrescida do objeto completo da operação de crédito (`credit_operation` ou `discounted_credit_right`, dependendo do tipo de ativo). ## Enumeradores de status do ativo Qualquer um dos valores abaixo pode ser usado no filtro `status` da listagem. | Status | Descrição | |---|---| | `created` | Ativo criado, ainda não submetido à análise. | | `pending_eligibility` | Ativo inserido, aguardando análise de elegibilidade. | | `pending_documentation` | Ativo aprovado na elegibilidade, aguardando envio de documentos. | | `pending_invoice_validation` | Aguardando validação da nota fiscal. | | `pre_approved` | Ativo pré-aprovado na elegibilidade individual. | | `pending_registry` | Aguardando início do registro do ativo. | | `pending_external_registry` | Aguardando registro em câmara externa. | | `sending_to_registry` | Em envio para a câmara de registro. | | `waiting_registry` | Registro submetido, aguardando retorno da câmara. | | `pending_formalization` | Ativo formalizado e apto a seguir no lote. | | `registry_denied` | Registro do ativo recusado pela câmara. | | `sending_to_wallet` | Em processo de encarteiramento na carteira do fundo. | | `denied` | Ativo reprovado. Consulte `denied_by` para a origem da reprovação. | | `discarded` | Ativo descartado do lote. | | `completed` | Ativo encarteirado na carteira do fundo. | --- # Remoção de Ativos do Lote URL: /documentation/iaas/negociacao_recebiveis/asset/remocao_ativos Processo para retirar ativos de um lote que está aguardando aprovação do gestor. A remoção envolve **3 passos sequenciais**: reabrir o lote, remover os ativos desejados e fechar o lote novamente. :::info Pré-requisito A remoção de ativos só é possível quando o lote está no status `pending_manager_approval` (aguardando aprovação do gestor). Com o lote nesse status, é necessário reabri-lo antes de realizar qualquer alteração nos ativos. ::: ## Passo 1 — Reabrir o lote Altere o status do lote para `pending_assets_insertion` para permitir a remoção de ativos. ### Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id} MÉTODO PUT ```json title="Request Body" { "assignment_status": "pending_assets_insertion" } ``` #### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `assignment_status` | string | obrigatório | Status para o qual o lote será atualizado. Para reabrir, envie `pending_assets_insertion`. | ### Response STATUS 200 ```json title="Response Body" { "assignment_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a", "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36", "status": "pending_assets_insertion", "number_of_approved_assets": 10, "assignment_total_value": 1234.99 } ``` #### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `assignment_key` | string | Identificador único do lote (UUID). | | `external_id` | string | Chave externa do lote fornecida pelo parceiro. | | `status` | string | Novo status do lote: `pending_assets_insertion`. | | `number_of_approved_assets` | integer | Quantidade de ativos aprovados no lote. | | `assignment_total_value` | number | Valor total da cessão em reais. | ## Passo 2 — Remover ativos Com o lote reaberto, remova cada ativo desejado alterando seu status para `denied`. Realize uma requisição para cada ativo a ser removido. ### Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `asset_external_id` | string | O `external_id` do ativo que será removido. | ```json title="Request Body" { "asset_status": "denied" } ``` #### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_status` | string | obrigatório | Status para o qual o ativo será atualizado. Para remover, envie `denied`. | ### Response STATUS 200 ```json title="Response Body" { "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36", "status": "denied" } ``` #### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | Chave externa do ativo. | | `status` | string | Novo status do ativo: `denied`. | ## Passo 3 — Fechar o lote novamente Após remover os ativos desejados, feche o lote para que ele siga novamente para aprovação do gestor. ### Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id} MÉTODO PUT ```json title="Request Body" { "assignment_status": "completed_assets_insertion" } ``` #### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `assignment_status` | string | obrigatório | Status para o qual o lote será atualizado. Para fechar, envie `completed_assets_insertion`. | ### Response STATUS 200 ```json title="Response Body" { "assignment_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a", "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36", "status": "completed_assets_insertion", "number_of_approved_assets": 10, "assignment_total_value": 1234.99 } ``` #### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `assignment_key` | string | Identificador único do lote (UUID). | | `external_id` | string | Chave externa do lote fornecida pelo parceiro. | | `status` | string | Novo status do lote: `completed_assets_insertion`. | | `number_of_approved_assets` | integer | Quantidade de ativos aprovados remanescentes. | | `assignment_total_value` | number | Valor total atualizado da cessão em reais. | Após fechar o lote, ele seguirá novamente para aprovação do gestor e continuará o fluxo normalmente. ## Possíveis erros STATUS 404 **Ativo não encontrado** O `asset_external_id` informado na URL não corresponde a nenhum ativo do lote. Verifique se o identificador está correto e se o ativo pertence ao lote informado. ```json { "title": "Asset not found", "description": "Asset not found", "translation": "Ativo não foi encontrado", "code": "TRC000020" } ``` STATUS 400 **Ativo não pode ser removido** O ativo informado não pode ser negado/removido no status atual. Isso pode ocorrer quando o ativo já foi descartado ou quando o lote não está aberto para modificação. ```json { "title": "Cant deny this asset.", "description": "This asset cant be denied.", "translation": "Esse ativo não pode ser negado", "code": "TRC000086" } ``` STATUS 400 **Status do lote inválido para esta operação** O lote não está em um status que permita esta operação. Para remover ativos, o lote precisa estar no status `pending_assets_insertion`. Verifique o status atual do lote e, se necessário, reabra-o primeiro (Passo 1). ```json { "title": "Invalid assignment status", "description": "Assignment is not in a valid status for this operation", "translation": "O lote não está em um status valido para essa operação", "code": "TRC000087" } ``` --- # Webhooks do Ativo URL: /documentation/iaas/negociacao_recebiveis/asset/webhooks Ao longo do fluxo de cessão, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status dos ativos individuais. Existem dois tipos de webhook: `trade_receivables.asset_status_change` para mudanças de status e `trade_receivables.asset_creation` para confirmação de criação do ativo. :::info Configuração de webhooks Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. ::: ## Fluxo de status do ativo O ativo entra em `pending_eligibility` assim que é inserido no lote e, a partir da análise de elegibilidade, segue por um dos caminhos abaixo. Todos os nove status geram webhook — o caminho central leva ao encarteiramento, e as três saídas de recusa ou descarte são terminais. ![Fluxo de status do ativo, do pending_eligibility até completed, com as saídas para denied, registry_denied e discarded](/img/diagrams/iaas-negociacao-recebiveis-asset-webhooks.svg) _Como ler o diagrama: **azul** = status intermediário · **verde** = ativo cedido e encarteirado · **vermelho** = status final de recusa ou descarte._ ## Estrutura do webhook Todos os webhooks de ativo seguem a mesma estrutura base: | Campo | Tipo | Descrição | |---|---|---| | `webhook_type` | string | Tipo do webhook: `trade_receivables.asset_status_change` ou `trade_receivables.asset_creation`. | | `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. | | `data` | object | Dados do evento. Veja tabela abaixo. | #### Atributos de `data` | Campo | Tipo | Descrição | |---|---|---| | `assignment_external_id` | string | O `external_id` do lote ao qual o ativo pertence. | | `asset_external_id` | string | O `external_id` do ativo. | | `asset_new_status` | string | Novo status do ativo. | | `assignment_configuration_key` | string | Identificador da configuração de cessão à qual o lote pertence — a mesma chave usada nas URLs dos endpoints. | | `fund_class_key` | string | Identificador da classe do fundo associada ao lote. | | `asset_payload` | object | Presente apenas no webhook de criação (`asset_creation`). Contém todos os dados do ativo conforme enviados na criação. | :::info O que é a `assignment_configuration_key` A **configuração de cessão** é o acordo já cadastrado entre o cedente e o fundo: ela define para qual fundo os recebíveis são cedidos, qual tipo de ativo é aceito e sob quais regras a operação acontece. É a mesma chave que você já usa nas URLs dos endpoints de cessão, obtida na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato). Como um mesmo cedente pode ter mais de uma configuração ativa ao mesmo tempo, esse campo informa **sob qual acordo** o ativo está sendo cedido. Assim você direciona o webhook para o fluxo certo sem precisar consultar a API para descobrir a origem do ativo. ::: ```json title="Estrutura padrão do webhook" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "STATUS", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ## Eventos por status ### Ativo Criado STATUS pending_eligibility Enviado quando um ativo é inserido no lote com sucesso. Este webhook inclui o campo `asset_payload` com todos os dados da operação de crédito enviados na criação. O tipo do webhook é `trade_receivables.asset_creation`. ```json title="Webhook Body" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "pending_eligibility", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c", "asset_payload": { "premiums": [ { "total_value": 1.2, "premium_type": "spread" } ], "asset_type": "ccb", "credit_operation": { "delay": { "fine": { "amount": 0.0, "fine_type": "percentage" }, "interest": { "method": "compound", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "workdays" } } }, "borrower": { "name": "João Pereira", "email": "exemplo3@gmail.com", "phone": { "number": "948386674", "area_code": "11" }, "address": { "uf": "SP", "city": "São Paulo", "number": "84", "street": "RUA GILBERTO SABINO", "country": "BRA", "postal_code": "05425-020", "neighborhood": "Pinheiros" }, "person_type": "natural_person", "natural_person": { "birthdate": "1970-02-18", "mother_name": "Natalia Nascimento" }, "document_number": "926.857.750-05" }, "contract": { "cet": 0.0314, "number": "0032226586/NNT", "iof_value": 3.04, "issue_date": "2024-04-24", "issue_value": 93.05, "signature_date": "2024-04-24", "disbursement_date": "2024-04-24", "disbursement_value": 62.1 }, "pre_fixed": { "monthly_rate": 0.0179, "calendar_base": "calendar_365" }, "external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "installments": [ { "face_value": 30.81, "maturity_date": "2025-02-01", "installment_number": 1 }, { "face_value": 26.19, "maturity_date": "2026-02-01", "installment_number": 2 }, { "face_value": 29.68, "maturity_date": "2027-02-01", "installment_number": 3 }, { "face_value": 23.74, "maturity_date": "2028-02-01", "installment_number": 4 }, { "face_value": 28.49, "maturity_date": "2029-02-01", "installment_number": 5 }, { "face_value": 19.94, "maturity_date": "2030-02-01", "installment_number": 6 }, { "face_value": 13.96, "maturity_date": "2031-02-01", "installment_number": 7 }, { "face_value": 13.03, "maturity_date": "2032-02-01", "installment_number": 8 } ], "principal_value": 93.05, "amortization_type": "price", "interest_rate_type": "pre_fixed", "originator_document_number": "40.940.511/0001-08" }, "total_purchase_value": 94.86 } }, "webhook_type": "trade_receivables.asset_creation", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Aprovado na Elegibilidade — Pendente Documentação STATUS pending_documentation Enviado quando o ativo é **aprovado** na análise de elegibilidade e está aguardando o envio dos documentos obrigatórios. Utilize o endpoint de [Inserção de Documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) para enviar a documentação exigida. ```json title="Webhook Body" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "pending_documentation", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Pré-Aprovado STATUS pre_approved Enviado quando o ativo é **pré-aprovado**, após validação bem-sucedida dos documentos (ou quando nenhuma documentação adicional é exigida). O ativo está apto para avançar para a etapa de formalização/registro. ```json title="Webhook Body" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "pre_approved", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Pendente Registro STATUS pending_registry Enviado quando o ativo pré-aprovado é encaminhado para a **registradora**. Só ocorre em configurações de cessão cujo `registry_type` exige registro — `internal_registry`, `external_registry`, `registry_transfer` ou `unfit`. O ativo permanece nesse status até a registradora responder. ```json title="Webhook Body" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "pending_registry", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Pendente Formalização STATUS pending_formalization Enviado quando o ativo pré-aprovado foi encaminhado para a etapa de formalização (registro no órgão competente). O ativo aguarda a conclusão do processo de registro para ser encarteirado. ```json title="Webhook Body" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "pending_formalization", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Ativo Concluído STATUS completed Enviado quando o ativo foi **encarteirado com sucesso** na carteira do fundo. Este é o status final de um ativo bem-sucedido — a partir desse momento, o ativo encontra-se dentro do estoque do fundo. ```json title="Webhook Body" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "completed", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Reprovado na Elegibilidade STATUS denied Enviado quando o ativo é **reprovado** na análise de elegibilidade ou na validação de documentos. O ativo não seguirá adiante no fluxo. ```json title="Webhook Body" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "denied", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Registro Recusado STATUS registry_denied Enviado quando a **registradora recusa** o registro do ativo. É um status **terminal**: o ativo não segue para a formalização nem para o encarteiramento. O motivo da recusa é registrado pela QI Tech e não vem no corpo do webhook — consulte a [recuperação do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos) ou o time de integração para o detalhe. ```json title="Webhook Body" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "registry_denied", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Ativo Descartado STATUS discarded Enviado quando o ativo é descartado do lote. Isso pode ocorrer por remoção manual ou por problemas durante o processamento. ```json title="Webhook Body" { "data": { "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "asset_new_status": "discarded", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- # Aprovação do Gestor URL: /documentation/iaas/negociacao_recebiveis/assignment/aprovacao Após a elegibilidade do lote ser aprovada, o gestor do fundo deve analisar e decidir pela aprovação ou reprovação do lote. Se aprovado, o sistema gera o Termo de Cessão e o encaminha para assinatura. Se reprovado, o lote é descartado e o processo se encerra. :::info Rota exclusiva para Gestores Este endpoint está disponível **somente para gestores** do fundo. Caso o gestor não seja integrado via API, essa ação pode ser realizada pelo [Portal do Gestor](https://portal-do-gestor.fundos.qitech.com.br/). ::: :::tip Onde estou no fluxo? Este passo ocorre após a **elegibilidade do lote** ter sido aprovada. Você receberá um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com o status `pending_manager_approval` indicando que o lote está aguardando a decisão do gestor. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `assignment_external_id` | string | O `external_id` informado na criação do lote. | ```json title="Request Body — Aprovação" { "assignment_status": "approved", "disbursement_account_key": "764746ce-a530-4a71-af66-3f7c879627df" } ``` ```json title="Request Body — Reprovação" { "assignment_status": "denied" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `assignment_status` | string | obrigatório | Decisão do gestor sobre o lote. Valores aceitos: `approved` ou `denied`. | | `disbursement_account_key` | string | opcional | Chave única (UUID, 36 caracteres) da conta de desembolso cadastrada na homologação do cedente. Se não informada, será utilizada a conta padrão configurada no contrato de cessão. | **Enumeradores de `assignment_status`:** | Valor | Descrição | |---|---| | `approved` | Aprova o lote — o sistema gerará o Termo de Cessão | | `denied` | Reprova o lote — o lote será descartado | ## Response STATUS 200 ```json title="Response Body — Aprovação" { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "status": "approved", "number_of_approved_assets": 45, "assignment_total_value": 150000.00 } ``` ```json title="Response Body — Reprovação" { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "status": "denied", "number_of_approved_assets": 0, "assignment_total_value": 0.00 } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `assignment_key` | string | Identificador único do lote (UUID). | | `external_id` | string | Chave externa do lote fornecida pelo parceiro. | | `status` | string | Novo status do lote após a decisão do gestor (`approved` ou `denied`). | | `number_of_approved_assets` | integer | Quantidade de ativos aprovados na elegibilidade. Em caso de reprovação, o valor será `0`. | | `assignment_total_value` | number | Valor total da cessão em reais. Em caso de reprovação, o valor será `0.00`. | ## Possíveis erros STATUS 400 **Lote não encontrado** O `external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto e se você está usando a `fund_class_key` e `assignment_configuration_key` corretas. ```json { "title": "Assignment not found", "description": "Assignment not found", "translation": "Cessão não foi encontrada", "code": "TRC000018" } ``` STATUS 400 **Operação inválida para o status atual** O lote não está em um status que permita aprovação ou reprovação. Isso geralmente ocorre quando o lote ainda não passou pela elegibilidade, ou quando já foi aprovado/reprovado anteriormente. Consulte o status atual do lote via [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao) para entender em qual etapa ele se encontra. ```json { "title": "Invalid operation", "description": "This assignment can not receive 'denied' status", "translation": "Esse lote não pode receber o status 'denied'", "code": "TRC000024" } ``` ## Próximos passos Após a aprovação do gestor, o fluxo continua automaticamente: 1. **Assinatura do Termo de Cessão** — o sistema gera o Termo de Cessão e o envia para assinatura de todas as partes. Você receberá um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_assignment_term_signature`. O documento pode ser consultado via [Documentos da Cessão](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). 2. **Pagamento** — após a assinatura, o sistema realiza o pagamento ao cedente. Um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_payment` será enviado. 3. **Encarteiramento** — os ativos são incluídos na carteira do fundo e o lote é finalizado com status `completed`. --- # Criação do Lote de Cessão URL: /documentation/iaas/negociacao_recebiveis/assignment/criacao Este é o **primeiro passo** do fluxo de cessão de direitos creditórios. A criação do lote (*assignment*) reserva um agrupamento onde os ativos que serão cedidos ao fundo serão inseridos nas etapas seguintes. :::info Pré-requisitos Antes de criar um lote, você precisa ter em mãos: - A `fund_class_key` — chave única do fundo cessionário. - A `assignment_configuration_key` — chave única da configuração de cessão, obtida na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato). Essas duas chaves compõem os endpoints utilizados em todos os endpoints desta API: ``` /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key} ``` Para mais detalhes sobre o fluxo completo, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api). ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment MÉTODO POST ```json title="Request Body" { "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "assignment_date": "2024-04-01" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `external_id` | string | obrigatório | Chave única de identificação deste lote no sistema do parceiro integrador. Deve ser única — o sistema não permitirá a criação de dois lotes com o mesmo identificador. Máximo de 50 caracteres. | | `assignment_date` | string | opcional | Data da cessão no formato `YYYY-MM-DD`. Quando informada, deve corresponder à data contábil do fundo (*accounting_date*). Se não informada, será utilizada a data contábil vigente. | ## Response STATUS 201 ```json title="Response Body" { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "status": "pending_assets_insertion" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `assignment_key` | string | Identificador único do lote gerado pela QI Tech (UUID). | | `external_id` | string | A mesma chave externa fornecida na requisição. | | `status` | string | Status inicial do lote. Sempre retorna `pending_assets_insertion`, indicando que o lote está pronto para receber ativos. | ## Possíveis erros STATUS 404 **Configuração de cessão não encontrada** A combinação de `fund_class_key` e `assignment_configuration_key` informada não corresponde a nenhuma configuração de cessão. Verifique se as chaves estão corretas e se o contrato de cessão já foi homologado na etapa de [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato). ```json { "title": "AssignmentConfiguration was not found", "description": "AssignmentConfiguration was not found", "translation": "Configuração de cessão não foi encontrada", "code": "TRC000016" } ``` STATUS 400 **Data de cessão inválida** A data informada no campo `assignment_date` não corresponde à data contábil atual do fundo. Cada fundo possui uma data contábil vigente, e a data da cessão precisa ser igual a essa data. Verifique a data contábil vigente do fundo ou omita o campo `assignment_date` para que o sistema utilize a data automaticamente. ```json { "title": "Invalid assignment date.", "description": "Given assignment date is different from fund accounting date.", "translation": "Data de cessão fornecida diferente da data do fundo.", "code": "TRC000083" } ``` STATUS 400 **External ID duplicado** Já existe um lote cadastrado com o `external_id` informado. Cada lote deve ter um identificador único no sistema. Gere um novo `external_id` e tente novamente. ```json { "title": "Already Exists This External Id", "description": "Already Exists This External Id", "translation": "Já existe lote com esse external_id", "code": "TRC000041" } ``` ## Próximos passos Após criar o lote, o fluxo continua com: 1. **[Inserção dos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** — adicione os ativos (CCBs, duplicatas, etc.) que serão cedidos ao fundo. 2. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade. 3. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade. --- # Documentos da Cessão URL: /documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao Recupera os links para download do Termo de Cessão — tanto a versão original quanto a versão assinada. Este endpoint fica disponível a partir do momento em que o Termo é gerado, ou seja, após o lote atingir o status `pending_assignment_term_signature`. :::tip Quando utilizar Após receber o [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_assignment_term_signature`, utilize este endpoint para obter o link do Termo de Cessão e acompanhar se a assinatura já foi concluída. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assignment_term_link MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID). | | `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). | | `assignment_external_id` | string | O `external_id` informado na criação do lote. | ## Response STATUS 200 ```json title="Response Body" { "assignment_term_url": "https://storage.example.com/term/abc123.pdf", "signed_assignment_term_url": "https://storage.example.com/term/abc123_signed.pdf" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `assignment_term_url` | string | URL que direciona para o download do termo. | | `signed_assignment_term_url` | string \| null | URL para o Termo de Cessão assinado. Retorna `null` enquanto o documento ainda não tiver sido assinado por todas as partes. | :::info Observação O campo `signed_assignment_term_url` será `null` enquanto o Termo de Cessão ainda não tiver sido assinado por todas as partes envolvidas. Após a conclusão da assinatura, o lote avançará para o status `pending_payment` e um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) será enviado. ::: --- # Link de Assinatura Recupera o link para acesso à interface de assinatura do Termo de Cessão na CertifiQI, além de informações sobre os lotes e o link para download do documento. Este endpoint fica disponível a partir do momento em que o Termo é gerado, ou seja, após o lote atingir o status `pending_assignment_term_signature`. ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assignment_signature_url MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID). | | `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). | | `assignment_external_id` | string | O `external_id` informado na criação do lote. | ## Response STATUS 200 ```json title="Response Body" { "batches": [ { "name": "Termo de Cessão - Lote 001", "document_type": "assignment_term", "status": "pending", "document_key": "doc-uuid-example", "related_parties": [...] } ], "signature_url": "https://certifiqi.com/events/{external_batch_group_key}", "download_url": "https://storage.example.com/term/abc123.pdf" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `batches` | array | Lista de lotes vinculados ao Termo de Cessão. | | `batches[].name` | string | Nome do lote. | | `batches[].document_type` | string | Tipo do documento (ex: `assignment_term`, `duplicata`). | | `batches[].status` | string | Status atual da assinatura do lote. | | `batches[].document_key` | string | Chave identificadora do documento. | | `batches[].related_parties` | array | Partes envolvidas na assinatura do lote. | | `signature_url` | string | URL para acesso à interface de assinatura na CertifiQI. | | `download_url` | string | URL pré-assinada para download do Termo de Cessão. | :::info Observação O campo `download_url` aponta para o documento original (não assinado) enquanto o lote estiver no status `pending_assignment_term_signature`. Após a conclusão da assinatura por todas as partes, passa a apontar para o Termo de Cessão assinado. ::: --- # Encerrar Inserção de Ativos URL: /documentation/iaas/negociacao_recebiveis/assignment/fechamento Após inserir todos os ativos desejados no lote, utilize este endpoint para sinalizar que a inserção foi concluída. A partir desse momento, quando todos os ativos estiverem pré-aprovados (`pre_approved`) ou descartados (`discarded`), a elegibilidade do lote como um todo será avaliada automaticamente. :::info Não é necessário aguardar os webhooks dos ativos Você pode encerrar a inserção a qualquer momento após inserir os ativos. Não é preciso esperar que todos os ativos passem pela elegibilidade individual. O sistema aguardará automaticamente até que todos estejam com análise finalizada antes de prosseguir com a elegibilidade do lote. ::: :::tip Onde estou no fluxo? Este é o **3º passo** do fluxo de cessão. Antes deste passo, você deve ter: 1. [Criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao) 2. [Inserido os ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) e [enviado os documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `assignment_external_id` | string | O `external_id` informado na criação do lote. | ```json title="Request Body" { "assignment_status": "completed_assets_insertion" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `assignment_status` | string | obrigatório | Status para o qual o lote será atualizado. Para encerrar a inserção de ativos, envie `completed_assets_insertion`. | ## Response STATUS 200 ```json title="Response Body" { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "status": "completed_assets_insertion", "number_of_approved_assets": 0, "assignment_total_value": 0.00 } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `assignment_key` | string | Identificador único do lote (UUID). | | `external_id` | string | Chave externa do lote fornecida pelo parceiro. | | `status` | string | Novo status do lote: `completed_assets_insertion`. | | `number_of_approved_assets` | integer | Quantidade de ativos aprovados no lote. Nesta etapa, o valor será `0` pois a elegibilidade ainda não foi processada. | | `assignment_total_value` | number | Valor total da cessão em reais. Nesta etapa, o valor será `0.00` pois a precificação ainda não ocorreu. | ## Possíveis erros STATUS 400 **Lote sem ativos inseridos** Você tentou encerrar a inserção de ativos, mas o lote ainda não possui nenhum ativo. É necessário [inserir pelo menos um ativo](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) antes de fechar o lote. ```json { "title": "Cannot Close This Assignment", "description": "Cannot close this assignment because there is no asset.", "translation": "Não é possível fechar este lote porque não há nenhum ativo.", "code": "TRC000042" } ``` ## Próximos passos Após encerrar a inserção, o fluxo segue automaticamente: 1. **Elegibilidade dos ativos** — cada ativo será analisado individualmente. Você receberá [webhooks dos ativos](/documentation/iaas/negociacao_recebiveis/asset/webhooks) informando aprovação ou reprovação. 2. **Elegibilidade do lote** — quando todos os ativos tiverem sido analisados, a elegibilidade do lote será avaliada. O resultado será informado via [webhook do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). 3. **[Aprovação do gestor](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)** — caso o lote seja aprovado na elegibilidade, o gestor do fundo deverá aprová-lo. --- # Listagem de Lotes de Cessão URL: /documentation/iaas/negociacao_recebiveis/assignment/listagem Endpoint de consulta paginada que retorna os lotes de cessão de uma determinada classe de fundo. Utilize os filtros disponíveis para buscar lotes por data, status ou combinações de status. :::info Endpoint por classe de fundo Diferente dos demais endpoints de lote, este utiliza apenas a `fund_class_key` na URL — não é necessário informar a `assignment_configuration_key`. Isso permite listar lotes de todas as configurações de cessão de um fundo de uma vez. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignments MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `assignment_date` | string | opcional | Filtra por data da cessão no formato `YYYY-MM-DD`. | | `assignment_status` | string | opcional | Filtra por um status específico do lote. | | `in_status` | array | opcional | Lista de status para **incluir** na busca. Retorna apenas lotes que estejam em um dos status informados. | | `not_in_status` | array | opcional | Lista de status para **excluir** da busca. Retorna apenas lotes que **não** estejam nos status informados. | | `assignor_document_number` | string | opcional | Filtra por número de documento (CPF/CNPJ) do cedente. Deve ser enviado **com pontuação** (ex: `12.345.678/0001-90` ou `123.456.789-00`). | | `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `25`. Máximo: `155`. | ```python title="Exemplo de chamada" GET /trade_receivables/fund_class/{fund_class_key}/assignments?assignment_date=2024-04-01&in_status=pending_manager_approval,completed&page=0&limit=10 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "name": "CESSÃO #12345", "assignment_configuration": { "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "validation_configuration_key": "v1w2x3y4-z5a6-7890-abcd-ef1234567890", "assignment_configuration_name": "Config CCB Fundo Alpha", "assignment_contract_key": "k1l2m3n4-o5p6-7890-abcd-ef1234567890", "registry_type": "internal_registry", "asset_type": "ccb", "assignment_configuration_type": "standard", "consultant_decision_type": "manual_approval", "asset_fees": null, "assignment_reports": null, "fund_class": { "fund_class_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Fundo Alpha FIDC", "document_number": "12.345.678/0001-90", "accounting_date": "2024-04-01", "manager": { "manager_key": "e1f2a3b4-c5d6-7890-abcd-ef1234567890", "document_number": "11.222.333/0001-44", "manager_name": "Gestora Exemplo S.A." } }, "assignor": { "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "document_number": "98.765.432/0001-10", "name": "Cedente Exemplo Ltda" }, "consultant": { "consultant_key": "g1h2i3j4-k5l6-7890-abcd-ef1234567890", "document_number": "55.666.777/0001-88", "name": "Consultoria Exemplo Ltda" }, "originator_bonds": [ { "originator": { "originator_key": "h1i2j3k4-l5m6-7890-abcd-ef1234567890", "document_number": "22.333.444/0001-55", "name": "Originadora Exemplo Ltda" } } ], "webhook_configuration_bonds": [ { "webhook_configuration_bond": { "webhook_configuration_key": "w1x2y3z4-a5b6-7890-abcd-ef1234567890", "agent_type": "assignor", "agent_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890" }, "signature_key": "s1t2u3v4-w5x6-7890-abcd-ef1234567890", "webhook_url": "https://partner.example.com/webhooks/trade_receivables" } ] }, "assignment_number": "00012345", "assignment_date": "2024-04-01", "status": "completed", "assignment_term_key": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", "disbursement": { "target_account": { "account_key": "d1e2f3a4-b5c6-7890-abcd-ef1234567890", "account_type": "checking_account", "account_branch": "001", "account_number": "12345", "account_digit": "4", "financial_institution_code": "341", "financial_institution_ispb": "60701190", "owner": { "document_number": "98.765.432/0001-10" } } }, "assignment_total_value": 150000.00, "assignment_irr": 0.0215 } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de objetos de lote de cessão. Veja tabela abaixo. | | `page` | integer | Número da página atual. | | `limit` | integer | Quantidade de registros por página. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada lote (objetos dentro de `data`) Cada objeto do array possui a mesma estrutura retornada pelo endpoint de [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao), com exceção do campo `status_events` que **não é retornado** na listagem. | Campo | Tipo | Descrição | |---|---|---| | `assignment_key` | string | Identificador único do lote (UUID). | | `external_id` | string | Chave externa fornecida pelo parceiro. | | `name` | string | Nome identificador da cessão. | | `assignment_number` | string | Número do lote de cessão. | | `assignment_date` | string | Data da cessão no formato `YYYY-MM-DD`. | | `status` | string | Status atual do lote. Consulte a [tabela de status](#enumeradores-de-status-do-lote) abaixo. | | `origin_type` | string | Origem do lote (ex: `client`). | | `assignment_term_key` | string | Chave do Termo de Cessão (UUID). Disponível após geração do termo. | | `assignment_total_value` | number | Valor total da cessão em reais. Pode não estar presente se ainda não foi calculado. | | `assignment_irr` | number | Taxa interna de retorno (TIR) do lote. Pode não estar presente se ainda não foi calculada. | | `assignment_configuration` | object | Dados da configuração de cessão associada ao lote. Consulte os [atributos de `assignment_configuration`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-assignment_configuration) na página de Recuperação. | | `disbursement` | object \| null | Dados da conta de desembolso (quando aplicável). | | `assignor_discounts` | array | Lista de descontos do cedente. Presente apenas quando existem descontos configurados. Consulte os [atributos de `assignor_discounts`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-assignor_discounts) na página de Recuperação. | ## Enumeradores de status do lote | Status | Descrição | |---|---| | `pending_assets_insertion` | Lote criado, aguardando inserção de ativos | | `completed_assets_insertion` | Inserção de ativos encerrada, aguardando elegibilidade | | `pending_eligibility` | Em análise de elegibilidade | | `pending_consultant_approval` | Aguardando aprovação do consultor | | `pending_manager_approval` | Aguardando aprovação do gestor | | `pending_assets_registry` | Aguardando registro dos ativos | | `pending_assignment_term` | Aguardando geração do Termo de Cessão | | `pending_assignment_term_signature` | Aguardando assinatura do Termo de Cessão | | `pending_custody` | Aguardando custódia | | `pending_payment` | Aguardando pagamento ao cedente | | `pending_assets_wallet_inclusion` | Aguardando encarteiramento dos ativos | | `completed` | Cessão finalizada com sucesso | | `denied` | Lote reprovado na elegibilidade | | `discarded` | Lote descartado | --- # Recuperação do Lote de Cessão URL: /documentation/iaas/negociacao_recebiveis/assignment/recuperacao Recupera os detalhes completos de um lote de cessão específico, incluindo informações da configuração, status atual, histórico de eventos, dados de desembolso e valores financeiros. :::tip Quando utilizar Use este endpoint para consultar o estado atual de um lote a qualquer momento do fluxo — por exemplo, para verificar se o lote já passou pela elegibilidade, se o gestor já aprovou, ou se o pagamento foi realizado. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID). | | `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). | | `assignment_external_id` | string | O `external_id` informado na criação do lote. | ## Response STATUS 200 ```json title="Response Body" { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "name": "CESSÃO #12345", "assignment_configuration": { "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "validation_configuration_key": "v1w2x3y4-z5a6-7890-abcd-ef1234567890", "assignment_configuration_name": "Config CCB Fundo Alpha", "assignment_contract_key": "k1l2m3n4-o5p6-7890-abcd-ef1234567890", "registry_type": "internal_registry", "asset_type": "ccb", "assignment_configuration_type": "standard", "consultant_decision_type": "manual_approval", "asset_fees": null, "assignment_reports": null, "fund_class": { "fund_class_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Fundo Alpha FIDC", "document_number": "12.345.678/0001-90", "accounting_date": "2024-04-01", "manager": { "manager_key": "e1f2a3b4-c5d6-7890-abcd-ef1234567890", "document_number": "11.222.333/0001-44", "manager_name": "Gestora Exemplo S.A." } }, "assignor": { "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "document_number": "98.765.432/0001-10", "name": "Cedente Exemplo Ltda" }, "consultant": { "consultant_key": "g1h2i3j4-k5l6-7890-abcd-ef1234567890", "document_number": "55.666.777/0001-88", "name": "Consultoria Exemplo Ltda" }, "originator_bonds": [ { "originator": { "originator_key": "h1i2j3k4-l5m6-7890-abcd-ef1234567890", "document_number": "22.333.444/0001-55", "name": "Originadora Exemplo Ltda" } } ], "webhook_configuration_bonds": [ { "webhook_configuration_bond": { "webhook_configuration_key": "w1x2y3z4-a5b6-7890-abcd-ef1234567890", "agent_type": "assignor", "agent_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890" }, "signature_key": "s1t2u3v4-w5x6-7890-abcd-ef1234567890", "webhook_url": "https://partner.example.com/webhooks/trade_receivables" } ] }, "assignment_number": "00012345", "assignment_date": "2024-04-01", "status": "completed", "origin_type": "client", "assignment_term_key": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", "disbursement": { "target_account": { "account_key": "d1e2f3a4-b5c6-7890-abcd-ef1234567890", "account_type": "checking_account", "account_branch": "001", "account_number": "12345", "account_digit": "4", "financial_institution_code": "341", "financial_institution_ispb": "60701190", "owner": { "document_number": "98.765.432/0001-10" } } }, "assignment_total_value": 150000.00, "assignment_irr": 0.0215, "assignor_discounts": [ { "assignor_discount_key": "ad12e3f4-a5b6-7890-abcd-ef1234567890", "assignor_discount_type": "flat_rate", "status": "approved", "total_value": 500.00, "description": "Taxa de administração" } ], "status_events": [ { "status": "pending_assets_insertion", "event_datetime": "2024-04-01 10:00:00" }, { "status": "completed_assets_insertion", "event_datetime": "2024-04-01 11:30:00" }, { "status": "pending_eligibility", "event_datetime": "2024-04-01 11:35:00" }, { "status": "completed", "event_datetime": "2024-04-01 16:00:00", "selected_agent": { "AGENT-TYPE": "manager", "AGENT-KEY": "e1f2a3b4-c5d6-7890-abcd-ef1234567890", "AGENT-USER": "gestor@exemplo.com" } } ] } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `assignment_key` | string | Identificador único do lote gerado pela QI Tech (UUID). | | `external_id` | string | Chave externa fornecida pelo parceiro na criação. | | `name` | string | Nome identificador da cessão. | | `assignment_number` | string | Número sequencial do lote de cessão. | | `assignment_date` | string | Data da cessão no formato `YYYY-MM-DD`. | | `status` | string | Status atual do lote. Consulte os [enumeradores de status](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote) para todos os valores possíveis. | | `assignment_term_key` | string | Chave do Termo de Cessão (UUID). Disponível após a geração do termo. | | `assignment_total_value` | number | Valor total da cessão em reais. Disponível após a aprovação. Pode não estar presente se ainda não foi calculado. | | `assignment_irr` | number | Taxa interna de retorno (TIR) do lote. Pode não estar presente se ainda não foi calculada. | | `assignment_configuration` | object | Dados completos da configuração de cessão. Veja tabela abaixo. | | `disbursement` | object \| null | Dados da conta de desembolso. `null` quando ainda não configurada. | | `assignor_discounts` | array | Lista de descontos do cedente. Presente apenas quando existem descontos configurados. Veja tabela abaixo. | | `status_events` | array | Histórico de transições de status do lote. Veja tabela abaixo. | #### Atributos de `assignment_configuration` | Campo | Tipo | Descrição | |---|---|---| | `assignment_configuration_key` | string | Chave da configuração (UUID). | | `validation_configuration_key` | string | Chave da configuração de validação (UUID). | | `assignment_configuration_name` | string | Nome da configuração de cessão. | | `assignment_contract_key` | string | Chave do contrato de cessão (UUID). | | `registry_type` | string | Tipo de registro dos ativos (ex: `internal_registry`, `external_registry`). | | `asset_type` | string | Tipo de ativo aceito nesta configuração (ex: `ccb`, `duplicata_mercantil`, `duplicata_servico`). | | `assignment_configuration_type` | string | Tipo da configuração de cessão (ex: `standard`). | | `consultant_decision_type` | string | Tipo de decisão do consultor (ex: `manual_approval`, `auto_approval`). | | `asset_fees` | object \| null | Configuração de taxas dos ativos, quando aplicável. | | `assignment_reports` | object \| null | Configuração de relatórios da cessão, quando aplicável. | | `fund_class` | object | Dados do fundo cessionário. Veja tabela abaixo. | | `assignor` | object | Dados do cedente. Veja tabela abaixo. | | `consultant` | object | Dados do consultor. Presente quando a configuração possui consultor vinculado. Veja tabela abaixo. | | `originator_bonds` | array | Lista de originadores vinculados à configuração. Veja tabela abaixo. | | `webhook_configuration_bonds` | array | Lista de configurações de webhook vinculadas. Veja tabela abaixo. | #### Atributos de `fund_class` | Campo | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID). | | `name` | string | Nome do fundo. | | `document_number` | string | CNPJ do fundo. | | `accounting_date` | string | Data contábil vigente do fundo no formato `YYYY-MM-DD`. | | `manager` | object | Dados do gestor do fundo. Veja tabela abaixo. | #### Atributos de `manager` | Campo | Tipo | Descrição | |---|---|---| | `manager_key` | string | Chave única do gestor (UUID). | | `document_number` | string | CNPJ do gestor. | | `manager_name` | string | Nome do gestor. | #### Atributos de `assignor` | Campo | Tipo | Descrição | |---|---|---| | `assignor_key` | string | Chave única do cedente (UUID). | | `document_number` | string | CPF/CNPJ do cedente. | | `name` | string | Nome do cedente. | #### Atributos de `consultant` | Campo | Tipo | Descrição | |---|---|---| | `consultant_key` | string | Chave única do consultor (UUID). | | `document_number` | string | CNPJ do consultor. | | `name` | string | Nome do consultor. | #### Atributos de `originator_bonds` | Campo | Tipo | Descrição | |---|---|---| | `originator` | object | Dados do originador. | | `originator.originator_key` | string | Chave única do originador (UUID). | | `originator.document_number` | string | CNPJ do originador. | | `originator.name` | string | Nome do originador. | #### Atributos de `webhook_configuration_bonds` | Campo | Tipo | Descrição | |---|---|---| | `webhook_configuration_bond` | object | Dados da configuração de webhook. | | `webhook_configuration_bond.webhook_configuration_key` | string | Chave única da configuração de webhook (UUID). | | `webhook_configuration_bond.agent_type` | string | Tipo do agente que receberá o webhook (ex: `assignor`, `manager`, `consultant`). | | `webhook_configuration_bond.agent_key` | string | Chave do agente vinculado. | | `signature_key` | string | Chave de assinatura para validação do webhook (UUID). | | `webhook_url` | string | URL de destino do webhook. | #### Atributos de `assignor_discounts` | Campo | Tipo | Descrição | |---|---|---| | `assignor_discount_key` | string | Chave única do desconto (UUID). | | `assignor_discount_type` | string | Tipo de desconto do cedente (ex: `flat_rate`). | | `status` | string | Status do desconto (ex: `approved`, `pending`). | | `total_value` | number | Valor total do desconto em reais. | | `description` | string | Descrição do desconto. | #### Atributos de `status_events` | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Status do evento. | | `event_datetime` | string | Data e hora do evento no formato `YYYY-MM-DD HH:MM:SS`. | | `selected_agent` | object | Dados do agente responsável pela transição. Presente apenas quando a transição foi feita por um agente identificado. | --- # Como criar uma cessão? URL: /documentation/iaas/negociacao_recebiveis/assignment/video_cessao Este guia apresenta o fluxo completo de criação de uma cessão de direitos creditórios, desde a criação do lote até o encarteiramento dos ativos no fundo. Utilize o vídeo abaixo como referência visual e os links para acessar a documentação detalhada de cada etapa. :::tip Manual completo Para um entendimento aprofundado das regras de negócio e do produto, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api). ::: ## Vídeo — Fluxo de cessão via Python ## Passo a passo ### 1. Criação do Lote Crie um lote de cessão informando um identificador único (`external_id`). O lote será o contêiner para todos os ativos que serão cedidos ao fundo. **[Acessar documentação da criação do lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)** ### 2. Inserção dos Ativos Adicione os ativos (CCBs, duplicatas, etc.) ao lote criado. Cada ativo deve ser inserido individualmente com suas informações de operação, parcelas e dados do sacado. **[Acessar documentação da inserção de ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** ### 3. Envio dos Documentos Para cada ativo aprovado na elegibilidade individual, envie os documentos exigidos pelo produto (contrato, nota fiscal, etc.). O ativo só prossegue na esteira após todos os documentos exigidos serem enviados. **[Acessar documentação do envio de documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** ### 4. Encerramento da Inserção Sinalize que todos os ativos foram inseridos no lote. Esse comando permite que o sistema avalie a elegibilidade do lote como um todo após todos os ativos serem analisados. **[Acessar documentação do encerramento](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** ### 5. Aprovação do Gestor Após a elegibilidade do lote ser aprovada, o gestor do fundo analisa e aprova ou reprova o lote. Se aprovado, o Termo de Cessão será gerado automaticamente. **[Acessar documentação da aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)** ### 6. Assinatura, Pagamento e Encarteiramento Os passos finais são automatizados: o Termo de Cessão é assinado pelas partes, o pagamento é realizado ao cedente e os ativos são encarteirados na carteira do fundo. Acompanhe o progresso através dos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). --- # Webhooks do Lote de Cessão URL: /documentation/iaas/negociacao_recebiveis/assignment/webhooks Ao longo do fluxo de cessão, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status do lote. Todos os webhooks possuem o tipo `trade_receivables.assignment_status_change` e identificam o lote pelo `assignment_external_id` fornecido na criação. :::info Configuração de webhooks Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. ::: ## Fluxo de status do lote O lote percorre treze status, e **todos** geram webhook. A coluna central é o caminho de sucesso, da criação do lote até o encarteiramento dos ativos; a coluna da direita concentra as saídas de recusa, que podem ocorrer na elegibilidade, na aprovação do consultor ou na aprovação do gestor. ![Fluxo de status do lote de cessão, do pending_assets_insertion até completed, com as saídas para denied e discarded](/img/diagrams/iaas-negociacao-recebiveis-assignment-webhooks.svg) _Como ler o diagrama: **azul** = status intermediário · **verde** = cessão concluída · **vermelho** = status final de recusa ou descarte._ ## Estrutura do webhook Todos os webhooks do lote de cessão seguem a mesma estrutura: | Campo | Tipo | Descrição | |---|---|---| | `webhook_type` | string | Sempre `trade_receivables.assignment_status_change`. | | `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. | | `data` | object | Dados do evento. Veja tabela abaixo. | #### Atributos de `data` | Campo | Tipo | Descrição | |---|---|---| | `assignment_external_id` | string | O `external_id` do lote informado na criação. | | `assignment_new_status` | string | Novo status do lote. | | `assignment_configuration_key` | string | Identificador da configuração de cessão à qual o lote pertence — a mesma chave usada nas URLs dos endpoints. | | `fund_class_key` | string | Identificador da classe do fundo associada ao lote. | | `signed_term_url` | string | URL para download do Termo de Cessão assinado. Presente apenas no webhook `pending_payment` quando o termo foi assinado digitalmente. | :::info O que é a `assignment_configuration_key` A **configuração de cessão** é o acordo já cadastrado entre o cedente e o fundo: ela define para qual fundo os recebíveis são cedidos, qual tipo de ativo é aceito e sob quais regras a operação acontece. É a mesma chave que você já usa nas URLs dos endpoints de cessão, obtida na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato). Como um mesmo cedente pode ter mais de uma configuração ativa ao mesmo tempo, esse campo informa **sob qual acordo** o evento aconteceu. Assim você direciona o webhook para o fluxo certo sem precisar consultar a API para descobrir a origem do lote. ::: ```json title="Estrutura padrão do webhook" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "STATUS", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ## Eventos por status ### Lote Criado — Aguardando Inserção de Ativos STATUS pending_assets_insertion Enviado quando um novo lote de cessão é criado com sucesso e está pronto para receber ativos. Este é o primeiro webhook do ciclo de vida do lote. O cedente pode inserir ativos enquanto o lote estiver neste status. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "pending_assets_insertion", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Inserção de Ativos Concluída STATUS completed_assets_insertion Enviado quando a inserção de ativos é **encerrada** pelo cedente. A partir desse momento não é mais possível adicionar ativos ao lote, que avança automaticamente para a análise de elegibilidade. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "completed_assets_insertion", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Em Análise de Elegibilidade STATUS pending_eligibility Enviado quando o lote inicia o processo de análise de elegibilidade. Todos os ativos são analisados individualmente, e o resultado agregado determina a aprovação ou reprovação do lote. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "pending_eligibility", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Pendente Aprovação do Consultor STATUS pending_consultant_approval Enviado quando o lote passa na análise de elegibilidade e está aguardando a decisão do **consultor** do fundo. Esse status ocorre quando o fluxo de aprovação configurado exige aprovação prévia do consultor antes do gestor. O consultor pode aprovar ou reprovar o lote via [Portal do Consultor](https://portal-do-consultor.fundos.qitech.com.br/). ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "pending_consultant_approval", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Pendente Aprovação do Gestor STATUS pending_manager_approval Enviado quando o lote é **aprovado na elegibilidade** (e pelo consultor, quando aplicável) e está aguardando a decisão do gestor do fundo. O gestor deve aprovar ou reprovar o lote via [Aprovação do Gestor](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) ou pelo [Portal do Gestor](https://portal-do-gestor.fundos.qitech.com.br/). ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "pending_manager_approval", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Aguardando Formalização dos Ativos STATUS waiting_assets_to_formalize Enviado quando o gestor **aprova** o lote e o sistema aguarda a conclusão da formalização (registro) de todos os ativos aprovados. O lote permanece neste status até que todos os ativos concluam o processo de registro. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "waiting_assets_to_formalize", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Aguardando Geração do Termo de Cessão STATUS pending_assignment_term Enviado quando todos os ativos foram formalizados e o sistema está **gerando o Termo de Cessão**. O lote aguarda a conclusão da geração do documento antes de encaminhá-lo para assinatura. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "pending_assignment_term", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Pendente Assinatura do Termo STATUS pending_assignment_term_signature Enviado após a aprovação do gestor, quando o Termo de Cessão foi gerado e encaminhado para assinatura de todas as partes envolvidas. Você pode consultar o documento via [Documentos da Cessão](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "pending_assignment_term_signature", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Pendente Pagamento STATUS pending_payment Enviado após o Termo de Cessão ter sido assinado por todas as partes. O sistema irá realizar o pagamento ao cedente na conta configurada. O valor total é a soma dos `total_purchase_value` de todos os ativos não descartados do lote. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "pending_payment", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Aguardando Encarteiramento dos Ativos STATUS pending_assets_wallet_inclusion Enviado após a confirmação do pagamento ao cedente, quando os ativos estão sendo **encarteirados** na carteira do fundo. O sistema processa a inclusão dos ativos no estoque do fundo. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "pending_assets_wallet_inclusion", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Cessão Completa STATUS completed Enviado quando todos os ativos do lote foram **encarteirados** na carteira do fundo. A partir desse momento, os ativos já se encontram dentro do estoque do fundo. Este é o status final de uma cessão bem-sucedida. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "completed", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Reprovado na Elegibilidade STATUS denied Enviado quando o lote é **reprovado** na análise de elegibilidade ou pelo gestor/consultor do fundo. O lote ainda pode ser manipulado, porém caso nada aconteça ele será descartado. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "denied", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Lote Descartado STATUS discarded Enviado quando o lote é descartado. Isso pode ocorrer por reprovação na elegibilidade, reprovação do gestor, ou por problemas no registro dos ativos. O lote não seguirá adiante no fluxo. ```json title="Webhook Body" { "data": { "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "assignment_new_status": "discarded", "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c" }, "webhook_type": "trade_receivables.assignment_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- # Fluxo de Cessão URL: /documentation/iaas/negociacao_recebiveis/fluxo_cessao Esta página oferece uma visão holística de todo o fluxo de cessão de direitos creditórios, desde a criação do lote até o encarteiramento dos ativos na carteira do fundo. Acompanhe a evolução dos **status do lote**, dos **status dos ativos** e dos **webhooks** recebidos em cada etapa. :::tip Como usar este fluxograma Passe o mouse sobre cada etapa para ver os detalhes do endpoint e acessar a documentação completa. As três trilhas coloridas mostram simultaneamente o que acontece com o lote, com os ativos e quais webhooks você receberá. ::: {` .cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px} .cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600} .cf-legend-dot{width:12px;height:12px;border-radius:3px} .cf-step{position:relative;margin-bottom:4px} .cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)} .cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))} .cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)} .cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap} .cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0} .cf-num-int{background:#3b82f6} .cf-num-qi{background:#8b5cf6} .cf-num-ges{background:#d946ef} .cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)} .cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto} .cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb} .cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed} .cf-actor-ges{background:rgba(217,70,239,0.12);color:#c026d3} .cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px} .cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px} .cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid} .cf-track-lote{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)} .cf-track-ativo{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)} .cf-track-wh{background:rgba(245,158,11,0.1);color:#b45309;border-color:rgba(245,158,11,0.25)} .cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)} .cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em} .cf-new{font-weight:700} .cf-unchanged{opacity:0.5} .cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px} .cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)} .cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap} .cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem} .cf-method-post{background:#f97316;color:#fff} .cf-method-put{background:#3b82f6;color:#fff} .cf-method-get{background:#22c55e;color:#fff} .cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px} .cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none} .cf-link:hover{text-decoration:underline} .cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap} .cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed} .cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)} .cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)} .cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px} .cf-branch-label-ok{color:#16a34a} .cf-branch-label-err{color:#dc2626} html[data-theme='dark'] .cf-track-lote{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)} html[data-theme='dark'] .cf-track-ativo{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)} html[data-theme='dark'] .cf-track-wh{background:rgba(245,158,11,0.15);color:#fbbf24;border-color:rgba(245,158,11,0.3)} html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)} html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)} html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)} html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa} html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa} html[data-theme='dark'] .cf-actor-ges{background:rgba(217,70,239,0.2);color:#e879f9} `} ## Legenda Agente Integrador QI Tech (automático) Gestor do Fundo Status do Lote Status do Ativo Webhook ## Fluxograma 1 Criação do Lote Agente Integrador Cria um lote de cessão com um identificador único ( external_id ). Lote: pending_assets_insertion POST /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment O lote é criado em status pending_assets_insertion , pronto para receber ativos. Ver documentação completa → 2 Inserção dos Ativos Agente Integrador Insere os ativos no lote (CCB, duplicata, contrato descontado ou contrato parcelado). Repita para cada ativo. Lote: pending_assets_insertion Ativo: pending_eligibility Webhook: asset_creation POST /trade_receivables/.../assignment/{assignment_external_id}/asset Cada ativo é criado com status pending_eligibility . Você receberá um webhook trade_receivables.asset_creation confirmando a inserção. CCB → Duplicata → Contrato Descontado → Contrato Parcelado → 3 Envio de Documentos Agente Integrador Envia os documentos exigidos para cada ativo (PDF em Base64). Duplicatas mercantis não exigem documentos. Lote: pending_assets_insertion Ativo: pending_eligibility POST /trade_receivables/.../asset/{asset_external_id}/document Envie os documentos após receber o webhook pending_documentation para o ativo (etapa 5a). Ver documentação completa → 4 Encerrar Inserção Agente Integrador Sinaliza que todos os ativos foram inseridos no lote. A análise de elegibilidade será iniciada automaticamente. Lote: completed_assets_insertion Ativo: pending_eligibility PUT /trade_receivables/.../assignment/{assignment_external_id} Envie {"assignment_status": "completed_assets_insertion"} . Não é necessário aguardar os webhooks de elegibilidade individual dos ativos. Ver documentação completa → 5a Elegibilidade dos Ativos QI Tech A QI Tech analisa cada ativo individualmente. Você recebe um webhook por ativo com o resultado. Lote: completed_assets_insertion Ativo: pre_approved / denied Webhook: asset_status_change Ativo aprovado pre_approved O ativo foi pré-aprovado na elegibilidade. Ativo reprovado denied O ativo não segue adiante no fluxo. Webhook trade_receivables.asset_status_change — enviado para cada ativo com o resultado da elegibilidade. Ver documentação de webhooks do ativo → 5b Elegibilidade do Lote QI Tech Quando todos os ativos forem analisados, a QI Tech avalia a elegibilidade do lote como um todo. Lote: pending_manager_approval / denied Webhook: assignment_status_change Lote elegível pending_manager_approval O lote aguarda a aprovação do gestor do fundo (passo 6). Lote reprovado denied O lote causa desenquadramento do fundo. Fluxo encerrado. Webhook trade_receivables.assignment_status_change — informa se o lote foi aprovado ou reprovado na elegibilidade. Ver documentação de webhooks do lote → 6 Aprovação do Gestor Gestor do Fundo O gestor do fundo analisa e aprova ou reprova o lote (via API ou pelo Portal do Gestor). Se aprovado, o Termo de Cessão é gerado automaticamente. Lote: pending_assignment_term_signature Webhook: assignment_status_change PUT /trade_receivables/.../assignment/{assignment_external_id} Endpoint disponível somente para gestores. Envie {"assignment_status": "approved"} ou "denied" . Após aprovação, você recebe o webhook com status pending_assignment_term_signature . Ver documentação completa → 7 Assinatura do Termo de Cessão QI Tech O Termo de Cessão é gerado e encaminhado para assinatura. Todas as partes relacionadas precisam assinar o termo para que o fluxo prossiga. O integrador pode consultar o documento a qualquer momento. Lote: pending_payment Webhook: assignment_status_change GET /trade_receivables/.../assignment/{assignment_external_id}/assignment_term_link Consulte o Termo de Cessão (original e assinado). Após todas as partes assinarem, você recebe o webhook com status pending_payment . Ver documentação completa → 8 Pagamento ao Cedente QI Tech O pagamento é realizado automaticamente ao cedente na conta configurada durante a homologação. Lote: pending_assets_wallet_inclusion Webhook: assignment_status_change O valor total é a soma dos total_purchase_value de todos os ativos não descartados. Após o pagamento, você recebe o webhook com status pending_assets_wallet_inclusion . 9 Encarteiramento QI Tech Os ativos são incluídos na carteira do fundo. A cessão está concluída. Lote: completed Ativo: completed Webhook: assignment_status_change Você recebe o webhook final com status completed . A partir desse momento, os ativos se encontram na carteira do fundo. Ver documentação de webhooks → --- ## Resumo de webhooks A tabela abaixo consolida todos os webhooks que o integrador recebe ao longo do fluxo, na ordem cronológica: | # | Tipo do webhook | Status | Momento no fluxo | Ação esperada | |---|---|---|---|---| | 1 | `asset_creation` | `pending_eligibility` | Após inserção de cada ativo (passo 2) | Nenhuma — confirmação de recebimento. | | 2 | `asset_status_change` | `pre_approved` | Ativo aprovado na elegibilidade (passo 5a) | Nenhuma — ativo pré-aprovado. | | 3 | `asset_status_change` | `denied` | Ativo reprovado na elegibilidade (passo 5a) | Nenhuma — ativo não segue adiante. | | 4 | `assignment_status_change` | `pending_manager_approval` | Lote aprovado na elegibilidade (passo 5b) | Aguardar [aprovação do gestor](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao). | | 5 | `assignment_status_change` | `denied` | Lote reprovado na elegibilidade (passo 5b) | Nenhuma — fluxo encerrado. | | 6 | `assignment_status_change` | `pending_assignment_term_signature` | Gestor aprovou o lote (passo 6) | Opcional: [consultar Termo de Cessão](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). | | 7 | `assignment_status_change` | `pending_payment` | Termo assinado por todas as partes (passo 7) | Nenhuma — pagamento em processamento. | | 8 | `assignment_status_change` | `pending_assets_wallet_inclusion` | Pagamento realizado (passo 8) | Nenhuma — encarteiramento em processamento. | | 9 | `assignment_status_change` | `completed` | Ativos encarteirados (passo 9) | Cessão concluída com sucesso. | | — | `assignment_status_change` | `discarded` | Qualquer momento (reprovação/erro) | Nenhuma — lote descartado. | :::info Prefixo dos webhooks Todos os tipos de webhook possuem o prefixo `trade_receivables.`. Por exemplo: `trade_receivables.asset_creation` e `trade_receivables.assignment_status_change`. Para detalhes sobre a estrutura completa dos webhooks, consulte [Webhooks do Ativo](/documentation/iaas/negociacao_recebiveis/asset/webhooks) e [Webhooks do Lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). ::: --- # Cessão de Direitos Creditórios URL: /documentation/iaas/negociacao_recebiveis/inicio Esta seção documenta as APIs que viabilizam o processo de cessão de Direitos Creditórios para Fundos de Investimento administrados pela QI CTVM. O fluxo abrange desde a criação do lote de cessão até o encarteiramento dos ativos na carteira do fundo. :::tip Manual completo Para um entendimento aprofundado das regras de negócio e do produto, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api). Recomendamos a leitura em conjunto com as rotas aqui disponibilizadas. ::: :::info Pré-requisitos - Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de Homologação (Sandbox) e Produção. - Você precisará da `fund_class_key` (chave do fundo) e da `assignment_configuration_key` (chave da configuração de cessão), obtidas na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato). - Para consultar as configurações de cessão disponíveis, utilize o endpoint de [Listagem de Configurações de Cessão](/documentation/iaas/negociacao_recebiveis/listagem). ::: ## Como enviar a cessão Existem dois caminhos, com o mesmo resultado final. Escolha um por lote — não é possível misturar os dois no mesmo lote. | Caminho | Como funciona | Onde | |---|---|---| | **Pela API, ativo a ativo** | Criação do lote, uma requisição por ativo e encerramento da inserção. É o fluxo detalhado nesta seção | API de integração | | **Por arquivo** | Um único arquivo com todos os ativos do lote: **CNAB 444** para duplicatas, contratos descontados e CT-e, ou **CSV** para CCB, honorários advocatícios e contratos parcelados | Portal do gestor/consultor | :::tip Cessão de duplicatas por arquivo Para duplicatas o formato é o **CNAB 444**; o CSV é aceito para operações de crédito (CCB), honorários advocatícios e contratos parcelados. Veja [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), o [Layout CNAB 444 — Cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444) e o [Layout CSV — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado), com exemplos prontos para download. ::: ## Fluxo de cessão O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação. :::tip Fluxo completo Para todas as transições de status, os payloads dos webhooks e os caminhos de exceção, consulte o [Fluxo de cessão](/documentation/iaas/negociacao_recebiveis/fluxo_cessao). ::: ## Passo a passo ### 1. Criação do Lote Crie um lote de cessão informando um identificador único (`external_id`). O lote será o contêiner para todos os ativos que serão cedidos ao fundo. **[Acessar documentação da criação do lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)** ### 2. Inserção dos Ativos Adicione os ativos (CCBs, duplicatas, contratos parcelados, etc.) ao lote criado. Cada ativo deve ser inserido individualmente com suas informações de operação, parcelas e dados do sacado. **[Acessar documentação da inserção de ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** ### 3. Envio dos Documentos Para cada ativo inserido, envie os documentos exigidos pelo produto (contrato, nota fiscal, etc.). O ativo só prossegue na esteira após todos os documentos exigidos serem enviados. **[Acessar documentação do envio de documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** ### 4. Encerramento da Inserção Sinalize que todos os ativos foram inseridos no lote. O sistema aguardará a análise individual de cada ativo antes de prosseguir com a elegibilidade do lote como um todo. **[Acessar documentação do encerramento](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** ### 5. Aprovação do Gestor Após a elegibilidade do lote ser aprovada, o lote segue para aprovação. A depender da configuração de cessão, essa etapa é **manual** — o consultor e/ou o gestor do fundo analisam e aprovam ou reprovam o lote, e o lote fica em `pending_consultant_approval` / `pending_manager_approval` até a decisão — ou **automática**, sem nenhuma ação do integrador. Se aprovado, o Termo de Cessão será gerado automaticamente. **[Acessar documentação da aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)** ### 6. Assinatura, Pagamento e Encarteiramento Os passos finais são automatizados: o Termo de Cessão é assinado pelas partes, o pagamento é realizado ao cedente e os ativos são encarteirados na carteira do fundo. Acompanhe o progresso através dos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). ## Lotes de substituição O fluxo de substituição segue as mesmas etapas do fluxo de cessão, com um passo adicional: antes de inserir os ativos que serão comprados, é necessário inserir os ativos que serão **recomprados** pelo cedente. 1. Criação do lote 2. **Inserção dos ativos de recompra** — [Acessar documentação](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset) 3. Inserção dos ativos que serão comprados 4. Encerramento da inserção --- # Listagem de Configurações de Cessão URL: /documentation/iaas/negociacao_recebiveis/listagem Endpoint de consulta paginada que retorna as configurações de cessão vinculadas a uma determinada classe de fundo. Cada configuração representa a relação entre um fundo cessionário e um cedente, incluindo regras de registro, tipo de ativo aceito e aprovação. ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configurations MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única do fundo (UUID). | ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `assignment_contract_key` | string | opcional | Filtra por chave do contrato que originou a configuração (UUID). | | `asset_type` | string | opcional | Filtra por tipo de ativo aceito na configuração (ex: `ccb`, `duplicata_mercantil`, `duplicata_servicos`). | | `assignor_document_number` | string | opcional | Filtra por CPF/CNPJ do cedente. Deve ser enviado **com pontuação** (ex: `12.345.678/0001-90` ou `123.456.789-00`). | | `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `10`. | ```python title="Exemplo de chamada" GET /trade_receivables/fund_class/{fund_class_key}/assignment_configurations?asset_type=ccb&assignor_document_number=98.765.432/0001-10&page=0&limit=10 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "assignment_configuration_name": "Config CCB Fundo Alpha", "assignment_contract_key": "k1l2m3n4-o5p6-7890-abcd-ef1234567890", "registry_type": "internal_registry", "asset_type": "ccb", "fund_class": { "fund_class_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "Fundo Alpha FIDC", "document_number": "12.345.678/0001-90", "accounting_date": "2024-04-01", "manager": { "manager_key": "e1f2a3b4-c5d6-7890-abcd-ef1234567890", "document_number": "11.222.333/0001-44", "manager_name": "Gestora Exemplo S.A." } }, "assignor": { "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "document_number": "98.765.432/0001-10", "name": "Cedente Exemplo Ltda" }, "consultant_decision_type": "manual_approval", "consultant": { "consultant_key": "g1h2i3j4-k5l6-7890-abcd-ef1234567890", "document_number": "55.666.777/0001-88", "name": "Consultoria Exemplo Ltda" } } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de objetos de configuração de cessão. Veja tabela abaixo. | | `page` | integer | Número da página atual. | | `limit` | integer | Quantidade de registros por página. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada configuração (objetos dentro de `data`) | Campo | Tipo | Descrição | |---|---|---| | `assignment_configuration_key` | string | Identificador único da configuração de cessão (UUID). | | `assignment_configuration_name` | string | Nome da configuração de cessão. | | `assignment_contract_key` | string | Chave do contrato de cessão que originou esta configuração (UUID). | | `registry_type` | string | Tipo de registro dos ativos. Valores possíveis: `internal_registry`, `external_registry`. | | `asset_type` | string | Tipo de ativo aceito nesta configuração. Valores possíveis: `ccb`, `duplicata_mercantil`, `duplicata_servico`. | | `consultant_decision_type` | string | Tipo de decisão do consultor sobre a elegibilidade. Valores possíveis: `automatic_approval`, `manual_approval`. | | `fund_class` | object | Dados do fundo cessionário. Consulte os [atributos de `fund_class`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-fund_class) na página de Recuperação. | | `assignor` | object | Dados do cedente. Consulte os [atributos de `assignor`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-assignor) na página de Recuperação. | | `consultant` | object | Dados do consultor vinculado à configuração. Consulte os [atributos de `consultant`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-consultant) na página de Recuperação. | | `required_documents` | array | Tipos de documento exigidos **antes** da cessão, enviados pelo [endpoint de documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) enquanto o ativo está em `pending_documentation`. Lista vazia quando o produto não exige nenhum. | | `after_assignment_required_documents` | array | Tipos de documento exigidos **depois** da cessão, enviados pelo mesmo endpoint enquanto o ativo está em `pending_after_assignment_documentation`. Lista vazia quando o produto não exige nenhum. | --- # Listagem de Solicitações de Amortização URL: /documentation/iaas/passivo/amortizacao/listagem Endpoint de consulta paginada que retorna as solicitações de amortização de uma determinada classe de fundo. A resposta inclui, para cada solicitação, os dados financeiros calculados, o histórico de status, as amortizações por investidor e os dados da série de emissão vinculada. :::info Filtros de retorno Por padrão, todos os sub-objetos (`issuance_serie`, `investor_amortizations` e `status_events`) são retornados. Utilize os query params `dto_filters_*` para omitir campos e reduzir o tamanho da resposta. ::: ## Request ENDPOINT /quota/fund_class/{fund_class_key}/amortization_requests MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única da classe de fundo (UUID). | ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `20`. Máximo: `100`. | | `dto_filters_issuance_serie` | boolean | opcional | Quando `true`, omite o objeto `issuance_serie` de cada item. Padrão: `false`. | | `dto_filters_investor_amortizations` | boolean | opcional | Quando `true`, omite o array `investor_amortizations` de cada item. Padrão: `false`. | | `dto_filters_status_events` | boolean | opcional | Quando `true`, omite o array `status_events` de cada item. Padrão: `false`. | ```python title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/amortization_requests?page=0&limit=20 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "amortization_request_key": "3571e292-3a83-4011-904d-20ee963022ef", "type": "scheduled_amortization", "regime_type": "issuance_serie_principal_percentage", "quotation_date": "2026-06-05", "principal_percentage": 0.5, "financial_application_yield_percentage": 0.12, "gross_value": 10000.0, "result_quota_value": 1.05, "amortization_value": 5000.0, "net_value": 4750.0, "quota_percentage": 0.5, "status": "done", "status_events": [ { "status": "created", "event_datetime": "2026-06-01T10:00:00.000Z" }, { "status": "done", "event_datetime": "2026-06-05T14:30:00.000Z" } ], "investor_amortizations": [ { "investor_amortization_key": "f1e2d3c4-b5a6-7890-fedc-ba9876543210", "investor": { "investor_key": "aaaa1111-bbbb-2222-cccc-dddd33334444", "name": "Investidor Exemplo S.A.", "person_type": "legal", "document_number": "12.345.678/0001-99", "distributor": { "distributor_key": "dddd4444-eeee-5555-ffff-aaaa66667777", "name": "Distribuidora Exemplo", "document_number": "98.765.432/0001-11", "account_data": { "bank": "341", "agency": "1234", "account": "56789-0" } } }, "status": "done", "net_value": 4750.0, "ir_value": 200.0, "iof_value": 50.0, "ir_compensation": 0.0, "iof_compensation": 0.0, "total_value": 5000.0, "payment_method": "regular", "payment_date": "2026-06-06", "status_events": [ { "status": "created", "event_datetime": "2026-06-01T10:00:00.000Z" }, { "status": "done", "event_datetime": "2026-06-06T09:00:00.000Z" } ], "amortizations": [ { "financial_application_key": "fa111111-2222-3333-4444-555566667777", "amortization_key": "am888888-9999-aaaa-bbbb-ccccddddeeee", "status": "settled", "principal_reduction": 2500.0, "acquisition_cost_reduction": 0.0, "yield_value": 300.0, "total_value": 2800.0, "ir_value": 100.0, "iof_value": 25.0, "taxable_yield_value": 300.0 } ], "payments": [ { "payment_key": "pp000000-1111-2222-3333-444455556666", "origin_key": "f1e2d3c4-b5a6-7890-fedc-ba9876543210", "total_value": 4750.0, "target_account": { "bank": "341", "agency": "1234", "account": "56789-0" }, "payment_type": "amortization_payment.investor", "payment_date": "2026-06-06", "status": "paid", "status_events": [ { "status": "paid", "event_datetime": "2026-06-06T09:15:00.000Z" } ] } ] } ], "issuance_serie": { "issuance_serie_key": "is111111-2222-3333-4444-555566667777", "name": "Série A - Cota Sênior", "serie": 1, "original_quota_value": 1.0, "current_quota_value": 1.05, "current_number_of_quotas": 1000000.0, "current_net_worth": 1050000.0, "current_principal_value": 1000000.0, "performance_fee_current_value": 0.0, "remuneration_type": "cdi_plus", "minimum_share_capital": 1000.0, "status": "active", "internal_code": "SR-001", "processing_method": "pro_rata", "operation_period_configuration": { "subscription_days": [1, 2, 3, 4, 5], "redemption_days": [1, 2, 3, 4, 5] }, "sub_class": { "sub_class_key": "sc222222-3333-4444-5555-666677778888", "name": "Classe Sênior", "subordination_level": 1, "fund_class": { "fund_class_key": "fc333333-4444-5555-6666-777788889999", "name": "Fundo de Investimento em Direitos Creditórios Exemplo", "short_name": "FIDC Exemplo", "document_number": "11.222.333/0001-44", "accounting_date": "2026-06-09", "sub_type": "exclusive", "tax_classification": "long_term", "condominum_type": "closed", "investment_category": "credit_rights", "prevent_payment": false, "manager": { "manager_key": "mg444444-5555-6666-7777-888899990000", "name": "Gestora Exemplo DTVM", "document_number": "55.666.777/0001-88" } } } } } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de solicitações de amortização. Veja tabela abaixo. | | `page` | integer | Número da página atual. | | `limit` | integer | Quantidade de registros por página. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada solicitação (objetos dentro de `data`) | Campo | Tipo | Descrição | |---|---|---| | `amortization_request_key` | string | Identificador único da solicitação (UUID). | | `type` | string | Tipo da amortização. Consulte os [enumeradores de tipo](#enumeradores-de-type) abaixo. | | `regime_type` | string | Regime de cálculo da amortização. Consulte os [enumeradores de regime](#enumeradores-de-regime_type) abaixo. | | `quotation_date` | string | Data de cotação no formato `YYYY-MM-DD`. | | `principal_percentage` | number | Percentual do principal a ser amortizado. Presente conforme o `regime_type`. | | `financial_application_yield_percentage` | number | Percentual de rendimento da aplicação financeira. Presente conforme o `regime_type`. | | `gross_value` | number | Valor bruto total da amortização em reais. | | `result_quota_value` | number | Valor da cota resultante após a amortização. | | `amortization_value` | number | Valor total a ser amortizado em reais. | | `net_value` | number | Valor líquido total após impostos em reais. | | `quota_percentage` | number | Percentual de cotas resgatadas. Presente conforme o `regime_type`. | | `status` | string | Status atual da solicitação. Consulte os [enumeradores de status](#enumeradores-de-status) abaixo. | | `status_events` | array | Histórico de transições de status. Omitido se `dto_filters_status_events=true`. Veja tabela abaixo. | | `investor_amortizations` | array | Lista de amortizações individuais por investidor. Omitido se `dto_filters_investor_amortizations=true`. Veja tabela abaixo. | | `issuance_serie` | object | Dados da série de emissão vinculada. Omitido se `dto_filters_issuance_serie=true`. Veja tabela abaixo. | #### Atributos de `status_events` | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Status do evento. | | `event_datetime` | string | Data e hora do evento no formato ISO 8601 (ex: `2026-06-01T10:00:00.000Z`). | #### Atributos de `investor_amortizations` | Campo | Tipo | Descrição | |---|---|---| | `investor_amortization_key` | string | Identificador único da amortização do investidor (UUID). | | `investor` | object | Dados do investidor. Veja tabela abaixo. | | `status` | string | Status da amortização do investidor. Consulte os [enumeradores de status do investidor](#enumeradores-de-status-do-investor_amortization) abaixo. | | `net_value` | number | Valor líquido a pagar ao investidor em reais. | | `ir_value` | number | Valor de IR retido em reais. | | `iof_value` | number | Valor de IOF retido em reais. | | `ir_compensation` | number | Compensação de IR em reais. | | `iof_compensation` | number | Compensação de IOF em reais. | | `total_value` | number | Valor total bruto em reais. Presente após o cálculo. | | `payment_method` | string | Método de pagamento. Consulte os [enumeradores de método de pagamento](#enumeradores-de-payment_method) abaixo. | | `payment_date` | string | Data prevista do pagamento no formato `YYYY-MM-DD`. | | `status_events` | array | Histórico de transições de status do investidor. Mesma estrutura de `status_events` da solicitação. | | `amortizations` | array | Detalhamento por aplicação financeira. Veja tabela abaixo. | | `payments` | array | Lista de pagamentos gerados. Veja tabela abaixo. | #### Atributos de `investor` | Campo | Tipo | Descrição | |---|---|---| | `investor_key` | string | Chave única do investidor (UUID). | | `name` | string | Nome do investidor. | | `person_type` | string | Tipo de pessoa (`natural` ou `legal`). | | `document_number` | string | CPF ou CNPJ do investidor. Presente quando disponível. | | `external_id` | string | Identificador externo do investidor. Presente quando informado. | | `external_distribution_key` | string | Chave de distribuição externa. Presente quando informada. | | `short_name` | string | Nome abreviado. Presente quando informado. | | `sub_type` | string | Subtipo do investidor. Presente quando informado. | | `distributor` | object | Dados da distribuidora vinculada. Veja tabela abaixo. | #### Atributos de `distributor` | Campo | Tipo | Descrição | |---|---|---| | `distributor_key` | string | Chave única da distribuidora (UUID). | | `name` | string | Nome da distribuidora. | | `document_number` | string | CNPJ da distribuidora. | | `account_data` | object | Dados bancários da distribuidora. | #### Atributos de `amortizations` {#amortizations} | Campo | Tipo | Descrição | |---|---|---| | `financial_application_key` | string | Chave da aplicação financeira (UUID). | | `amortization_key` | string | Chave única da amortização (UUID). | | `status` | string | Status da amortização. | | `principal_reduction` | number | Redução de principal em reais. | | `acquisition_cost_reduction` | number | Redução de custo de aquisição em reais. | | `yield_value` | number | Valor de rendimento em reais. Presente quando calculado. | | `total_value` | number | Valor total em reais. Presente quando calculado. | | `ir_value` | number | Valor de IR em reais. Presente quando calculado. | | `iof_value` | number | Valor de IOF em reais. Presente quando calculado. | | `taxable_yield_value` | number | Valor de rendimento tributável em reais. Presente quando calculado. | #### Atributos de `payments` | Campo | Tipo | Descrição | |---|---|---| | `payment_key` | string | Chave única do pagamento (UUID). | | `origin_key` | string | Chave da origem do pagamento (UUID). | | `total_value` | number | Valor total do pagamento em reais. | | `target_account` | object | Dados da conta de destino. | | `description` | string | Descrição do pagamento. Presente quando informada. | | `payment_type` | string | Tipo do pagamento. Consulte os [enumeradores de tipo de pagamento](#enumeradores-de-payment_type) abaixo. | | `payment_date` | string | Data do pagamento no formato `YYYY-MM-DD`. | | `status` | string | Status do pagamento. Consulte os [enumeradores de status do pagamento](#enumeradores-de-status-do-payment) abaixo. | | `deleted_at` | string | Data e hora de exclusão no formato ISO 8601. Presente apenas quando o pagamento foi cancelado. | | `status_events` | array | Histórico de transições de status do pagamento. Mesma estrutura de `status_events` da solicitação. | #### Atributos de `issuance_serie` | Campo | Tipo | Descrição | |---|---|---| | `issuance_serie_key` | string | Chave única da série de emissão (UUID). | | `name` | string | Nome da série de emissão. | | `serie` | integer | Número da série. | | `original_quota_value` | number | Valor original da cota em reais. | | `current_quota_value` | number | Valor atual da cota em reais (calculado como `current_net_worth / current_number_of_quotas`). | | `current_number_of_quotas` | number | Quantidade atual de cotas em circulação. | | `current_net_worth` | number | Patrimônio líquido atual em reais. | | `current_principal_value` | number | Valor de principal atual em reais. | | `performance_fee_current_value` | number | Valor atual de taxa de performance em reais. | | `remuneration_type` | string | Tipo de remuneração da série. | | `minimum_share_capital` | number | Capital mínimo em reais. | | `status` | string | Status da série de emissão. | | `internal_code` | string | Código interno da série. | | `processing_method` | string | Método de processamento (ex: `pro_rata`). | | `operation_period_configuration` | object | Configuração de períodos operacionais da série. | | `pre_fixed` | number | Taxa pré-fixada. Presente quando aplicável. | | `post_fixed` | object | Dados do indexador pós-fixado. Presente quando aplicável. | | `interest_rate_type` | string | Tipo de taxa de juros. Presente quando aplicável. | | `isin_code` | string | Código ISIN da série. Presente quando informado. | | `external_id` | string | Identificador externo. Presente quando informado. | | `specific_interest_rate_data` | object | Dados específicos de taxa de juros. Presente quando aplicável. | | `fixed_principal_value` | number | Valor de principal fixo. Presente quando aplicável. | | `sub_class` | object | Dados da subclasse vinculada. Veja tabela abaixo. | #### Atributos de `sub_class` | Campo | Tipo | Descrição | |---|---|---| | `sub_class_key` | string | Chave única da subclasse (UUID). | | `name` | string | Nome da subclasse. | | `subordination_level` | integer | Nível de subordinação da subclasse. | | `fund_class` | object | Dados da classe de fundo. Veja tabela abaixo. | #### Atributos de `fund_class` | Campo | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única da classe de fundo (UUID). | | `name` | string | Nome do fundo. | | `short_name` | string | Nome abreviado do fundo. | | `document_number` | string | CNPJ do fundo. | | `accounting_date` | string | Data contábil vigente no formato `YYYY-MM-DD`. | | `sub_type` | string | Subtipo do fundo. | | `tax_classification` | string | Classificação tributária do fundo. | | `condominum_type` | string | Tipo de condomínio do fundo. | | `investment_category` | string | Categoria de investimento. | | `prevent_payment` | boolean | Indica se pagamentos estão bloqueados para o fundo. | | `manager` | object | Dados do gestor do fundo. | | `administrator` | object | Dados do administrador. Presente quando informado. | | `integralization_account_key` | string | Chave da conta de integralização (UUID). Presente quando informada. | ## Enumeradores de `type` | Valor | Descrição | |---|---| | `scheduled_amortization` | Amortização programada/agendada | | `extraordinary_amortization` | Amortização extraordinária | ## Enumeradores de `regime_type` | Valor | Descrição | |---|---| | `cash_availability` | Baseado na disponibilidade de caixa | | `issuance_serie_principal_percentage` | Percentual do principal da série de emissão | | `quota_percentage` | Percentual de cotas | | `financial_application_principal_percentage` | Percentual do principal da aplicação financeira | | `net_value` | Valor líquido fixo | | `gross_value` | Valor bruto fixo | | `financial_application_yield_percentage` | Percentual de rendimento da aplicação financeira | ## Enumeradores de `status` | Status | Descrição | |---|---| | `created` | Solicitação criada | | `waiting_quotation_date` | Aguardando data de cotação | | `pending_inputs` | Aguardando dados de entrada | | `processing_calculation` | Cálculo em processamento | | `processing_investor_amortizations` | Processando amortizações dos investidores | | `pending_manual_approval` | Aguardando aprovação manual | | `processing_approval` | Aprovação em processamento | | `processing_issuance_serie_impacts` | Processando impactos na série de emissão | | `reprocessed` | Reprocessada | | `reproved` | Reprovada | | `done` | Concluída | ## Enumeradores de status do `investor_amortization` | Status | Descrição | |---|---| | `created` | Amortização do investidor criada | | `pending_quote` | Aguardando cotação | | `processing_approval` | Aprovação em processamento | | `pending_manual_approval` | Aguardando aprovação manual | | `done` | Concluída | | `reproved` | Reprovada | ## Enumeradores de `payment_method` | Valor | Descrição | |---|---| | `regular` | Pagamento padrão (TED/PIX) | | `b3` | Pagamento via B3 | ## Enumeradores de `payment_type` | Valor | Descrição | |---|---| | `amortization_payment.investor` | Pagamento de amortização ao investidor | | `amortization_payment.ir` | Recolhimento de IR da amortização | | `amortization_payment.iof` | Recolhimento de IOF da amortização | | `amortization_payment.collateral` | Pagamento de garantia da amortização | | `redemption.investor` | Pagamento de resgate ao investidor | | `redemption.ir` | Recolhimento de IR do resgate | | `redemption.iof` | Recolhimento de IOF do resgate | | `redemption.integralization_iof` | Recolhimento de IOF de integralização do resgate | | `redemption.tax_anticipation` | Antecipação de tributos do resgate | ## Enumeradores de status do `payment` | Status | Descrição | |---|---| | `created` | Pagamento criado | | `pending_payment` | Aguardando pagamento | | `pending_manual_approval` | Aguardando aprovação manual | | `pending_confirmation` | Aguardando confirmação | | `pending_accounting_date` | Aguardando data contábil | | `paid` | Pago | | `canceled` | Cancelado | --- # Consulta paginada de Aplicação Financeira URL: /documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras --- ### Requests Requisição por cotista: este endpoint retornará todas as aplicações financeiras de um cotista ENDPOINT /quota/investor/INVESTOR_KEY/financial_applications MÉTODO GET STATUS 200 Requisição por fundo: este endpoint retornará todas as aplicações financeiras de um fundo ENDPOINT /quota/fund_class/FUND_CLASS_KEY/financial_applications MÉTODO GET STATUS 200 ### Query Params | Parâmetro | Descrição | |------------------|--------------------------------------------------------------------------------------| | `quotation_date` | Data de cotização das aplicações | | `status` | Lista de **[Financial Application Status](#financial_application_status)** desejados | | `application_from_datetime` | Retorna apenas as aplicações com data/hora de aplicação maior ou igual ao valor informado. | | `application_to_datetime` | Retorna apenas as aplicações com data/hora de aplicação menor ou igual ao valor informado. | | `issuance_serie_key` | Filtra as aplicações por série de emissão | | `types` | Lista de tipos de aplicação desejados (ex.: primary_market, secondary_market) | | `fund_class_document_number` | Filtra por CNPJ da classe de fundo _(somente na consulta por cotista)_ | | `manager_key` | Filtra pelo gestor _(somente na consulta por cotista)_ | | `investor_name` | Filtra pelo nome do investidor _(somente na consulta por fundo)_ | | `investor_document_number` | Filtra pelo CPF/CNPJ do investidor _(somente na consulta por fundo)_ | ### Responses Caso 01: Consulta bem-sucedida ```json { "data": [ { "external_id": "", "financial_application_key": "UUID", "share_capital": 0.00, "investor_position": { "investor": { "investor_key": "UUID", "document_number": "999.999.999-99" | "99.999.999/9999-99", "name": "", "person_type": "natural_person" | "legal_person", "account_data": { "owner": { "name": "", "document_number": "99.999.999/9999-99" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, "distributor": { "distributor_key": "UUID", "document_number": "99.999.999/9999-99", "name": "", "account_data": { "owner": { "name": "", "document_number": "99.999.999/9999-99" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, } }, "total_net_worth": 0.00, "total_number_of_quotas": 0.00000000, "issuance_serie": {}, "investor_position_key":"UUID" }, "original_principal_value": 0.00000000, "current_principal_value": 0.00000000, "original_number_of_units": 0.00000000, "current_number_of_units": 0.00000000, "quotation_date": "yyyy-mm-dd", "application_datetime": "YYYY-MM-DDTHH:MM:SSZ", "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled", "status_events": [ { "event_datetime": "yyyy-mm-dd HH:MM:SS:ms", "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled", } ], "capital_returns": [ { "capital_return_key": "UUID", "origin_key": "UUID", "net_value": 0.00, "iof_value": 0.00, "ir_value": 0.00, "payment_date": "yyyy-mm-dd", "capital_return_date": "yyyy-mm-dd", "status": "", "capital_return_type": "", "number_of_units": "", } ], } ], "limit": 50, "page": 0, "is_last_page": true } ``` ### Page | Campo | Tipo | Descrição | |---------------|--------|------------------------------------------------------------------------------| | `data` | array | Lista de objetos de **[Financial Application](#financial_application)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última | ### Financial Application {#financial_application} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------------------------------------|------------| | `external_id` | string | Identificador externo | até 100 | | `financial_application_key` | string | Chave única de identificação da aplicação financeira | 36 | | `share_capital` | float | Valor do aporte | - | | `investor_position` | JSON | Objeto de **[Investor Position](#investor_position)** | - | | `original_principal_value` | float | Valor original de principal por cota | - | | `current_principal_value` | float | Valor atual de principal por cota | - | | `original_number_of_units` | float | Quantidade original de cotas | - | | `current_number_of_units` | float | Quantidade atual de cotas | - | | `quotation_date` | string | Data da cotização | - | | `application_datetime` | string | Data da criação da aplicação financeira | - | | `status` | string | Enumerador de **[Financial Application Status](#financial_application_status)** | - | | `status_events` | array | Lista de objetos de **[Status Event](#status_event)** | - | | `capital_returns` | array | Lista de objetos de **[Capital Return](#capital_return)** | - | ### Financial Application Status {#financial_application_status} | Enumerador | Descrição | |--------------------------|-------------------------------------------------| | `pending_payment` | Pendente pagamento | | `pending_quote` | Pendente cotização | | `quoted` | Cotizado | | `settled` | Totalmente amortizado | | `redeemed` | Totalmente resgatado | | `canceled` | cancelado | ### Investor Position {#investor_position} | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------------| | `investor` | JSON | Objeto de **[Investor](#investor)** | | `total_net_worth` | float | Patrimônio Líquido da posição do investidor | | `total_number_of_quotas` | float | Número de cotas da posição do investidor | | `issuance_serie` | JSON | Objeto de **[Issuance Serie](#issuance_serie)** | | `investor_position_key` | JSON | Chave única de identificação da posição do investidor | ### Status Event {#status_event} | Campo | Tipo | Descrição | |------------------|----------|----------------------------------------------------------------| | `status` | string | Status do evento | | `event_datetime` | string | Data e hora do evento | ### Investor | Campo | Tipo | Descrição | Caracteres | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome do investidor | até 255 | | `investor_key` | string | Chave única de identificação do investidor | 36 | | `document_number` | string | CPF/CNPJ do investidor | 14 ou 18 | | `person_type` | string | Pessoa Física / Pessoa Jurídica / Classe de Fundo | até 50 | | `distributor` | JSON | Objeto de **[Distributor](#distributor)** | - | | `account_data` | JSON | Objeto de **[Account Data](#account_data)** | - | ### Distributor | Campo | Tipo | Descrição | Caracteres | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome do distribuidor | até 255 | | `distributor_key` | string | Chave única de identificação do distribuidor | - | | `document_number` | string | CPF/CNPJ do distribuidor | 14 ou 18 | | `account_data` | JSON | Objeto de **[Account Data](#account_data)** | - | ### Account Data {#account_data} | Campo | Tipo | Descrição | |------------------------------|----------|-----------------------------------------------------------------------------| | `account_digit` | string | Dígito da conta bancária | | `account_branch` | string | N° da agência da conta bancária | | `account_number` | string | N° da conta bancária | | `financial_institution_code` | string | Código da instituição financeira | | `financial_institution_ispb` | string | Identificador no Sistema de Pagamento Brasileiro da instituição financeira | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da série de emissão | até 255 | | `issuance_serie_key` | string | Chave única de identificação da série de emissão | 36 | | `cetip_code` | string | Código da série de emissão como ativo na CETIP | 10 | | `start_date` | string | Data de início da série de emissão | 10 | | `maturity_date` | string | Data de vencimento da série de emissão | 10 | | `original_quota_value` | float | Valor de cota original | - | | `remuneration_type` | string | Curva de rendimento / Residual | até 50 | | `investment_category` | string | FIDC / Multimercado | até 50 | | `condominum_type` | string | Aberto / Fechado | até 50 | | `tax_classification` | string | Curto prazo / Longo prazo | até 50 | | `investment_restriction_type` | string | Sem restrição / Qualificado / Profissional | até 50 | | `minimum_share_capital` | float | Valor mínimo para aplicação | - | | `accounting_date` | string | Data contábil da série de emissão | 10 | | `sub_class` | JSON | Objeto de **[Sub Class](#sub_class)** | - | ### Sub Class {#sub_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da sub classe | até 255 | | `sub_class_key` | string | Chave única de identificação da sub classe | 36 | | `subordination_level` | int | Nível de subordinação da sub classe | - | | `fund_class` | JSON | Objeto de **[Fund Class](#fund_class)** | - | ### Fund Class {#fund_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da classe de fundo | até 255 | | `fund_class_key` | string | Chave única de identificação da classe de fundo | 36 | | `document_number` | string | CNPJ da classe de fundo | - | ### Capital Return {#capital_return} | Campo | Tipo | Descrição | |---------------------------|----------|----------------------------------------------------------------| | `capital_return_key` | string | Chave única de identificação do retorno de capital | | `origin_key` | string | Chave única de identificação da origem do retorno de capital | | `net_value` | float | Valor líquido do retorno de capital | | `iof_value` | float | Valor de IOF do retorno de capital | | `ir_value` | float | Valor de IR do retorno de capital | | `payment_date` | string | Data de pagamento do retorno de capital | | `capital_return_date` | string | Data de criação do retorno de capital | | `status` | string | Enviando para o Administrador / Pendente Pagamento / Pago | | `capital_return_type` | string | Amortização / Pedido de Resgate / Come-cotas | | `number_of_units` | float | N° de quotas do retorno de capital | --- # Consulta paginada de Fechamento das Aplicações Financeiras URL: /documentation/iaas/passivo/aplicacao_financeira/busca_paginada_fechamento_das_aplicacoes_financeiras --- ### Requests Requisição por classe de fundo ENDPOINT /quota/fund_class/FUND_CLASS_KEY/financial_application_closings MÉTODO GET STATUS 200 #### Query Params | Parâmetro | Descrição | |--------------------|--------------------------------------------------------------------------------------| | `accounting_date` | Data contábil específica de fechamento (formato `yyyy-mm-dd`) | | `from_date` | Data de início do período (formato `yyyy-mm-dd`) | | `to_date` | Data de fim do período (formato `yyyy-mm-dd`) | | `limit` | Limite de objetos recuperados por página (mínimo `0`, máximo `75`, padrão `75`) | | `page` | Número da página recuperada (mínimo `0`, padrão `0`) | :::warning Atenção É obrigatório enviar `accounting_date` **ou** a combinação de `from_date` e `to_date`. Caso nenhum desses parâmetros seja enviado, o recurso retornará erro de parâmetros obrigatórios ausentes. ::: Requisição por investidor e aplicação financeira ENDPOINT /quota/investor/INVESTOR_KEY/financial_application/FINANCIAL_APPLICATION_KEY/financial_application_closings MÉTODO GET STATUS 200 #### Query Params | Parâmetro | Descrição | |--------------------------------------|--------------------------------------------------------------------------------------| | `last_financial_application_closing` | Booleano. Quando `true`, retorna apenas o último fechamento da aplicação. Padrão: `false`. | | `limit` | Limite de objetos recuperados por página (mínimo `0`, máximo `500`, padrão `50`) | | `page` | Número da página recuperada (mínimo `0`, padrão `0`) | ### Responses Caso 01: Consulta bem-sucedida ```json { "data": [ { "financial_application": { "financial_application_key": "UUID", "share_capital": 0.00, "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled", "investor": { "investor_key": "UUID", "name": "", "person_type": "natural_person" | "legal_person", "document_number": "999.999.999-99" | "99.999.999/9999-99", "distributor": { "distributor_key": "UUID", "name": "", "document_number": "99.999.999/9999-99", "account_data": {} } }, "issuance_serie": {}, "financial_application_type": "regular", "payment_method": "regular" | "cetip" | "b3", "quotation_date": "yyyy-mm-dd", "current_principal_value": 0.00000000, "current_number_of_quotas": 0.00000000, "original_number_of_quotas": 0.00000000, "original_number_of_quotas_str": "0.00000000", "acquisition_cost": 0.00, "external_id": "", "redemptions": [], "amortizations": [], "status_events": [], "reserved_taxable_yields": [] }, "total_value": 0.00, "number_of_quotas": 0.00000000, "principal_value": 0.00, "acquisition_cost": 0.00, "yield_value": 0.00, "ir_value": 0.00, "iof_value": 0.00, "taxable_yield_value": 0.00, "accounting_date": "yyyy-mm-dd" } ], "limit": 75, "page": 0, "is_last_page": true } ``` :::caution **Atenção** Os campos abaixo do objeto `financial_application` são **condicionais** — só são retornados quando o dado existe no recurso: - `redemptions[]`, `amortizations[]`, `status_events[]`, `reserved_taxable_yields[]`: listas omitidas quando vazias. - `original_number_of_quotas` (e o sibling `original_number_of_quotas_str`), `current_principal_value`, `acquisition_cost`, `current_number_of_quotas`, `quotation_date`: preenchidos após o processamento de cotização da aplicação. - `payment_method`, `financial_application_type`, `external_id`: opcionais por aplicação — retornados quando informados na criação ou em atualização posterior. O envelope (`data`, `limit`, `page`, `is_last_page`) e os campos do objeto **[Financial Application Closing](#financial-application-closing)** estão sempre presentes na resposta. ::: ### Page | Campo | Tipo | Descrição | |---------------|--------|-----------------------------------------------------------------------------------------| | `data` | array | Lista de objetos de **[Financial Application Closing](#financial-application-closing)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última | ### Financial Application Closing | Campo | Tipo | Descrição | |-------------------------|----------|---------------------------------------------------------------| | `financial_application` | JSON | Objeto de **[Financial Application](#financial-application)** | | `total_value` | float | Valor total de fechamento da aplicação | | `number_of_quotas` | float | Número de cotas referente ao fechamento | | `principal_value` | float | Valor principal referente ao fechamento | | `acquisition_cost` | float | Custo de aquisição das cotas relacionadas ao fechamento | | `yield_value` | float | Valor do rendimento bruto | | `ir_value` | float | Valor de IR | | `iof_value` | float | Valor de IOF | | `taxable_yield_value` | float | Valor do rendimento tributável | | `accounting_date` | string | Data contábil referente ao fechamento da aplicação | ### Financial Application | Campo | Tipo | Descrição | |------------------------------------|----------|---------------------------------------------------------------------------------| | `financial_application_key` | string | Chave única de identificação da aplicação financeira | | `share_capital` | float | Valor do aporte | | `status` | string | Enumerador de **[Financial Application Status](#financial-application-status)** | | `investor` | JSON | Objeto de **[Investor](#investor)** | | `issuance_serie` | JSON | Objeto de **[Issuance Serie](#issuance-serie)** | | `redemptions` | array | Lista de objetos de **Redemption** *(condicional)* | | `amortizations` | array | Lista de objetos de **[Amortization](/documentation/iaas/passivo/amortizacao/listagem#amortizations)** *(condicional)* | | `status_events` | array | Lista de objetos de **[Status Event](#status_event)** *(condicional)* | | `reserved_taxable_yields` | array | Lista de objetos de **Reserved Taxable Yield** *(condicional)* | | `financial_application_type` | string | Tipo da aplicação financeira *(condicional)* | | `original_number_of_quotas` | float | Quantidade original de cotas *(condicional)* | | `original_number_of_quotas_str` | string | Versão string com precisão da quantidade original de cotas *(condicional)* | | `current_principal_value` | float | Valor atual de principal por cota *(condicional)* | | `acquisition_cost` | float | Custo de aquisição das cotas da aplicação *(condicional)* | | `current_number_of_quotas` | float | Quantidade atual de cotas *(condicional)* | | `payment_method` | string | Método de pagamento (`regular`, `cetip`, `b3`) *(condicional)* | | `quotation_date` | string | Data de cotização *(condicional)* | | `external_id` | string | Identificador externo *(condicional)* | ### Financial Application Status | Enumerador | Descrição | |-------------------|----------------------------| | `pending_payment` | Pendente pagamento | | `pending_quote` | Pendente cotização | | `quoted` | Cotizado | | `settled` | Totalmente amortizado | | `redeemed` | Totalmente resgatado | | `canceled` | Cancelado | ### Status Event {#status_event} | Campo | Tipo | Descrição | |------------------|----------|----------------------------------------------------------------| | `status` | string | Status do evento | | `event_datetime` | string | Data e hora do evento | ### Investor | Campo | Tipo | Descrição | |-----------------------------|----------|------------------------------------------------------| | `investor_key` | string | Chave única de identificação do investidor | | `name` | string | Nome do investidor | | `person_type` | string | `natural_person` / `legal_person` / `fund_class` | | `distributor` | JSON | Objeto de **[Distributor](#distributor)** | | `document_number` | string | CPF/CNPJ do investidor *(condicional)* | | `external_id` | string | Identificador externo do investidor *(condicional)* | | `external_distribution_key` | string | Chave externa de distribuição *(condicional)* | ### Distributor | Campo | Tipo | Descrição | |--------------------------|----------|---------------------------------------------------| | `distributor_key` | string | Chave única de identificação do distribuidor | | `name` | string | Nome do distribuidor | | `document_number` | string | CNPJ do distribuidor | | `account_data` | JSON | Objeto com dados bancários do distribuidor | ### Issuance Serie | Campo | Tipo | Descrição | |----------------------------------|----------|----------------------------------------------------------------------------------------------| | `issuance_serie_key` | string | Chave única de identificação da série de emissão | | `name` | string | Nome da série de emissão | | `serie` | string | Identificador da série | | `internal_code` | string | Código interno da série | | `status` | string | Enumerador de status da série de emissão | | `original_quota_value` | float | Valor de cota original | | `current_quota_value` | float | Valor de cota atual (calculado a partir de `current_net_worth` / `current_number_of_quotas`) | | `current_number_of_quotas` | float | Quantidade atual de cotas em circulação | | `current_net_worth` | float | Patrimônio líquido atual | | `current_principal_value` | float | Valor de principal atual | | `performance_fee_current_value` | float | Taxa de performance atual | | `minimum_share_capital` | float | Valor mínimo para aplicação | | `remuneration_type` | string | Tipo de remuneração (enumerador) | | `interest_rate_type` | string | Tipo de taxa de juros (enumerador) | | `processing_method` | string | Método de processamento da série (enumerador) | | `operation_period_configuration` | JSON | Configuração do período de operação | | `sub_class` | JSON | Objeto de **[Sub Class](#sub-class)** | | `pre_fixed` | JSON | Configuração pré-fixada *(condicional)* | | `post_fixed` | JSON | Configuração pós-fixada *(condicional)* | | `isin_code` | string | Código ISIN *(condicional)* | | `external_id` | string | Identificador externo da série de emissão *(condicional)* | | `specific_interest_rate_data` | JSON | Dados específicos da taxa de juros *(condicional)* | ### Sub Class | Campo | Tipo | Descrição | |------------------------|----------|---------------------------------------------------| | `sub_class_key` | string | Chave única de identificação da sub classe | | `name` | string | Nome da sub classe | | `subordination_level` | int | Nível de subordinação da sub classe | | `fund_class` | JSON | Objeto de **[Fund Class](#fund-class)** | ### Fund Class | Campo | Tipo | Descrição | |--------------------------------|----------|---------------------------------------------------| | `fund_class_key` | string | Chave única de identificação da classe de fundo | | `name` | string | Nome da classe de fundo | | `short_name` | string | Nome curto da classe de fundo | | `document_number` | string | CNPJ da classe de fundo | | `accounting_date` | string | Data contábil da classe de fundo | | `sub_type` | string | Subtipo da classe de fundo (enumerador) | | `tax_classification_id` | string | Classificação tributária (enumerador) | | `condominum_type_id` | string | Tipo de condomínio (enumerador) | | `investment_category_id` | string | Categoria de investimento (enumerador) | | `prevent_payment` | boolean | Flag de prevenção de pagamento | | `integralization_account_key` | string | Chave da conta de integralização | | `manager` | JSON | Objeto de **[Manager](#manager)** | ### Manager | Campo | Tipo | Descrição | |---------------------|----------|---------------------------------------------| | `manager_key` | string | Chave única de identificação do gestor | | `manager_name` | string | Nome do gestor | | `document_number` | string | CNPJ do gestor | --- # Consultar Aplicação Financeira por chave URL: /documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave --- ### Request ENDPOINT /quota/investor/INVESTOR_KEY/financial_application/FINANCIAL_APPLICATION_KEY MÉTODO GET STATUS 200 ### Responses Caso 01: Consulta bem-sucedida ```json { "external_id": "", "financial_application_key": "UUID", "share_capital": 0.00, "investor_position": { "investor": { "investor_key": "UUID", "document_number": "999.999.999-99" | "99.999.999/9999-99", "name": "", "person_type": "natural_person" | "legal_person", "account_data": { "owner": { "name": "", "document_number": "99.999.999/9999-99" },"issuance_serie": {}, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, "distributor": { "distributor_key": "UUID", "document_number": "99.999.999/9999-99", "name": "", "account_data": { "owner": { "name": "", "document_number": "99.999.999/9999-99" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, } }, "total_net_worth": 0.00, "total_number_of_quotas": 0.00000000, "investor_position_key": "UUID", "issuance_serie":{ "name":"1", "cetip_code":"0000000SN1", "start_date":"YYYY-MM-DD", "maturity_date":"YYYY-MM-DD", "original_quota_value":0.00000000000000, "remuneration_type":"yield_curve", "interest_rate_type":"post_fixed", "pre_fixed":{ "calendar_base":"workdays / calendar_360 / calendar_365", "monthly_rate":0.00000000000000 }, "post_fixed":{ "calendar_base":"workdays / calendar_360 / calendar_365", "indexer":"di / ipca", "rate":1, "lag":{ "reference":"daily / monthly", "amount":1 } }, "investment_category":"fidc / multi_market", "condominum_type":"open_ended / close_ended", "tax_classification":"short_term / long_term", "investment_restriction_type":"just_professional", "issuance_serie_key":"UUID", "minimum_share_capital":0.0, "accounting_date":"YYYY-MM-DD", "sub_class":{ "name":"COTA SÊNIOR", "sub_class_key":"UUID", "subordination_level":1, "fund_class":{ "name":"SAMPLE FUND CLASS NAME", "fund_class_key":"UUID", "document_number":"00.000.000/0000-00" } } } }, "original_principal_value": 0.00000000, "current_principal_value": 0.00000000, "original_number_of_units": 0.00000000, "current_number_of_units": 0.00000000, "quotation_date": "yyyy-mm-dd", "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled", "status_events": [ { "event_datetime": "yyyy-mm-dd HH:MM:SS:ms", "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled", } ], "capital_returns": [ { "capital_return_key": "UUID", "origin_key": "UUID", "net_value": 0.00, "iof_value": 0.00, "ir_value": 0.00, "payment_date": "yyyy-mm-dd", "capital_return_date": "yyyy-mm-dd", "status": "", "capital_return_type": "", "number_of_units": "", } ], } ``` ### Financial Application | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------------------------------------|------------| | `external_id` | string | Identificador externo | até 100 | | `financial_application_key` | string | Chave única de identificação da aplicação financeira | 36 | | `share_capital` | float | Valor do aporte | - | | `investor_position` | JSON | Objeto de **[Investor Position](#investor_position)** | - | | `original_principal_value` | float | Valor original de principal por cota | - | | `current_principal_value` | float | Valor atual de principal por cota | - | | `original_number_of_units` | float | Quantidade original de cotas | - | | `current_number_of_units` | float | Quantidade atual de cotas | - | | `quotation_date` | string | Data da cotização | - | | `status` | string | Enumerador de **[Financial Application Status](#financial_application_status)** | - | | `status_events` | array | Lista de objetos de **[Status Event](#status_event)** | - | | `capital_returns` | array | Lista de objetos de **[Capital Return](#capital_return)** | - | ### Financial Application Status {#financial_application_status} | Enumerador | Descrição | |--------------------------|-------------------------------------------------| | `pending_payment` | Pendente pagamento | | `pending_quote` | Pendente cotização | | `quoted` | Cotizado | | `settled` | Totalmente amortizado | | `redeemed` | Totalmente resgatado | | `canceled` | cancelado | ### Investor Position {#investor_position} | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------------| | `investor` | JSON | Objeto de **[Investor](#investor)** | | `total_net_worth` | float | Patrimônio Líquido da posição do investidor | | `total_number_of_quotas` | float | Número de cotas da posição do investidor | | `issuance_serie` | JSON | Objeto de **[Issuance Serie](#issuance_serie)** | | `investor_position_key` | JSON | Chave única de identificação da posição do investidor | ### Status Event {#status_event} | Campo | Tipo | Descrição | |------------------|----------|----------------------------------------------------------------| | `status` | string | Status do evento | | `event_datetime` | string | Data e hora do evento | ### Investor | Campo | Tipo | Descrição | Caracteres | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome do investidor | até 255 | | `investor_key` | string | Chave única de identificação do investidor | 36 | | `document_number` | string | CPF/CNPJ do investidor | 14 ou 18 | | `person_type` | string | Pessoa Física / Pessoa Jurídica / Classe de Fundo | até 50 | | `distributor` | JSON | Objeto de **[Distributor](#distributor)** | - | | `account_data` | JSON | Objeto de **[Account Data](#account_data)** | - | ### Distributor | Campo | Tipo | Descrição | Caracteres | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome do distribuidor | até 255 | | `distributor_key` | string | Chave única de identificação do distribuidor | - | | `document_number` | string | CPF/CNPJ do distribuidor | 14 ou 18 | | `account_data` | JSON | Objeto de **[Account Data](#account_data)** | - | ### Account Data {#account_data} | Campo | Tipo | Descrição | |------------------------------|----------|-----------------------------------------------------------------------------| | `account_digit` | string | Dígito da conta bancária | | `account_branch` | string | N° da agência da conta bancária | | `account_number` | string | N° da conta bancária | | `financial_institution_code` | string | Código da instituição financeira | | `financial_institution_ispb` | string | Identificador no Sistema de Pagamento Brasileiro da instituição financeira | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da série de emissão | até 255 | | `issuance_serie_key` | string | Chave única de identificação da série de emissão | 36 | | `cetip_code` | string | Código da série de emissão como ativo na CETIP | 10 | | `start_date` | string | Data de início da série de emissão | 10 | | `maturity_date` | string | Data de vencimento da série de emissão | 10 | | `original_quota_value` | float | Valor de cota original | - | | `remuneration_type` | string | Curva de rendimento / Residual | até 50 | | `investment_category` | string | FIDC / Multimercado | até 50 | | `condominum_type` | string | Aberto / Fechado | até 50 | | `tax_classification` | string | Curto prazo / Longo prazo | até 50 | | `investment_restriction_type` | string | Sem restrição / Qualificado / Profissional | até 50 | | `minimum_share_capital` | float | Valor mínimo para aplicação | - | | `accounting_date` | string | Data contábil da série de emissão | 10 | | `sub_class` | JSON | Objeto de **[Sub Class](#sub_class)** | - | ### Sub Class {#sub_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da sub classe | até 255 | | `sub_class_key` | string | Chave única de identificação da sub classe | 36 | | `subordination_level` | int | Nível de subordinação da sub classe | - | | `fund_class` | JSON | Objeto de **[Fund Class](#fund_class)** | - | ### Fund Class {#fund_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da classe de fundo | até 255 | | `fund_class_key` | string | Chave única de identificação da classe de fundo | 36 | | `document_number` | string | CNPJ da classe de fundo | - | ### Capital Return {#capital_return} | Campo | Tipo | Descrição | |---------------------------|----------|----------------------------------------------------------------| | `capital_return_key` | string | Chave única de identificação do retorno de capital | | `origin_key` | string | Chave única de identificação da origem do retorno de capital | | `net_value` | float | Valor líquido do retorno de capital | | `iof_value` | float | Valor de IOF do retorno de capital | | `ir_value` | float | Valor de IR do retorno de capital | | `payment_date` | string | Data de pagamento do retorno de capital | | `capital_return_date` | string | Data de criação do retorno de capital | | `status` | string | Enviando para o Administrador / Pendente Pagamento / Pago | | `capital_return_type` | string | Amortização / Pedido de Resgate / Come-cotas | | `number_of_units` | float | N° de quotas do retorno de capital | --- # Criar Aplicação Financeira URL: /documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira --- ### Request ENDPOINT /quota/investor/INVESTOR_KEY/financial_application MÉTODO POST STATUS 201 ```json title='Request Body' { "issuance_serie_key": "UUID", "share_capital": 0.00, "payment_method": "b3 / regular", "central_depositary": "unregistered / cetip", "quotation_date": "yyyy-mm-dd" } ``` :::note **Campos Obrigatórios**. - issuance_serie_key - share_capital ::: :::caution **Atenção** **payment_method** e **central_depositary** são campos opcionais, de modo que caso não sejam enviado seram considerados a opção marcada de default. - Isso será depreciado em próximas versões, tornando-se obrigatório o envio dos campos - Com **central_depositary** `cetip`, o **payment_method** pode ser `regular` ou `b3`. Com `unregistered`, apenas `regular` (`b3` não é permitido). ::: ### Body params | Campo | Tipo | Descrição | |-----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------| | `issuance_serie_key` | string | Chave única de identificação da Série de emissão | | `share_capital` | float | Valor da aplicação financeira | | `payment_method` | string | Método de Pagamento. Valores esperados:
• regular: Pix ou TED **(default)**
• b3: Via B3 | | `central_depositary` | string | Tipo de depositárias. Valores esperados:
• unregistered: Sem registradora
• cetip: Registado na Cetip **(default)** | | `quotation_date` | string | Data de cotização da aplicação, no formato yyyy-mm-dd (opcional) | ### Response ```json title='Response Body' { "financial_application_key": "UUID" } ``` --- # Aprovação manual de bloqueio de cotas URL: /documentation/iaas/passivo/bloqueio_de_cotas/aprovar_bloqueio_pendente_aprovacao --- ### Introdução Este recurso tem como objetivo detalhar o fluxo de aprovação manual de um bloqueio. :::warning Atenção O Bloqueio de cotas somente irá para pendente aprovação manual caso o valor do bloqueio ultrapasse o valor total do patrimônio em até **3.8%** ::: ### Aprovação ENDPOINT quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCk_KEY/pending_manual_approval/approve MÉTODO PUT STATUS 204 ### Reprovação ENDPOINT quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCk_KEY/pending_manual_approval/reprove MÉTODO PUT STATUS 204 --- # Consultar bloqueio de cotas URL: /documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas --- ### Introdução Este recurso tem como objetivo detalhar as informações de uma solicitação de **bloqueio de cotas** de um **investidor**. ### Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY MÉTODO GET STATUS 200 ### Response ```json { "quota_lock_key": "UUID", "status": "pending_documents", "original_locked_quotas": 0.0, "current_locked_quotas": 0.0, "original_locked_value": 0.0, "current_locked_value": 0.0, "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Recipient Mother Name" } }, "borrower": { "name": "Sample Borrower Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Borrower Mother Name" } }, "assets": [ { "asset_key": "UUID", "asset_type": "cce", "credit_operation": { "contract_number": "1000000001", "principal_value": 0.0, "interest_rate_type": "post_fixed", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360" }, "post_fixed": { "calendar_base": "workdays", "indexer": "di", "rate": 1, "lag": { "reference": "daily", "amount": 1 } } }, "documents": [ { "document_key": "UUID", "document_type": "asset_document" } ] } ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.0, "financial_value": 0.0 }, { "issuance_serie_key": "UUID", "number_of_quotas": 0.0, "financial_value": 0.0 } ], "documents": [ { "document_key": "UUID", "document_type": "collateral_contract" } ] }, "investor_positions_locks": [ { "investor_position_lock_key": "UUID", "investor_position_key": "UUID", "original_locked_quotas": 0.0, "current_locked_quotas": 0.0, "original_locked_value": 0.0, "current_locked_value": 0.0 } ] } ``` ### Quota Lock | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |------------------------------------------------------------------------|------------| | `quota_lock_key` | string | Identificador único do bloqueio de cotas | 36 | | `status` | string | Enumerador de tipo de bloqueio de cotas | até 255 | | `type` | string | Enumerador de tipo de bloqueio de cotas | até 255 | | `original_locked_quotas` | float | Quantidade original de cotas bloqueadas | - | | `current_locked_quotas` | float | Quantidade atual de cotas bloqueadas | - | | `original_locked_value` | float | Valor original do bloqueio | - | | `current_locked_value` | float | Valor atual do bloqueio | - | | `collateral` | JSON | Objeto de **[Garantia](#collateral)** | - | | `investor_positions_locks` | Array | Lista de objetos de **[Bloqueio de posição do investidor](#locked-investor-positions)** | - | ### Quota Lock Status | Enumerador | Descrição | |--------------------------|-----------------------| | `pending_documents` | Pendente documentos | | `pending_approval` | Pendente aprovação | | `denied` | Negado | | `approved` | Aprovado | ### Quota Lock Type | Enumerador | Descrição | |--------------------------|-----------------------| | `collateral` | Garantia | ### Collateral | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |-----------------------------------------------------------------------|------------| | `recipient` | JSON | Objeto de **[Beneficiário](#recipient)** | - | | `borrower` | JSON | Objeto de **[Tomador](#borrower)** | - | | `assets` | Array | Lista de objetos de **[Ativo](#asset)** | - | | `issuance_series` | Array | Lista de objetos de **[Série de emissão](#issuance_serie)** | - | | `documents` | Array | Lista de objetos de **[Documento da garantia](#document)** | - | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|-------------------------------------------------------|--------------| | `issuance_serie_key` | string | Chave da série de emissão | 36 | | `number_of_quotas` | float | Número de cotas bloqueadas | - | | `financial_value` | float | Valor financeiro bloqueado | - | ### Recipient | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |-----------------------------------------------------|------------| | `name` | string | Nome do beneficiário | até 255 | | `document_number` | string | CPF / CNPJ do beneficiário | 14 ou 18 | | `person_type` | string | Enumerador de pessoa física ou jurídica | até 255 | | `natural_person` | JSON | Objeto de **[Pessoa Física](#natural_person)** | - | | `legal_person` | JSON | Objeto de **[Pessoa Jurídica](#legal_person)** | - | ### Borrower | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |-----------------------------------------------------|------------| | `name` | string | Nome do tomador | até 255 | | `document_number` | string | CPF / CNPJ do tomador | 14 ou 18 | | `person_type` | string | Enumerador de pessoa física ou jurídica | até 255 | | `natural_person` | JSON | Objeto de **[Pessoa Física](#natural_person)** | - | | `legal_person` | JSON | Objeto de **[Pessoa Jurídica](#legal_person)** | - | ### Person Type | Enumerador | Descrição | |--------------------------|-----------------------| | `natural_person` | Pessoa física | | `legal_person` | Pessoa jurídica | ### Natural Person {#natural_person} | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |-----------------------------------------------------|------------| | `birthdate` | string | Data de nascimento | 10 | | `mother_name` | string | Nome da mãe | até 255 | ### Legal Person {#legal_person} | Campo | Tipo | Descrição | Caracteres | |------------------|----------|----------------------------------------------------------|--------------| | `activity_code` | string | Classificação Nacional das Atividades Econômicas (CNAE) | 10 | | `representatives`| array | Lista de objetos de **[Representative](#representative)**| - | ### Representative | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|------------------------------------------------|--------------| | `name` | string | Nome do representante | até 255 | | `document_number` | string | CPF do representante | 14 | ### Asset | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|---------------------------------------------------------------|--------------| | `asset_key` | string | Identificador único do ativo | até 255 | | `asset_type` | string | Enumerador de tipo de ativo | até 255 | | `status` | string | Enumerador de status de ativo | até 255 | | `credit_operation` | JSON | Objeto de **[Operação de Crédito](#credit_operation)** | - | | `documents` | Array | Lista de objetos de **[Documento do ativo](#document)** | - | ### Asset Status | Enumerador | Descrição | |--------------------------|-----------------------| | `pending_approval` | Pendente aprovação | | `done` | concluído | ### Document | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|---------------------------------------------------------------|--------------| | `document_key` | string | Identificador único do ativo | até 255 | | `document_type` | string | Enumerador de tipo de ativo | até 255 | ### Asset Type | Enumerador | Descrição | |--------------------------|-----------| | `ccb` | CCB | | `cce` | CCE | ### Credit Operation {#credit_operation} | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|-------------------------------------------------------|--------------| | `contract_number` | string | N° do contrato | até 255 | | `principal_value` | string | Valor de principal da operação | - | | `interest_rate_type` | string | Enumerador de pós-fixada / pré-fixada | até 255 | | `pre_fixed` | JSON | Objeto de **[Pré-fixada](#pre_fixed)** | - | | `post_fixed` | JSON | Objeto de **[Pós-fixada](#pos_fixed)** | - | ### Interest Rate Type | Enumerador | Descrição | |--------------------------|-----------------------| | `pre_fixed` | Pré-fixada | | `post_fixed` | Pós-fixada | ### Pre fixed {#pre_fixed} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|--------------------------------------------------------------|------------| | `calendar_base` | string | Enumerador de Dias úteis / calendário 360 / calendário 365 | até 255 | | `monthly_rate` | float | Taxa mensal | - | ### Post fixed {#pos_fixed} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|-----------------------------------------------------------------|------------| | `calendar_base` | string | Enumerador de Dias úteis / calendário 360 / calendário 365 | até 255 | | `indexer` | string | Enumerador de DI / IPCA | até 255 | | `rate` | float | Taxa | - | | `lag` | JSON | Objeto de **[Lag](#lag)** | - | ### calendar_base | Enumerador | Descrição | |--------------------------|-----------------------| | `workdays` | Dias úteis | | `calendar_360` | Calendário 360 dias | | `calendar_365` | Calendário 365 dias | ### Indexer | Enumerador | Descrição | |--------------------------|-----------------------| | `di` | DI | | `ipca` | IPCA | ### Lag | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `reference` | string | Enumerador de Diário / Mensal | até 255 | | `amount` | integer | Quantidade de lag | - | ### Reference | Enumerador | Descrição | |--------------------------|-----------------------| | `daily` | Diário | | `monthly` | Mensal | ### Locked Investor Positions | Campo | Tipo | Descrição | Caracteres | |---------------------------------|------- |-----------------------------------------------------------------------|------------| | `investor_position_lock_key` | string | Identificador único do bloqueio da posição do investor | 36 | | `investor_position_key` | string | Identificador único da posição do investidor | 36 | | `original_locked_quotas` | float | Quantidade original de cotas bloqueadas | - | | `current_locked_quotas` | float | Quantidade atual de cotas bloqueadas | - | | `original_locked_value` | float | Valor original do bloqueio | - | | `current_locked_value` | float | Valor atual do bloqueio | - | --- # Consultar bloqueio de cotas de um investidor URL: /documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas_de_um_investidor --- ### Introdução Este recurso tem como objetivo detalhar as informações de todas as solicitação de **bloqueio de cotas** de um **investidor**. ### Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_locks MÉTODO GET STATUS 200 ### Response ```json { "data": [ { "quota_lock_key": "UUID", "status": "pending_documents", "original_locked_quotas": 0.0, "current_locked_quotas": 0.0, "original_locked_value": 0.0, "current_locked_value": 0.0, "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Recipient Mother Name" } }, "borrower": { "name": "Sample Borrower Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Borrower Mother Name" } }, "assets": [ { "asset_key": "UUID", "asset_type": "cce", "credit_operation": { "contract_number": "1000000001", "principal_value": 0.0, "interest_rate_type": "post_fixed", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360" }, "post_fixed": { "calendar_base": "workdays", "indexer": "di", "rate": 1, "lag": { "reference": "daily", "amount": 1 } } }, "documents": [ { "document_key": "UUID", "document_type": "asset_document" } ] } ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.0, "financial_value": 0.0 }, { "issuance_serie_key": "UUID", "number_of_quotas": 0.0, "financial_value": 0.0 } ], "documents": [ { "document_key": "UUID", "document_type": "collateral_contract" } ] }, "investor_positions_locks": [ { "investor_position_lock_key": "UUID", "investor_position_key": "UUID", "original_locked_quotas": 0.0, "current_locked_quotas": 0.0, "original_locked_value": 0.0, "current_locked_value": 0.0 } ] }, { "quota_lock_key":"04eeaabc-cb40-484a-b730-85ed5aed7bbf", "status":"approved", "type":"lawsuit", "original_locked_value":"50000.00", "current_locked_value":"50000.00", "lawsuit":{ "protocol":"20250037746822", "lock_date":"2024-01-15", "unlock_date":"2024-01-16", "process_number":"13289520258250000", "document_number":"236.682.501-38", "requested_amount":50000.0 } } ], "page": 0, "is_last_page": true } ``` ### Quota Lock | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |------------------------------------------------------------------------|------------| | `quota_lock_key` | string | Identificador único do bloqueio de cotas | 36 | | `status` | string | Enumerador de tipo de bloqueio de cotas | até 255 | | `type` | string | Enumerador de tipo de bloqueio de cotas | até 255 | | `original_locked_quotas` | float | Quantidade original de cotas bloqueadas | - | | `current_locked_quotas` | float | Quantidade atual de cotas bloqueadas | - | | `original_locked_value` | float | Valor original do bloqueio | - | | `current_locked_value` | float | Valor atual do bloqueio | - | | `collateral` | JSON | Objeto de **[Garantia](#collateral)** | - | | `investor_positions_locks` | Array | Lista de objetos de **[Bloqueio de posição do investidor](#locked-investor-positions)** | - | ### Quota Lock Status | Enumerador | Descrição | |--------------------------|-----------------------| | `pending_documents` | Pendente documentos | | `pending_approval` | Pendente aprovação | | `denied` | Negado | | `approved` | Aprovado | ### Quota Lock Type | Enumerador | Descrição | |--------------------------|-----------------------| | `collateral` | Garantia | ### Collateral | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |-----------------------------------------------------------------------|------------| | `recipient` | JSON | Objeto de **[Beneficiário](#recipient)** | - | | `borrower` | JSON | Objeto de **[Tomador](#borrower)** | - | | `assets` | Array | Lista de objetos de **[Ativo](#asset)** | - | | `issuance_series` | Array | Lista de objetos de **[Série de emissão](#issuance_serie)** | - | | `documents` | Array | Lista de objetos de **[Documento da garantia](#document)** | - | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|-------------------------------------------------------|--------------| | `issuance_serie_key` | string | Chave da série de emissão | 36 | | `number_of_quotas` | float | Número de cotas bloqueadas | - | | `financial_value` | float | Valor financeiro bloqueado | - | ### Recipient | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |-----------------------------------------------------|------------| | `name` | string | Nome do beneficiário | até 255 | | `document_number` | string | CPF / CNPJ do beneficiário | 14 ou 18 | | `person_type` | string | Enumerador de pessoa física ou jurídica | até 255 | | `natural_person` | JSON | Objeto de **[Pessoa Física](#natural_person)** | - | | `legal_person` | JSON | Objeto de **[Pessoa Jurídica](#legal_person)** | - | ### Borrower | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |-----------------------------------------------------|------------| | `name` | string | Nome do tomador | até 255 | | `document_number` | string | CPF / CNPJ do tomador | 14 ou 18 | | `person_type` | string | Enumerador de pessoa física ou jurídica | até 255 | | `natural_person` | JSON | Objeto de **[Pessoa Física](#natural_person)** | - | | `legal_person` | JSON | Objeto de **[Pessoa Jurídica](#legal_person)** | - | ### Person Type | Enumerador | Descrição | |--------------------------|-----------------------| | `natural_person` | Pessoa física | | `legal_person` | Pessoa jurídica | ### Natural Person {#natural_person} | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |-----------------------------------------------------|------------| | `birthdate` | string | Data de nascimento | 10 | | `mother_name` | string | Nome da mãe | até 255 | ### Legal Person {#legal_person} | Campo | Tipo | Descrição | Caracteres | |------------------|----------|----------------------------------------------------------|--------------| | `activity_code` | string | Classificação Nacional das Atividades Econômicas (CNAE) | 10 | | `representatives`| array | Lista de objetos de **[Representative](#representative)**| - | ### Representative | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|------------------------------------------------|--------------| | `name` | string | Nome do representante | até 255 | | `document_number` | string | CPF do representante | 14 | ### Asset | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|---------------------------------------------------------------|--------------| | `asset_key` | string | Identificador único do ativo | até 255 | | `asset_type` | string | Enumerador de tipo de ativo | até 255 | | `status` | string | Enumerador de status de ativo | até 255 | | `credit_operation` | JSON | Objeto de **[Operação de Crédito](#credit_operation)** | - | | `documents` | Array | Lista de objetos de **[Documento do ativo](#document)** | - | ### Asset Status | Enumerador | Descrição | |--------------------------|-----------------------| | `pending_approval` | Pendente aprovação | | `done` | concluído | ### Document | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|---------------------------------------------------------------|--------------| | `document_key` | string | Identificador único do ativo | até 255 | | `document_type` | string | Enumerador de tipo de ativo | até 255 | ### Asset Type | Enumerador | Descrição | |--------------------------|-----------| | `ccb` | CCB | | `cce` | CCE | ### Credit Operation {#credit_operation} | Campo | Tipo | Descrição | Caracteres | |-----------------------------------|----------|-------------------------------------------------------|--------------| | `contract_number` | string | N° do contrato | até 255 | | `principal_value` | string | Valor de principal da operação | - | | `interest_rate_type` | string | Enumerador de pós-fixada / pré-fixada | até 255 | | `pre_fixed` | JSON | Objeto de **[Pré-fixada](#pre_fixed)** | - | | `post_fixed` | JSON | Objeto de **[Pós-fixada](#pos_fixed)** | - | ### Interest Rate Type | Enumerador | Descrição | |--------------------------|-----------------------| | `pre_fixed` | Pré-fixada | | `post_fixed` | Pós-fixada | ### Pre fixed {#pre_fixed} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|--------------------------------------------------------------|------------| | `calendar_base` | string | Enumerador de Dias úteis / calendário 360 / calendário 365 | até 255 | | `monthly_rate` | float | Taxa mensal | - | ### Post fixed {#pos_fixed} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|-----------------------------------------------------------------|------------| | `calendar_base` | string | Enumerador de Dias úteis / calendário 360 / calendário 365 | até 255 | | `indexer` | string | Enumerador de DI / IPCA | até 255 | | `rate` | float | Taxa | - | | `lag` | JSON | Objeto de **[Lag](#lag)** | - | ### calendar_base | Enumerador | Descrição | |--------------------------|-----------------------| | `workdays` | Dias úteis | | `calendar_360` | Calendário 360 dias | | `calendar_365` | Calendário 365 dias | ### Indexer | Enumerador | Descrição | |--------------------------|-----------------------| | `di` | DI | | `ipca` | IPCA | ### Lag | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `reference` | string | Enumerador de Diário / Mensal | até 255 | | `amount` | integer | Quantidade de lag | - | ### Reference | Enumerador | Descrição | |--------------------------|-----------------------| | `daily` | Diário | | `monthly` | Mensal | ### Locked Investor Positions | Campo | Tipo | Descrição | Caracteres | |---------------------------------|------- |-----------------------------------------------------------------------|------------| | `investor_position_lock_key` | string | Identificador único do bloqueio da posição do investor | 36 | | `investor_position_key` | string | Identificador único da posição do investidor | 36 | | `original_locked_quotas` | float | Quantidade original de cotas bloqueadas | - | | `current_locked_quotas` | float | Quantidade atual de cotas bloqueadas | - | | `original_locked_value` | float | Valor original do bloqueio | - | | `current_locked_value` | float | Valor atual do bloqueio | - | --- # Enviar Documento da Garantia URL: /documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_da_garantia --- ### Introdução Este recurso tem como objetivo nos enviar o **documento** relacionado a formalização da **garantia** ao qual se está solicitando o **bloqueio de cotas** ### Input / Output: Como ***input*** deve ser enviado o **tipo do documento** e o **base 64** do documento. Segue abaixo exemplo. Como ***output*** será entregue uma ***collateral_document_key***. A ***collateral_document_key*** é utilizada para identificar o **documento da garantia** enviado. ### Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/collateral/COLLATERAL_KEY/document MÉTODO POST STATUS 201 ### Request body ```json title='Request Body' { "document_type": "collateral_contract", "document_b64" : "B64" } ``` ### Collateral Document | Campo | Tipo | Descrição | Caracteres | Obrigatório | |------------------|--------|------------------------------------------------------------|------------|-------------| | `document_type` | string | Enumerador de tipo de documento da garantia | até 255 | Sim | | `document_b64` | string | Conteúdo do documento codificado em base64 | - | Sim | ### Document Type | Enumerador | Descrição | |------------------------|------------------------| | `collateral_contract` | Contrato de garantia | | `rental_contract` | Contrato de aluguel | ### Response ```json title='Response Body' { "collateral_document_key": "UUID" } ``` --- # Enviar Documento do Ativo URL: /documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_do_ativo --- ### Introdução Este recurso tem como objetivo nos enviar o **documento** do **ativo** que é objeto da **garantia** ao qual se está solicitando o **bloqueio de cotas** ### Input / Output: Como ***input*** deve ser enviado o **tipo do documento** e o **base 64** do documento. Segue abaixo exemplo. Como ***output*** será entregue uma ***asset_document_key***. A ***asset_document_key*** é utilizada para identificar o **documento do ativo** enviado. ### Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/collateral/COLLATERAL_KEY/asset/ASSET_KEY/document MÉTODO POST STATUS 201 ### Request body ```json title='Request Body' { "document_type": "asset_document", "document_b64" : "B64" } ``` ### Response ```json title='Response Body' { "asset_document_key": "UUID" } ``` --- # Execução de garantia URL: /documentation/iaas/passivo/bloqueio_de_cotas/execucao_de_garantia --- ### Introdução Este recurso tem como objetivo **executar uma garantia** constituída sobre as cotas de um **investidor**, convertendo o bloqueio em pagamento ao **credor**. Diferente dos demais eventos de bloqueio, a execução de garantia gera um **pedido de resgate** na classe do fundo e o valor apurado é pago **nominalmente ao credor** cadastrado na garantia — não ao investidor. A posição do investidor é reduzida na proporção das cotas resgatadas. ### Pré-requisitos Antes de solicitar a execução, confirme que: | Requisito | Detalhe | |-----------|---------| | Bloqueio aprovado | O bloqueio de cotas deve estar no status `approved`. | | Bloqueio do tipo garantia | Apenas bloqueios com o objeto `collateral` são executáveis. Bloqueios de penhora judicial não são. | | Credor identificado | `collateral.recipient` deve conter `name` e `document_number`. | | Conta bancária do credor | `collateral.recipient.bank_account` deve conter `account_number`, `account_branch`, `account_digit` e `financial_institution_ispb`. | O cadastro do credor e da conta bancária é feito no momento da [solicitação de bloqueio de cotas](./solicitar_bloqueio_de_cotas.md). Uma execução solicitada sobre uma garantia com cadastro incompleto **não é registrada**. :::warning Atenção A conta bancária informada em `collateral.recipient.bank_account` é a **conta do credor** e é o destino do pagamento da execução. Não confundir com `collateral.bank_account_key`, que identifica uma conta **do investidor** e não participa da execução. ::: ### Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/investor_position_lock/INVESTOR_POSITION_LOCK_KEY/event MÉTODO POST STATUS 201 Execução de garantia ```json { "type": "collateral_execution", "net_value": 1000.00 } ``` ### Collateral Execution Event | Campo | Tipo | Descrição | Caracteres | Obrigatório | |--------------|--------|------------------------------------------------------------------------|------------|-------------| | `type` | string | Enumerador do tipo de evento. Para execução de garantia: `collateral_execution` | até 255 | Sim | | `net_value` | float | Valor líquido a ser executado e pago ao credor | - | Sim | O valor informado em `net_value` não pode exceder o valor financeiro bloqueado no momento da solicitação. ### Response Execução registrada ```json { "investor_position_lock_event_key": "UUID" } ``` | Campo | Tipo | Descrição | Caracteres | |------------------------------------|--------|-------------------------------------------------------|------------| | `investor_position_lock_event_key` | string | Identificador do evento de execução criado | 36 | ### O que acontece após a solicitação 1. O evento de execução é registrado com o status `pending_processing`. Os valores bloqueados **permanecem integralmente bloqueados** neste momento. 2. Um pedido de resgate do tipo `net_value_redemption` é aberto automaticamente na classe do fundo, no valor informado. 3. O pedido de resgate é cotizado no ciclo normal da classe. O pagamento é emitido para a conta do credor, **líquido de IR e IOF**. 4. Com a cotização concluída, a quantidade de cotas efetivamente resgatada é abatida do bloqueio e o evento passa para `done`. Caso o pedido de resgate seja cancelado antes da cotização, o evento de execução passa para `canceled` e os valores bloqueados são **preservados integralmente** — não há baixa parcial. ### Event Status | Enumerador | Descrição | |-----------------------|-------------------------------------------------------------------------------| | `pending_processing` | Execução registrada, aguardando a cotização do pedido de resgate | | `done` | Execução concluída, cotas abatidas do bloqueio | | `canceled` | Execução cancelada, valores bloqueados preservados | ### Acompanhamento O status da execução é consultado pelo endpoint de [consulta de bloqueio de cotas](./consulta_de_bloqueio_de_cotas.md), no objeto `investor_position_locks[].events[]`. Evento na consulta de bloqueio ```json { "investor_position_locks": [ { "investor_position_lock_key": "UUID", "current_locked_quotas": 100.00000000000000, "events": [ { "quota_lock_event_key": "UUID", "type": "collateral_execution", "status": "pending_processing" } ] } ] } ``` :::note Na resposta da consulta, o identificador do evento é retornado no campo `quota_lock_event_key`. Ele corresponde ao `investor_position_lock_event_key` devolvido na criação. ::: Concluída a execução, o mesmo evento passa a apresentar `status: "done"` e o campo `new_locked_quotas` com a quantidade de cotas remanescente no bloqueio. Não há webhook dedicado a eventos de execução de garantia. Os webhooks disponíveis para bloqueio de cotas estão descritos em [Webhooks de bloqueio de cota](./webhooks_de_bloqueio_de_cota.md). ### Erros | Status | Código | Descrição | |--------|-------------|---------------------------------------------------------------------------------| | 400 | `QLK000044` | O `net_value` informado é nulo, zero ou negativo | | 400 | `QLK000042` | O `net_value` informado excede o valor bloqueado | | 400 | `QLK000036` | O agente selecionado não é o solicitante do bloqueio | | 404 | `QLK000022` | Bloqueio de cotas não encontrado | | 404 | `QLK000037` | Posição bloqueada não encontrada | --- # Reduzir bloqueio de cotas URL: /documentation/iaas/passivo/bloqueio_de_cotas/reduzir_bloqueio_de_cotas --- ### Introdução Este recurso tem como objetivo reduzir o valor de **bloqueio de cotas** de um **investidor**. ### Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/investor_position_lock/INVESTOR_POSITION_LOCK_KEY/event MÉTODO POST STATUS 201 Redução de valor bloqueado ```json { "type": "decrease_locked_value", "new_locked_value": 0.00 } ``` Redução de quantidade de cotas bloqueadas ```json { "type": "decrease_locked_quotas", "new_locked_quotas": 0.00 } ``` Execução de garantia ```json { "type": "collateral_execution", "net_value": 0.00 } ``` ### Locked Investor Position Event | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|------- |-----------------------------------------------------------|------------|-------------| | `type` | string | Enumerador de tipo de evento | até 255 | Sim | | `new_locked_value` | float | Novo valor financeiro bloqueado | - | Não | | `new_locked_quotas` | float | Nova quantidade de cotas bloqueadas | - | Não | | `net_value` | float | Valor líquido apurado na execução de garantia | - | Não | Obrigatoriamente um — e apenas um — entre `new_locked_value`, `new_locked_quotas` e `net_value` deve ser enviado. ### Event Type | Enumerador | Descrição | |---------------------------|--------------------------------------------------| | `decrease_locked_quotas` | Diminuir quantidade de cotas bloqueadas | | `decrease_locked_value` | Diminuir valor financeiro bloqueado | | `collateral_execution` | Execução de garantia | O evento `collateral_execution` tem fluxo, pré-requisitos e acompanhamento próprios, descritos em [Execução de garantia](./execucao_de_garantia.md). --- # Solicitar bloqueio de cotas URL: /documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas --- ### Introdução Este recurso tem como objetivo criar uma solicitação de **bloqueio de cotas** de um **investidor**. ### Input / Output: Deve ser enviado o **tipo de bloqueio** e a informação específica do tipo de bloqueio. Como ***output*** será entregue a ***quota_lock_key*** que representa o **bloqueio de cota**. ### Request ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock MÉTODO POST STATUS 201 Bloqueio de cotas por garantia - CCE - pessoa física ```json { "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Recipient Mother Name", } }, "borrower": { "name": "Sample Borrower Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Borrower Mother Name", } }, "assets": [ { "asset_type": "cce", "credit_operation": { "contract_number": "1000000001", "principal_value": 0.0, "interest_rate_type": "post_fixed", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360", }, "post_fixed": { "calendar_base": "workdays", "indexer": "di", "rate": 1, "lag": { "reference": "daily", "amount": 1 }, }, }, }, ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00, }, { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00, }, ], "bank_account_key": "UUID" }, } ``` Bloqueio de cotas por garantia - CCE - pessoa jurídica ```json { "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "000.000.000-00", "person_type": "legal_person", "legal_person": { "activity_code": "00.00-0-00", "representatives": [ { "name": "Sample Recipient Representative Name", "document_number": "000.000.000-00", } ], } }, "borrower": { "name": "Sample Borrower Name", "document_number": "000.000.000-00", "person_type": "legal_person", "legal_person": { "activity_code": "00.00-0-00", "representatives": [ { "name": "Sample Borrower Representative Name", "document_number": "000.000.000-00", } ], } }, "assets": [ { "asset_type": "cce", "credit_operation": { "contract_number": "1000000001", "principal_value": 0.0, "interest_rate_type": "post_fixed", "pre_fixed": { "monthly_rate": 0.0, "calendar_base": "calendar_360", }, "post_fixed": { "calendar_base": "workdays", "indexer": "di", "rate": 1, "lag": { "reference": "daily", "amount": 1 }, }, }, }, ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00, }, { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00, }, ], "bank_account_key": "UUID" }, } ``` Bloqueio de cotas por garantia - contrato de aluguel - pessoa física ```json { "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Recipient Mother Name", } }, "borrower": { "name": "Sample Borrower Name", "document_number": "000.000.000-00", "person_type": "natural_person", "natural_person": { "birthdate": "YYYY-MM-DD", "mother_name": "Sample Borrower Mother Name", } }, "assets": [ { "asset_type": "rental_contract", "rental_contract": { "monthly_value": 0.0, "property_address": { "street": "Sample Street", "number": "123", "neighborhood": "Sample Neighborhood", "city": "Sample City", "uf": "SP", "complement": "Sample Complement", "postal_code": "00000-000", "country": "BRA" }, "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD", "readjustment_index": 0.0 } } ], "issuance_series": [ { "issuance_serie_key": "UUID", "number_of_quotas": 0.00, "financial_value": 0.00, } ], "bank_account_key": "UUID" }, } ``` Bloqueio de cotas por garantia - contrato de aluguel - pessoa jurídica ```json { "type": "collateral", "collateral": { "recipient": { "name": "Sample Recipient Name", "document_number": "00.000.000/0000-00", "person_type": "legal_person", "legal_person": { "activity_code": "00.00-0-00", "representatives": [ { "name": "Sample Recipient Representative Name", "document_number": "000.000.000-00", } ], } }, "borrower": { "name": "Sample Borrower Name", "document_number": "00.000.000/0000-00", "person_type": "legal_person", "legal_person": { "activity_code": "00.00-0-00", "representatives": [ { "name": "Sample Borrower Representative Name", "document_number": "000.000.000-00", } ], } }, "assets": [ { "asset_type": "rental_contract", "rental_contract": { "monthly_value": 0.0, "property_address": { "street": "Sample Street", "number": "123", "neighborhood": "Sample Neighborhood", "city": "Sample City", "uf": "SP", "complement": "Sample Complement", "postal_code": "00000-000", "country": "BRA" }, "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD", "readjustment_index": 0.0 } } ], "issuance_series": [ { "issuance_serie_key": "UUID", "financial_application_keys": [ "UUID", "UUID" ] } ], "bank_account_key": "UUID" }, } ``` ### Quota Lock | Campo | Tipo | Descrição | Caracteres | |-----------------------------|------- |------------------------------------------------------------------|------------| | `type` | string | Enumerador de tipo de bloqueio de cotas | até 255 | | `collateral` | string | Objeto de **[Garantia](#collateral)** | - | ### Quota Lock Type | Enumerador | Descrição | |--------------------------|-----------------------| | `collateral` | Garantia | ### Collateral | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|------- |------------------------------------------------------------------|------------|-------------| | `recipient` | JSON | Objeto de **[Beneficiário](#recipient)** | - | Sim | | `borrower` | JSON | Objeto de **[Tomador](#borrower)** | - | Sim | | `assets` | Array | Lista de objetos de **[Ativo](#asset)** | - | Sim | | `issuance_series` | Array | Lista de objetos de **[Série de emissão](#issuance_serie)** | - | Sim | | `bank_account_key` | string | UUID da conta bancária associada à garantia | - | Não | ### Recipient | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|------- |-----------------------------------------------------|------------|-------------| | `name` | string | Nome do beneficiário | até 255 | Sim | | `document_number` | string | CPF / CNPJ do beneficiário | 14 ou 18 | Sim | | `person_type` | string | Enumerador de pessoa física ou jurídica | até 255 | Sim | | `natural_person` | JSON | Objeto de **[Pessoa Física](#natural_person)** | - | Não | | `legal_person` | JSON | Objeto de **[Pessoa Jurídica](#legal_person)** | - | Não | ### Borrower | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|------- |-----------------------------------------------------|------------|------------ | | `name` | string | Nome do tomador | até 255 | Sim | | `document_number` | string | CPF / CNPJ do tomador | 14 ou 18 | Sim | | `person_type` | string | Enumerador de pessoa física ou jurídica | até 255 | Sim | | `natural_person` | JSON | Objeto de **[Pessoa Física](#natural_person)** | - | Não | | `legal_person` | JSON | Objeto de **[Pessoa Jurídica](#legal_person)** | - | Não | ### Person Type | Enumerador | Descrição | |--------------------------|-----------------------| | `natural_person` | Pessoa física | | `legal_person` | Pessoa jurídica | ### Natural Person {#natural_person} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------|------- |-----------------------------------------------------|------------|-------------| | `birthdate` | string | Data de nascimento | 10 | Sim | | `mother_name` | string | Nome da mãe | até 255 | Sim | ### Legal Person {#legal_person} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |------------------|----------|----------------------------------------------------------|--------------|-------------| | `activity_code` | string | Classificação Nacional das Atividades Econômicas (CNAE) | 10 | Sim | | `representatives`| array | Lista de objetos de **[Representative](#representative)**| - | Sim | ### Representative | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------------|----------|------------------------------------------------|--------------|-------------| | `name` | string | Nome do representante | até 255 | Sim | | `document_number` | string | CPF do representante | 14 | Sim | ### Asset | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------------|----------|--------------------------------------------------------|--------------|-------------| | `asset_type` | string | Enumerador de tipo de ativo | até 255 | Sim | | `credit_operation` | JSON | Objeto de **[Operação de Crédito](#credit_operation)** | - | Não | | `rental_contract` | JSON | Objeto de **[Contrato de Aluguel](#rental_contract)** | - | Não | ### Asset Type | Enumerador | Descrição | |--------------------------|-----------------------| | `ccb` | CCB | | `cce` | CCE | | `rental_contract` | Contrato de aluguel | ### Credit Operation {#credit_operation} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------------|----------|-------------------------------------------------------|--------------|-------------| | `contract_number` | string | N° do contrato | até 255 | Sim | | `principal_value` | string | Valor de principal da operação | - | Sim | | `interest_rate_type` | string | Enumerador de Pós-fixada / pré-fixada | até 255 | Sim | | `pre_fixed` | JSON | Objeto de **[Pré-fixada](#pre_fixed)** | - | Não | | `post_fixed` | JSON | Objeto de **[Pós-fixada](#pos_fixed)** | - | Não | ### Interest Rate Type | Enumerador | Descrição | |--------------------------|-----------------------| | `pre_fixed` | Pré-fixada | | `post_fixed` | Pós-fixada | ### Pre fixed {#pre_fixed} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|--------------------------------------------------------------|------------| | `calendar_base` | string | Enumerador de Dias úteis / calendário 360 / calendário 365 | até 255 | | `monthly_rate` | float | Taxa mensal | - | ### Post fixed {#pos_fixed} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|-----------------------------------------------------------------|------------| | `calendar_base` | string | Enumerador de Dias úteis / calendário 360 / calendário 365 | até 255 | | `indexer` | string | Enumerador de DI / IPCA | até 255 | | `rate` | float | Taxa | - | | `lag` | JSON | Objeto de **[Lag](#lag)** | - | ### calendar_base | Enumerador | Descrição | |--------------------------|-----------------------| | `workdays` | Dias úteis | | `calendar_360` | Calendário 360 dias | | `calendar_365` | Calendário 365 dias | ### Indexer | Enumerador | Descrição | |--------------------------|-----------------------| | `di` | DI | | `ipca` | IPCA | ### Lag | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `reference` | string | Enumerador de Diário / Mensal | até 255 | | `amount` | integer | Quantidade de lag | - | ### Reference | Enumerador | Descrição | |--------------------------|-----------------------| | `daily` | Diário | | `monthly` | Mensal | ### Rental Contract {#rental_contract} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |----------------------|----------|-------------------------------------------------------|--------------|-------------| | `monthly_value` | float | Valor mensal do aluguel | - | Sim | | `property_address` | JSON | Objeto de **[Endereço](#address)** do imóvel | - | Sim | | `start_date` | string | Data de início do contrato (YYYY-MM-DD) | 10 | Sim | | `end_date` | string | Data de término do contrato (YYYY-MM-DD) | 10 | Sim | | `readjustment_index` | float | Índice de reajuste do contrato | - | Não | ### Address | Campo | Tipo | Descrição | Caracteres | Obrigatório | |----------------|----------|--------------------------------------------------|--------------|-------------| | `street` | string | Logradouro | até 255 | Não | | `number` | string | Número | - | Não | | `neighborhood` | string | Bairro | até 255 | Não | | `city` | string | Cidade | até 255 | Não | | `uf` | string | Unidade federativa (sigla de 2 letras) | 2 | Não | | `complement` | string | Complemento | até 255 | Não | | `postal_code` | string | CEP no formato `00000-000` | 9 | Não | | `country` | string | Código do país (3 letras) | 3 | Não | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | Caracteres | Obrigatório | |-----------------------------------|----------|-------------------------------------------------------|--------------|-------------| | `issuance_serie_key` | string | Chave da série de emissão | 36 | Sim | | `number_of_quotas` | float | Número de cotas a serem bloqueadas | - | Não | | `financial_value` | float | Valor financeiro a ser bloqueador | - | Não | ### Responses ```json title='Response Body' { "quota_lock_key": "UUID" } ``` --- # Webhook de bloqueio de cotas URL: /documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota --- ### Introdução Abaixo estão os detalhes sobre os webhooks enviados durante o processo de **bloqueio de cotas**. Bloqueio aprovado ```json { "webhook_type": "quota_lock.quota_lock_status_change", "webhook_datetime": "2024-12-05T00:00:00Z", "data": { "status": "approved", "quota_lock_key": "UUID" } } ``` Bloqueio reprovado ```json { "webhook_type": "quota_lock.quota_lock_status_change", "webhook_datetime": "2024-12-05T00:00:00Z", "data": { "status": "denied", "quota_lock_key": "UUID" } } ``` --- # Consulta paginada de investidores por classe de fundo URL: /documentation/iaas/passivo/consultas/consulta_investidores_classe_fundo Retorna **investidores que possuem aplicação financeira** vinculada à classe de fundo informada (via séries de emissão e subclasses), de forma paginada. Permite filtrar por documento, nome e **data contábil** do fundo. ## Request ENDPOINT /quota/fund_class/{fund_class_key}/investors MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`).| | `limit` | integer | opcional | Registros por página. Padrão: `20`. Máximo: `500`. | | `document_number` | string | opcional | Filtra pelo documento do investidor com pontuação. | | `reference_date` | string (data) | opcional | Restringe a registros em que a **data contábil da classe de fundo** (`accounting_date`) é igual à data informada (formato aceito pelo servidor para parâmetros de data, tipicamente `YYYY-MM-DD`). | ```python title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/investors?page=0&limit=25&reference_date=2024-04-01 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "12.345.678/0001-90", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "12.345.678/0001-90" }, "account_digit": "1", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "341", "financial_institution_ispb": "60746948" } }, "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Maria Cotista Silva", "person_type": "natural_person", "document_number": "123.456.789-00", "external_id": "ext-inv-001", "external_distribution_key": null }, { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "12.345.678/0001-90", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "12.345.678/0001-90" }, "account_digit": "1", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "341", "financial_institution_ispb": "60746948" } }, "investor_key": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Investimentos PJ Ltda", "person_type": "legal_person", "document_number": "98.765.432/0001-10", "external_id": null, "external_distribution_key": "dist-key-7721" } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de investidores. | | `page` | integer | Página atual. | | `limit` | integer | Tamanho da página. | | `is_last_page` | boolean | Indica fim da paginação. | #### Campos de cada investidor em `data` | Campo | Tipo | Descrição | |---|---|---| | `investor_key` | string | Identificador único do investidor (UUID). | | `name` | string | Nome. | | `person_type` | string | Tipo de pessoa (enumerador, ex.: `natural_person`, `legal_person`). | | `document_number` | string | Documento, quando houver. | | `distributor` | object | Dados da distribuidora (`distributor_key`, `document_number`, `name`, `account_data`). | | `external_id` | string | Opcional — identificador externo. | | `external_distribution_key` | string | Opcional — chave de distribuição externa. | ## Possíveis erros STATUS 404 **Classe de fundo não encontrada** ```json { "title": " Fund Class not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "A classe com chave {fund_class_key} não foi encontrado.", "code": "QTA000002" } ``` --- # Consulta paginada de posições de cotistas por classe de fundo URL: /documentation/iaas/passivo/consultas/consulta_posicoes_cotistas_classe_fundo Endpoint de consulta paginada que retorna as **posições por investidor e série de emissão** em uma classe de fundo: cotistas com saldo de cotas na aplicação financeira, com valor de cota obtido do fechamento mais recente da série. Utilize `document_number` para filtrar um cotista específico. ## Request ENDPOINT /quota/fund_class/{fund_class_key}/investor_positions MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `20`. Máximo: `100`. | | `document_number` | string | opcional | Filtra pelo documento do investidor (com pontuação). | ```python title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/investor_positions?page=0&limit=20&document_number=123.456.789-00 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "investor": { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "12.345.678/0001-90", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "12.345.678/0001-90" }, "account_digit": "1", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "341", "financial_institution_ispb": "60746948" } }, "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Maria Cotista Silva", "person_type": "natural_person", "document_number": "123.456.789-00", "external_id": "ext-inv-001", "external_distribution_key": null }, "issuance_serie": { "issuance_serie_key": "c3d4e5f6-a7b8-9012-cdef-123456789012", "original_quota_value": 1.0, "current_number_of_quotas": 500000.0, "current_net_worth": 525000.75, "current_principal_value": 500000.0, "performance_fee_current_value": 0.0, "remuneration_type": "yield_curve", "minimum_share_capital": 1000.0, "interest_rate_type": "post_fixed", "name": "Série Única", "serie": 1, "sub_class": { "name": "Cota Sênior", "sub_class_key": "d4e5f6a7-b8c9-0123-def0-234567890123", "subordination_level": 1, "fund_class": { "name": "Fundo Exemplo FIDC", "short_name": "FEX", "document_number": "12.345.678/0001-90", "fund_class_key": "e5f6a7b8-c9d0-1234-ef01-345678901234", "accounting_date": "2024-06-01", "sub_type": "fidc", "tax_classification_id": "long_term", "condominum_type_id": "open_ended", "investment_category_id": "fidc", "prevent_payment": false, "integralization_account_key": null, "manager": { "manager_key": "f6a7b8c9-d0e1-2345-f012-456789012345", "document_number": "98.765.432/0001-10", "manager_name": "Gestora Exemplo S.A." } } }, "status": "active", "internal_code": "INT-FEX-01", "processing_method": "standard", "operation_period_configuration": { "subscription": {}, "redemption": {} }, "current_quota_value": 1.0500015, "post_fixed": { "calendar_base": "calendar_252", "indexer": "cdi", "rate": 1.0, "lag": { "reference": "daily", "amount": 1 } }, "isin_code": "BRSTREXTFID6", "external_id": null, "specific_interest_rate_data": null }, "number_of_quotas": 10000.0, "quota_value": 1.05234567 } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de posições. Cada item agrega **investidor**, **série de emissão**, **quantidade de cotas** e **valor de cota** (`quota_value` quando existir fechamento). | | `page` | integer | Página atual. | | `limit` | integer | Tamanho da página solicitado. | | `is_last_page` | boolean | Indica se não há mais registros após esta página. | #### Objeto em `data` | Campo | Tipo | Descrição | |---|---|---| | `investor` | object | Dados do cotista e da distribuidora . | | `issuance_serie` | object | Série de emissão da posição, incluindo `sub_class` e `fund_class` aninhados. | | `number_of_quotas` | number | Soma das cotas da aplicação financeira para aquele investidor e série. | | `quota_value` | number | Valor de cota do fechamento mais recente da série; omitido se não houver fechamento disponível. | Campos opcionais ou nulos em `issuance_serie` (como `pre_fixed`, `external_id`, `integralization_account_key`) podem variar conforme o cadastro da série. Para mais contexto sobre séries, consulte [Consulta paginada de séries de emissão](/documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao). ## Possíveis erros STATUS 404 **Classe de fundo não encontrada** ```json { "title": " Fund Class not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "A classe com chave {fund_class_key} não foi encontrado.", "code": "QTA000002" } ``` STATUS 404 **Gestor não encontrado** ```json { "title": "Manager not Found", "description": "Manager with Key {manager_key} was not found", "translation": "O gestor com chave {manager_key} nao foi encontrado", "code": "QTA00053" } ``` --- # Consulta paginada do Mapa de Evolução de Cotas URL: /documentation/iaas/passivo/consultas/consultar_mapa_de_evolucao_de_cotas ### Request ENDPOINT /composition/fund_class/FUND-CLASS-KEY/issuance_serie/ISSUANCE-SERIE-KEY/quota_evolution_map MÉTODO GET STATUS 200 ### Params | Parâmetro | Tipo | Obrigatório | Descrição | | -------------------- | ------ | ----------- | ------------------------- | | `fund_class_key` | `UUID` | Sim | Chave do fundo | | `issuance_serie_key` | `UUID` | Sim | Chave da série de emissão | ### Query Params | Parâmetro | Tipo | Obrigatório | Descrição | | ---------------- | ------------ | ----------- | ------------------------------------------------ | | `reference_date` | `YYYY-MM-DD` | Condicional | Data única de referência para consulta | | `start_date` | `YYYY-MM-DD` | Condicional | Data inicial do intervalo | | `end_date` | `YYYY-MM-DD` | Condicional | Data final do intervalo | | `limit` | `int` | Não | Quantidade de registros por página (default: 10) | | `page` | `int` | Não | Página atual (default: 0) | :::warning Atenção É obrigatório passar um dos filtros de data, reference_date trás o mec de uma data especifica, o conjunto de start_date e end_date vai trazer o mec em um range de datas. Caso nenhum dos dois filtros seja enviado, você receberá um erro: CMP000018 ::: Caso 01: Retorno com uma data ```json { "data": [ { "gross_net_worth": 10867777.38, "net_net_worth": 10867777.38, "gross_quota_value": 1.855893979904, "net_quota_value": 1.855893979904, "number_of_quotas": 5855818.003441199, "composition_date": "2025-05-04", "applied_value": 0.0, "applied_quotas": 0.0, "redeemed_value": 0.0, "redeemed_quotas": 0.0, "amortized_value": 0.0, "tax_anticipated_value": 0.0, "tax_anticipated_quotas": 0.0, "daily_rentability": 0.0006, "monthly_rentability": 0.0072, "yearly_rentability": 0.0898 }, ], "is_last_page": true, "page": 0, "limit": 10 } ``` ### Quota Evolution Map | Campo | Tipo | Descrição | | ------------------------ | ------ | --------------------------------------------------------------- | | `gross_net_worth` | number | Patrimônio bruto no dia da composição | | `net_net_worth` | number | Patrimônio líquido no dia da composição | | `gross_quota_value` | number | Valor bruto da cota | | `net_quota_value` | number | Valor líquido da cota | | `number_of_quotas` | number | Quantidade total de cotas no dia | | `composition_date` | string | Data da composição (formato: `YYYY-MM-DD`) | | `applied_value` | number | Valor aplicado no dia | | `applied_quotas` | number | Quantidade de cotas aplicadas no dia | | `redeemed_value` | number | Valor resgatado no dia | | `redeemed_quotas` | number | Quantidade de cotas resgatadas no dia | | `amortized_value` | number | Valor amortizado no dia | | `tax_anticipated_value` | number | Valor de imposto antecipado no dia | | `tax_anticipated_quotas` | number | Quantidade de cotas com imposto antecipado no dia | | `daily_rentability` | number | Rentabilidade diária (formato decimal, ex: `0.0007` para 0.07%) | | `monthly_rentability` | number | Rentabilidade mensal (formato decimal, ex: `0.0060` para 0.60%) | | `yearly_rentability` | number | Rentabilidade anual (formato decimal, ex: `0.096` para 9.6%) | --- # Consulta paginada de Séries de Emissão URL: /documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao ### Request ENDPOINT /quota/issuance_series MÉTODO GET STATUS 200 ### Query Params | Parâmetro | Descrição | |-------------------------------|---------------------------------------------------------------------------| | `issuance_serie_key` | Chave única de identificação da série de emissão | | `fund_class_document_number` | CNPJ do fundo relacionado à série de emissão | :::warning Atenção Durante o processo de integração será exigido um meio de autenticação da hash enviada. ::: Caso 01: Retorno com uma série de emissão ```json { "data": [ { "name": "Sample Issuance Serie Name", "investment_category": "fidc", "condominum_type": "open_ended", "tax_classification": "long_term", "investment_restriction_type": "professional", "remuneration_type": "residual", "issuance_serie_key": "UUID", "minimum_share_capital": 0.0, "accounting_date": "YYYY-MM-DD", "start_date": "YYYY-MM-DD", "original_quota_value": 1.0, "serie": 1, "maturity_date": "YYYY-MM-DD", "sub_class": { "name": "Sample Sub Class Name", "sub_class_key": "UUID", "subordination_level": 0, "fund_class": { "name": "Sample Fund Name", "fund_class_key": "UUID", "document_number": "00.000.000/0000-00", "administrator": { "name": "Sample Administrator Name", "administrator_key": "UUID", "document_number": "00.000.000/0000-00" } } } } ], "limit": 50, "page": 0, "is_last_page": true } ``` ### Issuance Serie | Campo | Tipo | Descrição | |-------------------------------|--------|---------------------------------------------------------------------------| | `name` | string | Nome da série de emissão | | `investment_category` | string | Categoria de investimento (ex: fidc) | | `condominium_type` | string | Tipo de condomínio (`open_ended` ou `closed_ended`) | | `tax_classification` | string | Classificação fiscal (ex: `long_term`) | | `investment_restriction_type` | string | Tipo de restrição ao investimento (ex: `professional`) | | `remuneration_type` | string | Tipo de remuneração (ex: `residual`) | | `issuance_serie_key` | string | Chave única de identificação da série | | `minimum_share_capital` | number | Capital mínimo da série | | `accounting_date` | string | Data contábil da série | | `start_date` | string | Data de início da série | | `original_quota_value` | number | Valor original da cota | | `serie` | number | Número da série | | `maturity_date` | string | Data de vencimento da série | | `sub_class` | JSON | Objeto de **[Sub Class](#sub-class)** com informações da subclasse | ### Sub Class | Campo | Tipo | Descrição | |--------------------|--------|---------------------------------------------------------------------| | `name` | string | Nome da subclasse | | `sub_class_key` | string | Chave única da subclasse | | `subordination_level` | number | Nível de subordinação | | `fund_class` | JSON | Objeto de **[Fund Class](#fund-class)** com informações do fundo | ### Fund Class | Campo | Tipo | Descrição | |-------------------|--------|---------------------------------------------------------------------------------------| | `fund_class_key` | string | Chave única de identificação do fundo | | `document_number` | string | CNPJ do fundo | | `name` | string | Nome do fundo | | `administrator` | JSON | Objeto de **[Administrator](#administrator)** com informações do administrador | ### Administrator | Campo | Tipo | Descrição | |---------------------|--------|------------------------------------------------| | `administrator_key` | string | Chave única de identificação do administrador | | `name` | string | Nome do administrador | | `document_number` | string | CNPJ do administrador | --- # Consulta paginada de Fundos URL: /documentation/iaas/passivo/consultas/consultar_todos_fundos --- :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de **Distribuidor**. ::: ### Request ENDPOINT /quota/fund_classes MÉTODO GET STATUS 200 ### Query Params | Parâmetro | Descrição | |------------------------------|--------------------------------------------------------------------------------------| | `document_number` | Documento do fundo | | `fund_class_key` | Chave única de identificação do fundo | :::warning Atenção Durante o processo de integração será exigido um meio de autenticação da hash enviada. ::: Caso 01: Retorno com apenas um fundo ```json { "data": [ { "name":"SAMPLE FUND CLASS NAME", "fund_class_key":"UUID", "document_number":"00.000.000/0000-00", "administrator":{ "name":"SAMPLE ADMINISTRATOR NAME", "administrator_key":"UUID", "document_number":"00.000.000/0000-00" } } ], "limit": 50, "page": 0, "is_last_page": true } ``` ### Fund Class | Campo | Tipo | Descrição | | ----------------- | ------ | ------------------------------------------------------------------------------------- | | `fund_class_key` | string | Chave única de identificação do fundo | | `document_number` | string | CNPJ do fundo | | `name` | string | Nome do fundo | | `administrator` | JSON | Objeto de **[Administrator](#administrator)** com informações do administrador | ### Administrator | Campo | Tipo | Descrição | | ------------------- | ------ | ---------------------------------------------- | | `administrator_key` | string | Chave única de identificação do administrador | | `name` | string | Nome do administrador | | `document_number` | string | CNPJ do administrador | --- # Enviar Boletim de Subscrição Assinado URL: /documentation/iaas/passivo/controle_de_oferta/enviar_boletim_de_subscricao_assinado --- ### Introdução Este recurso tem como objetivo nos enviar a comprovação de assinatura do **boletim de subscrição** de um **investidor** a uma **oferta de cotas** de um fundo. :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de **Distribuidor**. ::: ### Input / Output: Como ***input*** deve ser enviada as informações relacionadas a subscrição, UUID da **oferta de cotas** do fundo que o investidor subscreveu e, **tipo de assinatura** e dependendo da assinatura o conteúdo necessário para validação. Segue abaixo exemplo. Como ***output*** será entregue uma ***subscription_note_key***. A ***subscription_note_key*** é utilizada para identificar o **boletim de subscrição**. ### Request ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/signed_subscription_note MÉTODO POST STATUS 201 ### Request body ```json title='Request Body' { "number_of_quotas": 0.0, "original_subscription_note_value": 0.0, "start_date": "YYYY-MM-DD", "maturity_date": "YYYY-MM-DD", "quota_offering_key": "UUID", "transaction_type": "ted | b3", "signature_method": "opt_in", "opt_in_hash" : "OPT_IN_HASH" } ``` :::warning Atenção Durante o processo de integração será exigido um meio de autenticação da hash enviada. ::: ### Response ```json title='Response Body' { "subscription_note_key": "UUID" } ``` --- # Recuperando Informações sobre Boletim de Subscrição URL: /documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao --- ### Request ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/subscription_notes MÉTODO GET :::warning Atenção O endpoint acima está disponível apenas para integrações que exercem o papel de **Distribuidor**. ::: ENDPOINT /quota_offering_control/fund_class/FUND_CLASS_KEY/subscription_notes MÉTODO GET :::warning Atenção O endpoint acima está disponível apenas para integrações que exercem o papel de **Gestor**. ::: ### Responses STATUS 200 Caso 01: Investidor com um Boletim de Subscrição ```json { "data":[ { "subscription_note_key":"UUID", "quota_offering":{ "quota_offering_key":"UUID", "status":"active / closed", "original_quota_offering_value":0.00, "issued_number_of_quotas":0.00000000, "remaining_quota_offering_value":0.00, "start_date":"YYYY-MM-DD", "issuance_serie":{ "name":"1", "issuance_serie_key":"UUID", "sub_class":{ "name":"SÊNIOR", "sub_class_key":"UUID", "subordination_level":1, "fund_class":{ "fund_class_key":"UUID", "name":"SAMPLE FUND CLASS NAME", "document_number":"00.000.000/0000-00", "short_name":"SAMPLE FUND CLASS SHORT NAME" } }, "classification":"general / qualified / professional", "market_type":"primary / secondary" }, "type":"public / private", "data":{ "type":"public / private", "cvm_registration":{ "date":"YYYY-MM-DD", "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000" }, "lead_coordinator":{ "name":"SAMPLE LEAD COORDINATOR NAME", "address":{ "uf":"SP", "city":"São Paulo", "number":"0000", "street":"Sample street name", "complement":"Sample complement" }, "document_number":"00.000.000/0000-00" }, "original_quota_offering_value":0.00 } }, "investor":{ "distributor":{ "distributor_key":"UUID", "document_number":"00.000.000/0000-00", "name":"Sample Distributor Name" }, "investor_key":"UUID", "document_number":"00.000.000/0000-00", "name":"SAMPLE INVESTOR NAME", "person_type":"natural_person / legal_person" }, "status":"send_to_generate_document / pending_document / pending_signature / canceled / active / sold_off", "transaction_type":"b3 / ted", "original_subscription_note_value":0.00, "issued_number_of_quotas":0.00000000, "remaining_subscription_note_value":0.00, "start_date":"YYYY-MM-DD", "financial_application_events":[ { "financial_application_event_key":"UUID", "financial_application_key":"UUID", "type":"consume_value", "share_capital":0.00, "event_datetime":"YYYY-MM-DD HH:MM:SS" }, { "financial_application_event_key":"UUID", "financial_application_key":"UUID", "type":"update_quotas", "number_of_quotas":0.00, "event_datetime":"YYYY-MM-DD HH:MM:SS" }, { "financial_application_event_key":"UUID", "financial_application_key":"UUID", "type":"cancel", "event_datetime":"YYYY-MM-DD HH:MM:SS" } ] } ], "limit":50, "page":0, "is_last_page":true } ``` Caso 02: Investidor sem Boletim de Subscrição ```json { "data":[], "limit":50, "page":0, "is_last_page":true } ``` ### Response Fields | Campo | Tipo | Descrição | |---------------|--------|----------------------------------------------------------------| | `data` | array | Lista de objetos de **[Subscription Note](#subscription-note)**| | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última | ### Observação TIPO * significa que o campo pode ser nulo, como no exemplo abaixo: | Tipo | |----------| | string * | ### Subscription Note | Campo | Tipo | Descrição | |---------------------------|----------|-------------------------------------------------------------------------------------------------------| | `subscription_note_key` | string | Chave única de identificação do boletim de subscrição | | `quota_offering` | JSON | Objeto de **[Quota Offering](#quota-offering)** | | `investor` | JSON | Objeto de **[Investor](#investor)** | | `status` | string | Enviar para gerar documento / Pendente documento / Pendente assinatura / Cancelado / Ativo / Esgotado | | `transaction_type` | string | B3 / TED | | `original_subscription_note_value` | float | Valor original do boletim de subscrição | | `issued_number_of_quotas` | float | Quantidade de cotas emitidas | | `remaining_subscription_note_value` | float | Valor restante do boletim de subscrição | | `start_date` | string | Data inicial do boletim de subscrição | | `financial_application_events`| array | Lista de objetos de **[Financial Application Event](#financial-application-event)** | | `maturity_date` | string* | Data de vencimento | | `original_number_of_quotas`| string* | Número do cotas emitidas | ### Quota Offering | Campo | Tipo | Descrição | |-----------------------------------|----------|-----------------------------------------------------------------------------------------| | `quota_offering_key` | string | Chave única de identificação da oferta | | `status` | string | Ativa / Fechada | | `original_quota_offering_value` | float | Valor original da oferta | | `issued_number_of_quotas` | float | Quantidade de cotas subscritas | | `remaining_quota_offering_value` | float | Valor restante da oferta | | `start_date` | string | Data inicial da oferta | | `issuance_serie` | string | Objeto de **[Issuance Serie](#issuance-serie)** | | `type` | string | Tipo da oferta pública/privada | | `cvm_registration` | JSON *| Dados do registro CVM | | `lead_coordinator` | JSON *| Dados do coordenador líder | | `maturity_date` | string *| Data de vencimento | | `original_number_of_quotas` | string *| Número do cotas emitidas | cvm_registration ```json { "date":"YYYY-MM-DD", "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000" } ``` lead_coordinator ```json { "name":"SAMPLE LEAD COORDINATOR NAME", "address":{ "uf":"SP", "city":"São Paulo", "number":"0000", "street":"Sample street name", "complement":"Sample complement" }, "document_number":"00.000.000/0000-00" } ``` ### Financial Application Event | Campo | Tipo | Descrição | |-----------------------------------|----------|-----------------------------------------------------------------------------------------| | `financial_application_key` | string | Chave única de identificação da aplicação financeira | | `financial_application_event_key` | string | Chave única de identificação do evento da aplicação financeira | | `type` | string | Consumir valor / Atualizar cotas / Cancelar | | `event_datetime` | string | Data e hora do evento | | `share_capital` | float *| Valor do aporte da aplicação financeira *SOMENTE APARECE QUANDO FOR 'consume_value' | | `number_of_quotas` | float *| Número de cotas da aplicação financeira *SOMENTE APARECE QUANDO FOR 'update_quotas' | ### Issuance Serie | Campo | Tipo | Descrição | |-------------------------------|----------|---------------------------------------------------| | `name` | string | Nome da série de emissão | | `issuance_serie_key` | string | Chave única de identificação da série de emissão | | `sub_class` | JSON | Objeto de **[Sub Class](#sub-class)** | | `classification` | string | Profissional / Qualificado / Geral | | `market_type` | string | Primário / Secundário | | `serie` | integer | Curva de rendimento / Residual | ### Sub Class | Campo | Tipo | Descrição | |-------------------------------|----------|---------------------------------------------------| | `name` | string | Nome da sub classe | | `sub_class_key` | string | Chave única de identificação da sub classe | | `subordination_level` | int | Nível de subordinação da sub classe | | `fund_class` | JSON | Objeto de **[Fund Class](#fund-class)** | ### Fund Class | Campo | Tipo | Descrição | |-------------------------------|----------|---------------------------------------------------| | `name` | string | Nome da classe de fundo | | `fund_class_key` | string | Chave única de identificação da classe de fundo | | `document_number` | string | CNPJ da classe de fundo | | `short_name` | string | Nome reduzido da classe de fundo | ### Investor | Campo | Tipo | Descrição | |--------------------------|----------|---------------------------------------------------| | `name` | string | Nome do investidor | | `investor_key` | string | Chave única de identificação do investidor | | `document_number` | string | CPF/CNPJ do investidor | | `person_type` | string | Pessoa Física / Pessoa Jurídica / Classe de Fundo | | `distributor` | JSON | Objeto de **[Distributor](#distributor)** | ### Distributor | Campo | Tipo | Descrição | |--------------------------|----------|---------------------------------------------------| | `name` | string | Nome do distribuidor | | `distributor_key` | string | Chave única de identificação do distribuidor | | `document_number` | string | CPF/CNPJ do distribuidor | --- # Recuperando Informações sobre as Ofertas URL: /documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas --- ### Request ENDPOINT /quota_offering_control/fund_class/FUND_CLASS_KEY/quota_offerings MÉTODO GET :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de **Gestor**. ::: ### Responses STATUS 200 ### Query Params | Parâmetro | Descrição | |------------------------------|--------------------------------------------------------------------------------------| | `sub_class_key` | Chave única de identificação da sub classe | | `issuance_serie_key` | Chave única de identificação da série de emissão | Caso 01: Fundo com uma Oferta ```json { "data":[{ "quota_offering":{ "quota_offering_key":"UUID", "status":"active / closed", "original_quota_offering_value":0.00, "issued_number_of_quotas":0.00000000, "remaining_quota_offering_value":0.00, "start_date":"YYYY-MM-DD", "issuance_serie":{ "name":"1", "issuance_serie_key":"UUID", "sub_class":{ "name":"SÊNIOR", "sub_class_key":"UUID", "subordination_level":1, "fund_class":{ "fund_class_key":"UUID", "name":"SAMPLE FUND CLASS NAME", "document_number":"00.000.000/0000-00", "short_name":"SAMPLE FUND CLASS SHORT NAME" } }, "classification":"general / qualified / professional", "market_type":"primary / secondary" }, "type":"public / private", "data":{ "type":"public / private", "cvm_registration":{ "date":"YYYY-MM-DD", "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000" }, "lead_coordinator":{ "name":"SAMPLE LEAD COORDINATOR NAME", "address":{ "uf":"SP", "city":"São Paulo", "number":"0000", "street":"Sample street name", "complement":"Sample complement" }, "document_number":"00.000.000/0000-00" }, "original_quota_offering_value":0.00 } } } ], "limit":50, "page":0, "is_last_page":true } ``` Caso 02: Fundo sem uma Oferta ```json { "data":[], "limit":50, "page":0, "is_last_page":true } ``` ### Response Fields | Campo | Tipo | Descrição | |---------------|--------|----------------------------------------------------------------| | `data` | array | Lista de objetos de **[Quota Offering](#quota-offering)**| | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última | ### Observação TIPO * significa que o campo pode ser nulo, como no exemplo abaixo: | Tipo | |----------| | string * | ### Quota Offering | Campo | Tipo | Descrição | |-----------------------------------|----------|-----------------------------------------------------------------------------------------| | `quota_offering_key` | string | Chave única de identificação da oferta | | `status` | string | Ativa / Fechada | | `original_quota_offering_value` | float | Valor original da oferta | | `issued_number_of_quotas` | float | Quantidade de cotas subscritas | | `remaining_quota_offering_value` | float | Valor restante da oferta | | `start_date` | string | Data inicial da oferta | | `issuance_serie` | string | Objeto de **[Issuance Serie](#issuance-serie)** | | `type` | string | Tipo da oferta pública/privada | | `cvm_registration` | JSON *| Dados do registro CVM | | `lead_coordinator` | JSON *| Dados do coordenador líder | | `maturity_date` | string *| Data de vencimento | | `original_number_of_quotas` | string *| Número do cotas emitidas | cvm_registration ```json { "date":"YYYY-MM-DD", "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000" } ``` lead_coordinator ```json { "name":"SAMPLE LEAD COORDINATOR NAME", "address":{ "uf":"SP", "city":"São Paulo", "number":"0000", "street":"Sample street name", "complement":"Sample complement" }, "document_number":"00.000.000/0000-00" } ``` ### Issuance Serie | Campo | Tipo | Descrição | |-------------------------------|----------|---------------------------------------------------| | `name` | string | Nome da série de emissão | | `issuance_serie_key` | string | Chave única de identificação da série de emissão | | `sub_class` | JSON | Objeto de **[Sub Class](#sub-class)** | | `classification` | string | Profissional / Qualificado / Geral | | `market_type` | string | Primário / Secundário | | `serie` | integer | Curva de rendimento / Residual | ### Sub Class | Campo | Tipo | Descrição | |-------------------------------|----------|---------------------------------------------------| | `name` | string | Nome da sub classe | | `sub_class_key` | string | Chave única de identificação da sub classe | | `subordination_level` | int | Nível de subordinação da sub classe | | `fund_class` | JSON | Objeto de **[Fund Class](#fund-class)** | ### Fund Class | Campo | Tipo | Descrição | |-------------------------------|----------|---------------------------------------------------| | `name` | string | Nome da classe de fundo | | `fund_class_key` | string | Chave única de identificação da classe de fundo | | `document_number` | string | CNPJ da classe de fundo | | `short_name` | string | Nome reduzido da classe de fundo | --- # Solicitar Boletim de Subscrição URL: /documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao --- ### Introdução Este recurso tem como objetivo criar uma solicitação de **boletim de subscrição** de um **investidor** a uma **oferta de cotas** de um fundo. A partir desta solicitação, o documento do boletim é gerado de acordo com o tipo de geração configurado na oferta. ### Input / Output: Como ***input*** deve ser enviado o UUID da **oferta de cotas** em que o investidor está subscrevendo, o **valor do boletim**, o **tipo de transação** e, opcionalmente, o método de assinatura e o grupo de signatários. Segue abaixo exemplo. Como ***output*** será entregue o objeto completo do **boletim de subscrição** criado, incluindo a ***subscription_note_key***. A ***subscription_note_key*** é utilizada para identificar o **boletim de subscrição**. ### Request ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/subscription_note MÉTODO POST STATUS 201 ### Path Params | Parâmetro | Descrição | |-------------------|-----------------------| | `INVESTOR_KEY` | UUID do investidor | ### Request body ```json title='Request Body' { "original_subscription_note_value": 50000.00, "quota_offering_key": "UUID", "transaction_type": "ted", "signature_method": "certifiqi", "signer_group_key": "UUID" } ``` ### Subscription Note | Campo | Tipo | Descrição | Obrigatório | |------------------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------|-------------| | `original_subscription_note_value` | number | Valor do boletim de subscrição. Mínimo 0. Não pode exceder o valor restante da oferta | Sim | | `quota_offering_key` | string | UUID (36 caracteres) da oferta de cotas. A oferta deve existir e estar com status `active` | Sim | | `transaction_type` | string | `ted` ou `b3`. Para `b3`, a classe de fundo precisa ter conta B3 cadastrada | Sim | | `signature_method` | string | Enumerador do método de assinatura. Se omitido, o serviço define pelo tipo de pessoa: `natural_person` → `qi_sign`, `legal_person` → `certifiqi` | Não | | `signer_group_key` | string | UUID (36 caracteres) do grupo de signatários. Se omitido, usa o grupo de signatários default do investidor | Não | ### Signature Method | Enumerador | Descrição | |---------------|--------------------------------------------------------------| | `certifiqi` | Assinatura via CertifiQi (Certificado Digital) | | `qi_sign` | Assinatura via QI Sign (Assinatura Eletrônica) | ### Response ```json title='Response Body' { "subscription_note_key": "UUID", "status": "created", "original_number_of_quotas": 500, "original_subscription_note_value": 50000.00, "issued_number_of_quotas": 0, "remaining_subscription_note_value": 50000.00, "start_date": "YYYY-MM-DD", "transaction_type": "ted", "signature_method": "certifiqi", "investor": { "distributor": { "distributor_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE DISTRIBUTOR NAME" }, "investor_key": "UUID", "name": "SAMPLE INVESTOR NAME", "person_type": "natural_person / legal_person", "document_number": "00.000.000/0000-00" }, "quota_offering": { "quota_offering_key": "UUID", "status": "active", "original_quota_offering_value": 10000000.00, "issued_number_of_quotas": 25000.00, "remaining_quota_offering_value": 7500000.00, "start_date": "YYYY-MM-DD", "issuance_serie": { "name": "1", "issuance_serie_key": "UUID", "external_id": "SERIE-001", "sub_class": { "name": "SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "fund_class_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE FUND CLASS NAME", "short_name": "SAMPLE FUND CLASS SHORT NAME", "manager": { "name": "SAMPLE MANAGER NAME", "manager_key": "UUID", "document_number": "00.000.000/0000-00" }, "administrator": { "name": "SAMPLE ADMINISTRATOR NAME", "administrator_key": "UUID", "document_number": "00.000.000/0000-00", "data": {} }, "b3_account": "123456" } }, "classification": "general / qualified / professional", "market_type": "primary / secondary", "serie": 1, "issuance_serie_configuration": {} }, "type": "public / private", "subscription_note_template_key": "UUID", "subscription_note_generation_type": "internal / external", "regulatory_type": "exclusive_fund", "maturity_date": "YYYY-MM-DD", "status_events": [ { "status": "created", "event_datetime": "YYYY-MM-DD HH:MM:SS" }, { "status": "active", "event_datetime": "YYYY-MM-DD HH:MM:SS" } ] }, "financial_application_events": [], "status_events": [ { "status": "created", "event_datetime": "YYYY-MM-DD HH:MM:SS", "selected_agent": "distributor" } ] } ``` A descrição detalhada dos objetos **[Quota Offering](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao#quota-offering)**, **[Investor](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao#investor)** e **[Financial Application Event](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao#financial-application-event)** pode ser consultada na página **[Informações sobre Boletim de Subscrição](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao)**. --- # Recuperando Cotas Públicas URL: /documentation/iaas/passivo/fundos/cotas_publicas --- ### Request ENDPOINT /public_dash/mark_to_market/fund_quota/mark_to_markets METHOD GET STATUS 200 ### Query Params | Parâmetro | Tipo | Descrição | |-----------------------------|----------|---------------------------------------------------------------------------------------| | `internal_codes` | list | Lista de códigos internos da série de emissão para filtro exato dos registros. | | `from_reference_date` | string | Data de início do período a ser consultado (YYYY-MM-DD) | | `to_reference_date` | string | Data do fim do período a ser consultado (YYYY-MM-DD) | | `internal_code` | string | Código único da série de emissão a ser consultada | | `fund_class_document_number`| string | CNPJ (com pontuação) do fundo a ser consultado | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | :::warning Atenção O valor de cota se encontra a nível de **série de emissão (issuance_serie)** e portanto o uso do parâmetro **fund_class_document_number** implica no retorno de todas as séries. Recomenda-se o uso desse filtro apenas para o mapeamento de identificadores únicos das séries de emissão (**internal_code** e **issuance_serie_key**). ::: ### Response ```json title='Response Body' { "data": [ { "issuance_serie_key": "1de4125b-48c7-40ca-b97b-0b65fb356468", "internal_code": "INTERNAL-CODE-2", "fund_class_document_number": "12.345.678/0001-95", "fund_class_name": "FUNDO DE INVESTIMENTO DE TESTES", "marks_to_market": [ { "reference_date": "2025-09-05", "before_amortization_unit_price": 1000, "unit_price": 1000 } ] }, { "issuance_serie_key": "71f7ee44-388d-4916-b068-647e82fd67c8", "internal_code": "INTERNAL-CODE-1", "fund_class_document_number": "12.345.678/0001-95", "fund_class_name": "FUNDO DE INVESTIMENTO DE TESTES", "marks_to_market": [ { "reference_date": "2025-09-04", "before_amortization_unit_price": 1000, "unit_price": 1000 } ] } ], "limit": 5, "page": 0, "is_last_page": true } ``` ### Issuance Serie | Campo | Tipo | Descrição | |-----------------------------------|--------|--------------------------------------------------------------| | `issuance_serie_key` | string | Chave que identifica a série de emissão | | `internal_code` | string | Código que identifica a série de emissão internamente | | `fund_class_document_number` | string | CNPJ do fundo de investimento consultado | | `fund_class_name` | string | Nome do fundo de investimento consultado | | `marks_to_market` | array | Lista de objetos de **[Marks To Market](#marks-to-market)** | ### Marks To Market | Campo | Tipo | Descrição | |-----------------------------------|--------|--------------------------------------------------------------| | `reference_date` | string | Data do valor de cota da série de emissão (YYYY-MM-DD) | | `before_amortization_unit_price` | float | O valor da cota da série de emissão antes de uma amortização | | `unit_price` | float | O valor da cota da série de emissão após o fechamento | --- # Introdução URL: /documentation/iaas/passivo/inicio Bem-vindo à documentação de integração para operações relacionadas ao **Passivo**. Nesta seção, apresentamos todas as ferramentas e recursos necessários para interagir com os serviços oferecidos, desde o cadastro de investidores até a execução de operações financeiras. ## Visão Geral A API de Passivo oferece um conjunto de funcionalidades para facilitar a gestão e execução de operações financeiras para fundos de investimento. Com ela, é possível realizar o cadastro de investidores, aplicações financeiras, pedidos de resgate, bloqueio de cotas e outras operações essenciais para o gerenciamento de ativos. Os serviços são disponibilizados por meio de endpoints que permitem a comunicação segura e eficiente entre as aplicações dos clientes e a plataforma. ### Acesso aos Serviços Para obter acesso aos serviços, é necessário realizar as liberações necessárias em nossos ambientes de Homologação (Sandbox) e Produção. Entre em contato com o time de integração pelo e-mail [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para solicitar as credenciais de acesso e receber orientações sobre o processo de ativação. ## Recursos Disponíveis ### Cadastro do Investidor - **Criar investidor / análise do investidor**: Permite o cadastro de um investidor e a análise cadastral inicial. Descrito em: [5.9.2.1 Criar investidor](/documentation/iaas/investidor/cadastro/criar_investidor) - **Buscar informações do investidor**: Consulta informações cadastrais de um investidor. Descrito em: [5.9.2.2 Buscar informações do investidor](/documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor) - **Buscar informações de uma análise cadastral do investidor**: Permite consultar o status da análise cadastral de um investidor. Descrito em: [5.9.2.3 Buscar análise cadastral](/documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor) - **Enviar dados cadastrais**: Envia dados cadastrais complementares para análise. Descrito em: [5.9.2.4 Enviar dados cadastrais](/documentation/iaas/investidor/cadastro/enviar_dados_cadastrais) ### Aplicação Financeira - **Criar Aplicação Financeira**: Permite criar uma aplicação financeira em uma série de emissão. Descrito em: [5.9.5.1 Criar Aplicação Financeira](/documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira) - **Consultar Aplicação Financeira**: Permite consultar aplicações financeiras por chave ou através de busca paginada. Descrito em: [5.9.5.2 Consulta por chave](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave) e [5.9.5.3 Consulta paginada](/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras) ### Pedido de Resgate - **Criar Pedido de Resgate**: Permite criar um pedido de resgate para um investidor. Descrito em: [5.9.6.1 Criar Pedido de Resgate](/documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate) - **Consultar Pedido de Resgate**: Consulta pedidos de resgate por chave ou através de busca paginada. Descrito em: [5.9.6.2 Consulta por chave](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave), [5.9.6.3 Consulta paginada por investidor](/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor) e [5.9.6.4 Consulta paginada por classe de fundo](/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo) ### Bloqueio de Cotas - **Solicitar Bloqueio de Cotas**: Permite solicitar o bloqueio de cotas para garantia. Descrito em: [5.9.8.1 Solicitar Bloqueio de Cotas](/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas) - **Consultar Bloqueios de Cotas**: Consulta bloqueios de cotas por investidor ou de forma paginada. Descrito em: [5.9.8.2 Consultar bloqueios de cotas](/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas) ## Conclusão Essa documentação serve como guia completo para integração e utilização dos serviços de Passivo. Em caso de dúvidas, entre em contato com nossa equipe de suporte pelo e-mail [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). --- # Consulta paginada de negociações em mercado secundário URL: /documentation/iaas/passivo/mercado_secundario/consulta_negociacoes_mercado_secundario Endpoint de consulta paginada que retorna as **negociações de cotas em mercado secundário** de uma classe de fundo. Cada registro representa a transferência de uma quantidade de cotas de um cotista vendedor para um cotista comprador, com o valor de cota praticado na negociação e a tributação retida do vendedor. Cada negociação relaciona três aplicações financeiras: | Papel | Descrição | |---|---| | `sold_financial_application` | Aplicação do **vendedor**, da qual as cotas saíram. É por ela que os filtros de classe de fundo, série, investidor e depositária central são aplicados. | | `new_financial_application` | Aplicação criada para o **comprador**, com `financial_application_type` igual a `secondary_market`. | | `original_financial_application` | Aplicação que **originou a posição** no mercado primário. Em revendas sucessivas, a mesma aplicação original é propagada para todas as negociações da cadeia, permitindo rastrear a entrada original das cotas. | ## Request ENDPOINT /quota/fund_class/{fund_class_key}/secondary_market_trades MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `50`. Máximo: `500`. | | `issuance_serie_key` | string | opcional | Filtra pelas negociações da série de emissão informada. | | `investor_key` | string | opcional | Filtra pelas negociações em que o investidor informado é o **vendedor**. | | `sold_financial_application_key` | string | opcional | Filtra pela aplicação financeira de origem das cotas negociadas. | | `central_depositary` | string | opcional | Filtra pela depositária central da aplicação de origem. Valores: `cetip` (cotas depositadas na B3) ou `unregistered` (cotas não depositadas). | Os registros são retornados em ordem cronológica de criação da negociação. ```python title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/secondary_market_trades?page=0&limit=50&issuance_serie_key=c3d4e5f6-a7b8-9012-cdef-123456789012¢ral_depositary=cetip ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "secondary_market_trade_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "original_financial_application": { "financial_application_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "share_capital": 500000.0, "status": "quoted", "redemption_keys": [ { "redemption_key": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "financial_application_type": "primary_market", "original_number_of_quotas": 500000.0, "current_principal_value": 490000.0, "acquisition_cost": 500000.0, "current_number_of_quotas": 490000.0, "quotation_date": "2026-03-02", "payment_method": "b3", "investor_key": "d4e5f6a7-b8c9-0123-def0-234567890123", "issuance_serie_key": "e5f6a7b8-c9d0-1234-ef01-345678901234", "external_id": "ext-fa-001" }, "sold_financial_application": { "financial_application_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "share_capital": 500000.0, "status": "quoted", "redemption_keys": [ { "redemption_key": "c3d4e5f6-a7b8-9012-cdef-123456789012" } ], "financial_application_type": "primary_market", "original_number_of_quotas": 500000.0, "current_principal_value": 490000.0, "acquisition_cost": 500000.0, "current_number_of_quotas": 490000.0, "quotation_date": "2026-03-02", "payment_method": "b3", "investor_key": "d4e5f6a7-b8c9-0123-def0-234567890123", "issuance_serie_key": "e5f6a7b8-c9d0-1234-ef01-345678901234", "external_id": "ext-fa-001" }, "new_financial_application": { "financial_application_key": "f6a7b8c9-d0e1-2345-f012-456789012345", "share_capital": 10523.45, "status": "quoted", "redemption_keys": [], "financial_application_type": "secondary_market", "original_number_of_quotas": 10000.0, "current_principal_value": 1.05234567, "acquisition_cost": 1.05234567, "current_number_of_quotas": 10000.0, "quotation_date": "2026-03-02", "payment_method": "b3", "investor_key": "a7b8c9d0-e1f2-3456-0123-567890123456", "issuance_serie_key": "e5f6a7b8-c9d0-1234-ef01-345678901234" }, "trade_quota_value": 1.05234567, "number_of_quotas": 10000.0, "event_datetime": "2026-07-31 00:00:00", "taxable_yield_value": 523.45, "ir_value": 78.52, "iof_value": 0.0 } ], "limit": 50, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de negociações da classe de fundo. | | `page` | integer | Página atual. | | `limit` | integer | Tamanho da página solicitado. | | `is_last_page` | boolean | Indica se não há mais registros após esta página. | #### Objeto em `data` | Campo | Tipo | Descrição | |---|---|---| | `secondary_market_trade_key` | string | Chave única da negociação. | | `original_financial_application` | object | Aplicação financeira que originou a posição no mercado primário. | | `sold_financial_application` | object | Aplicação financeira do vendedor, de onde saíram as cotas. | | `new_financial_application` | object | Aplicação financeira criada para o comprador. | | `trade_quota_value` | number | Valor de cota praticado na negociação. | | `number_of_quotas` | number | Quantidade de cotas negociadas. | | `event_datetime` | string | Data e hora do evento de negociação. | | `taxable_yield_value` | number | Rendimento tributável apurado para o vendedor na negociação. Omitido quando não apurado. | | `ir_value` | number | Imposto de renda retido do vendedor. Omitido quando não apurado. | | `iof_value` | number | IOF retido do vendedor. Omitido quando não apurado. | #### Objeto de aplicação financeira | Campo | Tipo | Descrição | |---|---|---| | `financial_application_key` | string | Chave única da aplicação financeira. | | `share_capital` | number | Valor aportado na aplicação. | | `status` | string | Situação da aplicação, por exemplo `quoted`, `settled`, `redeemed`. | | `redemption_keys` | array | Chaves dos resgates associados à aplicação. Na aplicação do vendedor inclui o resgate gerado pela negociação. | | `financial_application_type` | string | `primary_market` ou `secondary_market`. | | `original_number_of_quotas` | number | Quantidade de cotas na criação da aplicação. | | `current_number_of_quotas` | number | Quantidade de cotas atual. | | `current_principal_value` | number | Valor principal atual. | | `acquisition_cost` | number | Custo de aquisição. | | `quotation_date` | string | Data de cotização. | | `payment_method` | string | Forma de liquidação, por exemplo `b3` ou `regular`. | | `investor_key` | string | Chave do investidor titular da aplicação. | | `issuance_serie_key` | string | Chave da série de emissão da aplicação. | | `external_id` | string | Identificador externo, quando informado no cadastro da aplicação. | Campos opcionais são omitidos da resposta quando não houver valor. Para consultar as aplicações financeiras em detalhe, consulte [Consulta paginada de aplicações financeiras](/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras). ## Possíveis erros STATUS 404 **Classe de fundo não encontrada** ```json { "title": " Fund Class not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "A classe com chave {fund_class_key} não foi encontrado.", "code": "QTA000002" } ``` STATUS 400 **Classe de fundo não pertence ao gestor autenticado** A consulta só retorna negociações de classes de fundo cujo gestor é o titular da integração utilizada na chamada. ```json { "title": "Invalid selected agent", "description": "Invalid selected agent", "translation": "Selected agent invalido", "code": "QIT000004" } ``` --- # Consultar Pedido de Resgate por chave URL: /documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave --- ### Request ENDPOINT /quota/investor/INVESTOR_KEY/redemption_request/REDEMPTION_REQUEST_KEY MÉTODO GET STATUS 200 ### Responses Caso 01: Consulta bem-sucedida ```json { "redemption_request_key": "UUID", "redemption_request_type": "gross_redemption_value" | "number_of_quotas" | "remaining_application_value", "status": "pending_quote" | "processing_quote" | "canceled" | "quoted", "quotation_date": "yyyy-mm-dd", "payment_date":"yyyy-mm-dd", "request_datetime":"yyyy-mm-dd HH:MM:SS:MS", "processed_value": 0.00, "investor_position": { "investor": { "investor_key": "UUID", "document_number": "999.999.999-99" | "99.999.999/9999-99", "name": "", "person_type": "natural_person" | "legal_person", "account_data": { "owner": { "name": "", "document_number": "99.999.999/9999-99" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, "distributor": { "distributor_key": "UUID", "document_number": "99.999.999/9999-99", "name": "", "account_data": { "owner": { "name": "", "document_number": "99.999.999/9999-99" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" }, } }, "total_net_worth": 0.00, "total_number_of_quotas": 0.00000000, "investor_position_key":"UUID", "issuance_serie":{ "name":"1", "cetip_code":"0000000SN1", "start_date":"YYYY-MM-DD", "maturity_date":"YYYY-MM-DD", "original_quota_value":0.00000000000000, "remuneration_type":"yield_curve", "interest_rate_type":"post_fixed", "pre_fixed":{ "calendar_base":"workdays / calendar_360 / calendar_365", "monthly_rate":0.00000000000000 }, "post_fixed":{ "calendar_base":"workdays / calendar_360 / calendar_365", "indexer":"di / ipca", "rate":1, "lag":{ "reference":"daily / monthly", "amount":1 } }, "investment_category":"fidc / multi_market", "condominum_type":"open_ended / close_ended", "tax_classification":"short_term / long_term", "investment_restriction_type":"just_professional", "issuance_serie_key":"UUID", "minimum_share_capital":0.0, "accounting_date":"YYYY-MM-DD", "sub_class":{ "name":"COTA SÊNIOR", "sub_class_key":"UUID", "subordination_level":1, "fund_class":{ "name":"SAMPLE FUND CLASS NAME", "fund_class_key":"UUID", "document_number":"00.000.000/0000-00" } } } }, "status_events": [ { "event_datetime": "yyyy-mm-dd HH:MM:SS:ms", "status": "pending_quote" | "processing_quote" | "canceled" | "quoted", } ], } ``` ### Redemption Request | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------------------------------------|------------| | `redemption_request_key` | string | Chave única de identificação do pedido de resgate | 36 | | `redemption_request_type` | string | Enumerador de **[Redemption Request Type](#redemption_request_type)** | - | | `status` | string | Enumerador de **[Redemption Request Status](#redemption_request_status)** | - | | `quotation_date` | string | Data da cotização | - | | `payment_date` | string | Data do pagamento | - | | `request_datetime` | string | Data da criação do pedido do resgate | - | | `processed_value` | float | Valor processado do resgate | - | | `investor_position` | JSON | Objeto de **[Investor Position](#investor_position)** | - | | `status_events` | array | Lista de objetos de **[Status Event](#status_event)** | - | ### Redemption Request Type {#redemption_request_type} | Enumerador | Descrição | |--------------------------------|-------------------------------------------------| | `gross_redemption_value` | Resgate por valor bruto | | `number_of_quotas` | Resgate por número de cotas | | `remaining_application_value` | Resgate por valor restate | ### Redemption Request Status {#redemption_request_status} | Enumerador | Descrição | |--------------------------|-------------------------------------------------| | `pending_quote` | Pendente pagamento | | `processing_quote` | Pendente cotização | | `quoted` | Cotizado | | `canceled` | Totalmente amortizado | ### Investor Position {#investor_position} | Campo | Tipo | Descrição | |--------------------------|--------|-------------------------------------------------------| | `investor` | JSON | Objeto de **[Investor](#investor)** | | `total_net_worth` | float | Patrimônio Líquido da posição do investidor | | `total_number_of_quotas` | float | Número de cotas da posição do investidor | | `issuance_serie` | JSON | Objeto de **[Issuance Serie](#issuance_serie)** | | `investor_position_key` | JSON | Chave única de identificação da posição do investidor | ### Status Event {#status_event} | Campo | Tipo | Descrição | |------------------|----------|----------------------------------------------------------------| | `status` | string | Status do evento | | `event_datetime` | string | Data e hora do evento | ### Investor | Campo | Tipo | Descrição | Caracteres | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome do investidor | até 255 | | `investor_key` | string | Chave única de identificação do investidor | 36 | | `document_number` | string | CPF/CNPJ do investidor | 14 ou 18 | | `person_type` | string | Pessoa Física / Pessoa Jurídica / Classe de Fundo | até 50 | | `distributor` | JSON | Objeto de **[Distributor](#distributor)** | - | | `account_data` | JSON | Objeto de **[Account Data](#account_data)** | - | ### Distributor | Campo | Tipo | Descrição | Caracteres | |--------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome do distribuidor | até 255 | | `distributor_key` | string | Chave única de identificação do distribuidor | - | | `document_number` | string | CPF/CNPJ do distribuidor | 14 ou 18 | | `account_data` | JSON | Objeto de **[Account Data](#account_data)** | - | ### Account Data {#account_data} | Campo | Tipo | Descrição | |------------------------------|----------|-----------------------------------------------------------------------------| | `account_digit` | string | Dígito da conta bancária | | `account_branch` | string | N° da agência da conta bancária | | `account_number` | string | N° da conta bancária | | `financial_institution_code` | string | Código da instituição financeira | | `financial_institution_ispb` | string | Identificador no Sistema de Pagamento Brasileiro da instituição financeira | ### Issuance Serie {#issuance_serie} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da série de emissão | até 255 | | `issuance_serie_key` | string | Chave única de identificação da série de emissão | 36 | | `cetip_code` | string | Código da série de emissão como ativo na CETIP | 10 | | `start_date` | string | Data de início da série de emissão | 10 | | `maturity_date` | string | Data de vencimento da série de emissão | 10 | | `original_quota_value` | float | Valor de cota original | - | | `remuneration_type` | string | Curva de rendimento / Residual | até 50 | | `investment_category` | string | FIDC / Multimercado | até 50 | | `condominum_type` | string | Aberto / Fechado | até 50 | | `tax_classification` | string | Curto prazo / Longo prazo | até 50 | | `investment_restriction_type` | string | Sem restrição / Qualificado / Profissional | até 50 | | `minimum_share_capital` | float | Valor mínimo para aplicação | - | | `accounting_date` | string | Data contábil da série de emissão | 10 | | `sub_class` | JSON | Objeto de **[Sub Class](#sub_class)** | - | ### Sub Class {#sub_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da sub classe | até 255 | | `sub_class_key` | string | Chave única de identificação da sub classe | 36 | | `subordination_level` | int | Nível de subordinação da sub classe | - | | `fund_class` | JSON | Objeto de **[Fund Class](#fund_class)** | - | ### Fund Class {#fund_class} | Campo | Tipo | Descrição | Caracteres | |-------------------------------|----------|---------------------------------------------------|------------| | `name` | string | Nome da classe de fundo | até 255 | | `fund_class_key` | string | Chave única de identificação da classe de fundo | 36 | | `document_number` | string | CNPJ da classe de fundo | - | --- # Consulta paginada de pedidos de resgate por classe de fundo URL: /documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo Lista **pedidos de resgate** vinculados a uma **classe de fundo** (`fund_class_key`), com paginação. Permite filtrar por **status**, **data de cotização** e **documento do investidor**. ## Request ENDPOINT /quota/fund_class/{fund_class_key}/redemption_requests MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. | | `limit` | integer | opcional | Registros por página. Padrão: `20`. Máximo: `500`. | | `quotation_date` | string | opcional | Filtra pela data de cotização (`YYYY-MM-DD`). | | `investor_document_number` | string | opcional | Filtra pelo documento do investidor (com pontuação). | | `request_from_datetime` | string (date-time) | opcional | Retorna apenas os pedidos com data/hora de solicitação maior ou igual ao valor informado. Formato ISO 8601 com Z (`YYYY-MM-DDTHH:MM:SSZ`). | | `request_to_datetime` | string (date-time) | opcional | Retorna apenas os pedidos com data/hora de solicitação menor ou igual ao valor informado. Formato ISO 8601 com Z (`YYYY-MM-DDTHH:MM:SSZ`). | ```python title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/redemption_requests?page=0&limit=50&investor_document_number=12.345.678/0001-90 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "redemption_request_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "quotation_date": "2024-06-15", "payment_date": "2024-06-18", "redemption_request_type": "number_of_quotas", "request_datetime": "2024-06-10T14:00:00.000000Z", "status": "quoted", "redemption_request_data": { "number_of_quotas": 500.0 }, "processed_value": 5250.5, "ir_value": 0.0, "iof_value": 0.0, "issuance_serie": { "issuance_serie_key": "c3d4e5f6-a7b8-9012-cdef-123456789012", "original_quota_value": 1.0, "current_number_of_quotas": 499500.0, "current_net_worth": 524475.25, "current_principal_value": 499500.0, "performance_fee_current_value": 0.0, "remuneration_type": "yield_curve", "minimum_share_capital": 1000.0, "interest_rate_type": "post_fixed", "name": "Série Única", "serie": 1, "sub_class": { "name": "Cota Sênior", "sub_class_key": "d4e5f6a7-b8c9-0123-def0-234567890123", "subordination_level": 1, "fund_class": { "name": "Fundo Exemplo FIDC", "short_name": "FEX", "document_number": "12.345.678/0001-90", "fund_class_key": "e5f6a7b8-c9d0-1234-ef01-345678901234", "accounting_date": "2024-06-01", "sub_type": "fidc", "tax_classification_id": "long_term", "condominum_type_id": "open_ended", "investment_category_id": "fidc", "prevent_payment": false, "integralization_account_key": null, "manager": { "manager_key": "f6a7b8c9-d0e1-2345-f012-456789012345", "document_number": "98.765.432/0001-10", "manager_name": "Gestora Exemplo S.A." } } }, "status": "active", "internal_code": "INT-FEX-01", "processing_method": "standard", "operation_period_configuration": {}, "current_quota_value": 1.05000055, "post_fixed": { "calendar_base": "calendar_252", "indexer": "cdi", "rate": 1.0, "lag": { "reference": "daily", "amount": 1 } }, "isin_code": "BRSTREXTFID6", "external_id": null, "specific_interest_rate_data": null }, "investor": { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "12.345.678/0001-90", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "12.345.678/0001-90" }, "account_digit": "1", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "341", "financial_institution_ispb": "60746948" } }, "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Maria Cotista Silva", "person_type": "natural_person", "document_number": "123.456.789-00", "external_id": "ext-inv-001", "external_distribution_key": null }, "status_events": [ { "status": "pending_quote", "event_datetime": "2024-06-10T14:00:01.000000Z" }, { "status": "quoted", "event_datetime": "2024-06-15T18:30:00.000000Z" } ] } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Pedidos de resgate. | | `page` | integer | Página atual. | | `limit` | integer | Tamanho da página. | | `is_last_page` | boolean | Última página da consulta. | #### Campos principais de cada pedido em `data` | Campo | Tipo | Descrição | |---|---|---| | `redemption_request_key` | string | Identificador único do pedido (UUID). | | `redemption_request_type` | string | Tipo do pedido — veja [Tipos de pedido](#tipos-de-pedido-de-resgate). | | `status` | string | Status atual — veja [Status do pedido](#status-do-pedido-de-resgate). | | `quotation_date` | string | Data de cotização (`YYYY-MM-DD`). | | `payment_date` | string | Data prevista/realizada de pagamento (`YYYY-MM-DD`). | | `request_datetime` | string | Momento da solicitação (ISO 8601 com sufixo Z quando aplicável). | | `processed_value` | number | Valor processado (quando aplicável). | | `ir_value` / `iof_value` | number | Retenções quando aplicáveis. | | `redemption_request_data` | object | Payload específico do tipo de resgate (valores solicitados, cotas, etc.). | | `issuance_serie` | object | Série de emissão vinculada. | | `investor` | object | Dados do investidor e distribuidora. | | `status_events` | array | Histórico de mudanças de status. | ## Tipos de pedido de resgate | Valor | Descrição | |---|---| | `gross_redemption_value` | Resgate por valor bruto. | | `number_of_quotas` | Resgate por quantidade de cotas. | | `remaining_application_value` | Resgate do valor remanescente da aplicação. | | `net_value_redemption` | Resgate por valor líquido. | ## Status do pedido de resgate | Status | Descrição resumida | |---|---| | `created` | Criado. | | `pending_manager_approval` | Aguardando aprovação do gestor. | | `pending_quote` | Aguardando cotização. | | `processing_quotation` | Cotização em processamento. | | `pending_quotation_date_input` | Aguardando informação de data de cotização. | | `quoted` | Cotizado. | | `canceled` | Cancelado. | | `reprocessed` | Reprocessado. | ## Objetos da resposta ### Issuance Serie (`issuance_serie`) | Campo | Tipo | Descrição | |---|---|---| | `issuance_serie_key` | string | Chave única de identificação da série de emissão | | `name` | string | Nome da série de emissão | | `serie` | int | Número da série | | `original_quota_value` | float | Valor da cota original | | `current_quota_value` | float | Valor atual da cota | | `current_number_of_quotas` | float | Quantidade atual de cotas | | `current_net_worth` | float | Patrimônio líquido atual | | `current_principal_value` | float | Valor de principal atual | | `performance_fee_current_value` | float | Valor atual de taxa de performance | | `minimum_share_capital` | float | Valor mínimo para aplicação | | `remuneration_type` | string | Tipo de remuneração (ex.: `yield_curve`) | | `interest_rate_type` | string | Tipo de taxa (`post_fixed` / `pre_fixed`) | | `post_fixed` / `pre_fixed` | object | Dados de remuneração (`calendar_base`, `indexer`, `rate`, `lag`) | | `status` | string | Status da série de emissão (ex.: `active`) | | `internal_code` | string | Código interno da série | | `isin_code` | string | Código ISIN | | `processing_method` | string | Método de processamento | | `operation_period_configuration` | object | Configuração de períodos de operação | | `external_id` | string | Identificador externo | | `sub_class` | object | Objeto **Sub Class** | ### Sub Class (`sub_class`) | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome da subclasse | | `sub_class_key` | string | Chave única de identificação da subclasse | | `subordination_level` | int | Nível de subordinação da subclasse | | `fund_class` | object | Objeto **Fund Class** | ### Fund Class (`fund_class`) | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome da classe de fundo | | `short_name` | string | Nome curto da classe de fundo | | `fund_class_key` | string | Chave única de identificação da classe de fundo | | `document_number` | string | CNPJ da classe de fundo | | `accounting_date` | string | Data contábil da classe de fundo | | `sub_type` | string | Subtipo (ex.: `fidc`) | | `tax_classification_id` | string | Classificação tributária (ex.: `long_term`) | | `condominum_type_id` | string | Tipo de condomínio (ex.: `open_ended`) | | `investment_category_id` | string | Categoria de investimento (ex.: `fidc`) | | `prevent_payment` | boolean | Indica se os pagamentos estão bloqueados | | `integralization_account_key` | string | Chave da conta de integralização | | `manager` | object | Objeto **Manager** | ### Manager (`manager`) | Campo | Tipo | Descrição | |---|---|---| | `manager_key` | string | Chave única de identificação do gestor | | `document_number` | string | CNPJ do gestor | | `manager_name` | string | Nome do gestor | ### Investor (`investor`) | Campo | Tipo | Descrição | |---|---|---| | `investor_key` | string | Chave única de identificação do investidor | | `name` | string | Nome do investidor | | `document_number` | string | CPF/CNPJ do investidor | | `person_type` | string | Tipo de pessoa (`natural_person` / `legal_person`) | | `external_id` | string | Identificador externo do investidor | | `external_distribution_key` | string | Chave de distribuição externa | | `distributor` | object | Objeto **Distributor** | ### Distributor (`distributor`) | Campo | Tipo | Descrição | |---|---|---| | `distributor_key` | string | Chave única de identificação do distribuidor | | `name` | string | Nome do distribuidor | | `document_number` | string | CNPJ do distribuidor | | `account_data` | object | Objeto **Account Data** | ### Account Data (`account_data`) | Campo | Tipo | Descrição | |---|---|---| | `owner` | object | Titular da conta (`name`, `document_number`) | | `account_digit` | string | Dígito da conta bancária | | `account_branch` | string | N° da agência da conta bancária | | `account_number` | string | N° da conta bancária | | `financial_institution_code` | string | Código da instituição financeira | | `financial_institution_ispb` | string | Identificador no Sistema de Pagamento Brasileiro (ISPB) da instituição financeira | ## Possíveis erros STATUS 404 **Classe de fundo não encontrada** ```json { "title": " Fund Class not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "A classe com chave {fund_class_key} não foi encontrado.", "code": "QTA000002" } ``` --- # Consulta paginada de pedidos de resgate por investidor URL: /documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor Retorna os **pedidos de resgate** de um investidor identificado por `investor_key`, com paginação e filtros opcionais por **status** e **data de cotização**. A lista é ordenada por fundo, subclasse, série e data de cotização (mais recente primeiro). ## Request ENDPOINT /quota/investor/{investor_key}/redemption_requests MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `page` | integer | opcional | Número da página (começa em `0`) | | `limit` | integer | opcional | Registros por página. Padrão: `20`. Máximo: `500`. | | `status` | array de strings | opcional | Um ou mais valores de status do pedido (veja [Status do pedido de resgate](#status-do-pedido-de-resgate)). Repita o parâmetro ou use o formato aceito pela plataforma para listas. | | `quotation_date` | string | opcional | Filtra pela data de cotização no formato `YYYY-MM-DD`. | | `fund_class_document_number` | string | opcional | Filtra pelo documento (CNPJ) da classe de fundo. | | `request_from_datetime` | string (date-time) | opcional | Retorna apenas os pedidos com data/hora de solicitação maior ou igual ao valor informado. Formato ISO 8601 com Z (`YYYY-MM-DDTHH:MM:SSZ`). | | `request_to_datetime` | string (date-time) | opcional | Retorna apenas os pedidos com data/hora de solicitação menor ou igual ao valor informado. Formato ISO 8601 com Z (`YYYY-MM-DDTHH:MM:SSZ`). | ```python title="Exemplo de chamada" GET /quota/investor/{investor_key}/redemption_requests?page=0&limit=20&status=quoted"ation_date=2024-06-15 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "redemption_request_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "quotation_date": "2024-06-15", "payment_date": "2024-06-18", "redemption_request_type": "number_of_quotas", "request_datetime": "2024-06-10T14:00:00.000000Z", "status": "quoted", "redemption_request_data": { "number_of_quotas": 500.0 }, "processed_value": 5250.5, "ir_value": 0.0, "iof_value": 0.0, "issuance_serie": { "issuance_serie_key": "c3d4e5f6-a7b8-9012-cdef-123456789012", "original_quota_value": 1.0, "current_number_of_quotas": 499500.0, "current_net_worth": 524475.25, "current_principal_value": 499500.0, "performance_fee_current_value": 0.0, "remuneration_type": "yield_curve", "minimum_share_capital": 1000.0, "interest_rate_type": "post_fixed", "name": "Série Única", "serie": 1, "sub_class": { "name": "Cota Sênior", "sub_class_key": "d4e5f6a7-b8c9-0123-def0-234567890123", "subordination_level": 1, "fund_class": { "name": "Fundo Exemplo FIDC", "short_name": "FEX", "document_number": "12.345.678/0001-90", "fund_class_key": "e5f6a7b8-c9d0-1234-ef01-345678901234", "accounting_date": "2024-06-01", "sub_type": "fidc", "tax_classification_id": "long_term", "condominum_type_id": "open_ended", "investment_category_id": "fidc", "prevent_payment": false, "integralization_account_key": null, "manager": { "manager_key": "f6a7b8c9-d0e1-2345-f012-456789012345", "document_number": "98.765.432/0001-10", "manager_name": "Gestora Exemplo S.A." } } }, "status": "active", "internal_code": "INT-FEX-01", "processing_method": "standard", "operation_period_configuration": {}, "current_quota_value": 1.05000055, "post_fixed": { "calendar_base": "calendar_252", "indexer": "cdi", "rate": 1.0, "lag": { "reference": "daily", "amount": 1 } }, "isin_code": "BRSTREXTFID6", "external_id": null, "specific_interest_rate_data": null }, "investor": { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "12.345.678/0001-90", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "12.345.678/0001-90" }, "account_digit": "1", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "341", "financial_institution_ispb": "60746948" } }, "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Maria Cotista Silva", "person_type": "natural_person", "document_number": "123.456.789-00", "external_id": "ext-inv-001", "external_distribution_key": null }, "status_events": [ { "status": "pending_quote", "event_datetime": "2024-06-10T14:00:01.000000Z" }, { "status": "quoted", "event_datetime": "2024-06-15T18:30:00.000000Z" } ] } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Pedidos de resgate. | | `page` | integer | Página atual. | | `limit` | integer | Tamanho da página. | | `is_last_page` | boolean | Última página da consulta. | #### Campos principais de cada pedido em `data` | Campo | Tipo | Descrição | |---|---|---| | `redemption_request_key` | string | Identificador único do pedido (UUID). | | `redemption_request_type` | string | Tipo do pedido — veja [Tipos de pedido](#tipos-de-pedido-de-resgate). | | `status` | string | Status atual — veja [Status do pedido](#status-do-pedido-de-resgate). | | `quotation_date` | string | Data de cotização (`YYYY-MM-DD`). | | `payment_date` | string | Data prevista/realizada de pagamento (`YYYY-MM-DD`). | | `request_datetime` | string | Momento da solicitação (ISO 8601 com sufixo Z quando aplicável). | | `processed_value` | number | Valor processado (quando aplicável). | | `ir_value` / `iof_value` | number | Retenções quando aplicáveis. | | `redemption_request_data` | object | Payload específico do tipo de resgate (valores solicitados, cotas, etc.). | | `issuance_serie` | object | Série de emissão vinculada. | | `investor` | object | Dados do investidor e distribuidora. | | `status_events` | array | Histórico de mudanças de status. | | `cancellation_data` | object | Presente quando o pedido foi cancelado (omitido quando `null`). | ## Tipos de pedido de resgate | Valor | Descrição | |---|---| | `gross_redemption_value` | Resgate por valor bruto. | | `number_of_quotas` | Resgate por quantidade de cotas. | | `remaining_application_value` | Resgate do valor remanescente da aplicação. | | `net_value_redemption` | Resgate por valor líquido. | ## Status do pedido de resgate | Status | Descrição resumida | |---|---| | `created` | Criado. | | `pending_manager_approval` | Aguardando aprovação do gestor. | | `pending_quote` | Aguardando cotização. | | `processing_quotation` | Cotização em processamento. | | `pending_quotation_date_input` | Aguardando informação de data de cotização. | | `quoted` | Cotizado. | | `canceled` | Cancelado. | | `reprocessed` | Reprocessado. | ## Objetos da resposta ### Issuance Serie (`issuance_serie`) | Campo | Tipo | Descrição | |---|---|---| | `issuance_serie_key` | string | Chave única de identificação da série de emissão | | `name` | string | Nome da série de emissão | | `serie` | int | Número da série | | `original_quota_value` | float | Valor da cota original | | `current_quota_value` | float | Valor atual da cota | | `current_number_of_quotas` | float | Quantidade atual de cotas | | `current_net_worth` | float | Patrimônio líquido atual | | `current_principal_value` | float | Valor de principal atual | | `performance_fee_current_value` | float | Valor atual de taxa de performance | | `minimum_share_capital` | float | Valor mínimo para aplicação | | `remuneration_type` | string | Tipo de remuneração (ex.: `yield_curve`) | | `interest_rate_type` | string | Tipo de taxa (`post_fixed` / `pre_fixed`) | | `post_fixed` / `pre_fixed` | object | Dados de remuneração (`calendar_base`, `indexer`, `rate`, `lag`) | | `status` | string | Status da série de emissão (ex.: `active`) | | `internal_code` | string | Código interno da série | | `isin_code` | string | Código ISIN | | `processing_method` | string | Método de processamento | | `operation_period_configuration` | object | Configuração de períodos de operação | | `external_id` | string | Identificador externo | | `sub_class` | object | Objeto **Sub Class** | ### Sub Class (`sub_class`) | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome da subclasse | | `sub_class_key` | string | Chave única de identificação da subclasse | | `subordination_level` | int | Nível de subordinação da subclasse | | `fund_class` | object | Objeto **Fund Class** | ### Fund Class (`fund_class`) | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome da classe de fundo | | `short_name` | string | Nome curto da classe de fundo | | `fund_class_key` | string | Chave única de identificação da classe de fundo | | `document_number` | string | CNPJ da classe de fundo | | `accounting_date` | string | Data contábil da classe de fundo | | `sub_type` | string | Subtipo (ex.: `fidc`) | | `tax_classification_id` | string | Classificação tributária (ex.: `long_term`) | | `condominum_type_id` | string | Tipo de condomínio (ex.: `open_ended`) | | `investment_category_id` | string | Categoria de investimento (ex.: `fidc`) | | `prevent_payment` | boolean | Indica se os pagamentos estão bloqueados | | `integralization_account_key` | string | Chave da conta de integralização | | `manager` | object | Objeto **Manager** | ### Manager (`manager`) | Campo | Tipo | Descrição | |---|---|---| | `manager_key` | string | Chave única de identificação do gestor | | `document_number` | string | CNPJ do gestor | | `manager_name` | string | Nome do gestor | ### Investor (`investor`) | Campo | Tipo | Descrição | |---|---|---| | `investor_key` | string | Chave única de identificação do investidor | | `name` | string | Nome do investidor | | `document_number` | string | CPF/CNPJ do investidor | | `person_type` | string | Tipo de pessoa (`natural_person` / `legal_person`) | | `external_id` | string | Identificador externo do investidor | | `external_distribution_key` | string | Chave de distribuição externa | | `distributor` | object | Objeto **Distributor** | ### Distributor (`distributor`) | Campo | Tipo | Descrição | |---|---|---| | `distributor_key` | string | Chave única de identificação do distribuidor | | `name` | string | Nome do distribuidor | | `document_number` | string | CNPJ do distribuidor | | `account_data` | object | Objeto **Account Data** | ### Account Data (`account_data`) | Campo | Tipo | Descrição | |---|---|---| | `owner` | object | Titular da conta (`name`, `document_number`) | | `account_digit` | string | Dígito da conta bancária | | `account_branch` | string | N° da agência da conta bancária | | `account_number` | string | N° da conta bancária | | `financial_institution_code` | string | Código da instituição financeira | | `financial_institution_ispb` | string | Identificador no Sistema de Pagamento Brasileiro (ISPB) da instituição financeira | ## Possíveis erros STATUS 404 **Status informado inválido** Algum valor em `status` não corresponde a um enumerador válido de `RedemptionRequestStatus`. ```json { "title": "Not found enumerator", "description": "invalid_status is not a valid type of RedemptionRequestStatus", "translation": "invalid_status não é um tipo válido de RedemptionRequestStatus", "code": "QTA000004" } ``` --- # Criar Pedido de Resgate URL: /documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate --- ### Request ENDPOINT /quota/investor/INVESTOR_KEY/redemption_request MÉTODO POST STATUS 201 ```json title='Request Body' { "issuance_serie_key": "UUID", "redemption_request_type": "gross_redemption_value" | "number_of_quotas" | "remaining_application_value" | "net_value_redemption", "payment_method": "regular / b3", "gross_redemption_value":0.00, "net_value": 0.00, "remaining_application_value":0.00, "number_of_quotas":0.00000000, "disbursement_account_key": "UUID", "quotation_date": "yyyy-mm-dd", "reference_date": "yyyy-mm-dd" } ``` :::::warning - O campo redemption_request_type define se os campos gross_redemption_value , remaining_application_value e number_of_quotas devem ser passados ou não. - Caso gross_redemption_value , o campo gross_redemption_value é obrigatório. - Caso remaining_application_value , o campo remaining_application_value é obrigatório. - Caso number_of_quotas , o campo number_of_quotas é obrigatório. - Caso net_value_redenotuib , o campo net_value é obrigatório. - O campo disbursement_account_key deve ser utilizada para a liquidação do resgate em uma conta específica do investidor. Caso não seja informada uma conta específica, a conta principal do investidor será utilizada ::::: ### Body params | Campo | Tipo | Descrição | Obrigatório |-----------------------------------|----------|-----------------------------------------------------------------------------------------|-----| | `issuance_serie_key` | string | Chave única de identificação da Série de emissão | Sim | `redemption_request_type` | string | Enumerador de **[Tipos de Pedido de Resgate](#tipos_de_pedido_de_resgate)** | Sim | `gross_redemption_value` | float | Valor bruto do resgate, sem descontar IR e IOF | Não | `net_value` | float | Valor Líquido do resgate, já disconsiderando IR e IOF | Não | `remaining_application_value` | float | Valor restante da aplicação | Não | `number_of_quotas` | float | Valor da aplicação financeira | Não | `disbursement_account_key` | string | Chave única de identificação da conta bancária do investidor | Não | | `quotation_date` | string | Data de cotização do resgate | Não | | `payment_method` | string | Método de pagamento do resgate. Valores esperados:
• regular **(default)**
• b3: Via B3 | Não | | `reference_date` | string | Data de referência do resgate, no formato yyyy-mm-dd | Não | ### Tipos de Pedido de Resgate {#tipos_de_pedido_de_resgate} | Enumerador | Descrição | |---------------------------------|-------------------------------------------------| | `gross_redemption_value` | Resgate por valor bruto | | `number_of_quotas` | Resgate por número de cotas | | `remaining_application_value` | Resgate por posição remanescente |] | `net_value_redemption` | Resgate por valor líquido | ### Response ```json title='Response Body' { "redemption_request_key": "UUID" } ``` --- # Enviar Termo de Adesão Assinado URL: /documentation/iaas/passivo/termo_de_adesao/enviar_termo_de_adesao_assinado --- ### Introdução Este recurso tem como objetivo nos enviar a comprovação de assinatura do **termo de adesão** de um **investidor** a uma **série de emissão** de um fundo. :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de **Distribuidor**. ::: ### Input / Output: Como ***input*** deve ser enviado o UUID da **série de emissão** do fundo que o investidor aderiu e **tipo de assinatura** e dependendo da assinatura o conteúdo necessário para validação. Segue abaixo exemplo. Como ***output*** será entregue uma ***investor_adhesion_key***. A ***investor_adhesion_key*** é utilizada para identificar a **adesão do investidor**. ### Request ENDPOINT /investor_adhesion/investor/INVESTOR_KEY/signed_investor_adhesion MÉTODO POST STATUS 201 ### Request body ```json title='Request Body' { "issuance_serie_key": "UUID", "signature_method": "opt_in", "opt_in_hash" : "OPT_IN_HASH" } ``` :::warning Atenção Durante o processo de integração será exigido um meio de autenticação da hash enviada. ::: ### Response ```json title='Response Body' { "investor_adhesion_key": "UUID" } ``` --- # Solicitar Termo de Adesão URL: /documentation/iaas/passivo/termo_de_adesao/solicitar_termo_de_adesao --- ### Introdução Este recurso tem como objetivo criar uma solicitação de **termo de adesão** de um **investidor** a uma **série de emissão** de um fundo. A partir desta solicitação, são gerados os documentos necessários para a formalização da adesão, de acordo com as configurações da série de emissão. :::warning Atenção Este recurso está disponível apenas para integrações que exercem o papel de **Gestor** do fundo. ::: ### Input / Output: Como ***input*** deve ser enviado o UUID da **série de emissão** em que o investidor está aderindo e, opcionalmente, o **método de assinatura** que será utilizado para os documentos gerados. Como ***output*** será entregue uma ***investor_adhesion_key***. A ***investor_adhesion_key*** é utilizada para identificar a **adesão do investidor**. ### Request ENDPOINT /investor_adhesion/investor/INVESTOR_KEY/investor_adhesion MÉTODO POST STATUS 201 ### Request body ```json title='Request Body' { "issuance_serie_key": "UUID", "signature_method": "qi_sign" } ``` ### Investor Adhesion | Campo | Tipo | Descrição | Caracteres | Obrigatório | |----------------------|--------|------------------------------------------------------------------------|------------|-------------| | `issuance_serie_key` | string | Chave da série de emissão a qual o investidor está aderindo | 36 | Sim | | `signature_method` | string | Enumerador do método de assinatura a ser utilizado nos documentos | até 255 | Não | ### Signature Method | Enumerador | Descrição | |---------------|--------------------------------------------------------------| | `certifiqi` | Assinatura via CertifiQi (Certificado Digital) | | `qi_sign` | Assinatura via QI Sign (Assinatura Eletrônica) | ### Response ```json title='Response Body' { "investor_adhesion_key": "UUID" } ``` :::info Fluxo da adesão Após solicitar uma nova adesão, podemos seguir dois caminhos: - **Investidor NÃO tinha uma adesão ativa**: a adesão é criada no status `pending_documents` e permanece assim até que todos os documentos exigidos sejam gerados e assinados. - **Investidor já tinha uma adesão ativa**: a requisição é rejeitada. ::: --- # Razão Contábil URL: /documentation/iaas/relatorios_dtvm/accounting_ledger ## Visão Geral O relatório `accounting_ledger` apresenta o razão contábil do fundo em um intervalo de datas. Para cada conta do plano de contas com movimentações no período, o relatório exibe uma linha de saldo inicial, todos os lançamentos individuais com data, contrapartida, valor e descrição, e uma linha de saldo final com totais de débito e crédito. Auditores, administradores e analistas utilizam este relatório para rastrear a origem de cada lançamento contábil e verificar a evolução dos saldos conta a conta. ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. | | `start_date` | sim | Data de início do período, no formato `AAAA-MM-DD`. | | `end_date` | sim | Data de fim do período, no formato `AAAA-MM-DD`. Precisa ser **posterior** à data de início. | :::warning É preciso haver contabilidade fechada nas duas datas O relatório só é gerado se existir fechamento contábil na data de início **e** na data de fim. Sem isso a solicitação é recusada com a mensagem "Não existe contabil na data ...". ::: :::warning As duas datas têm de estar no mesmo exercício contábil Além de existir fechamento nas duas datas, elas precisam pertencer ao **mesmo exercício** (mesmo *ledger*). Um período que atravessa o encerramento de exercício faz a geração falhar. ::: ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | XLSX | | Nomenclatura | `{nome_resumido_fundo}_accounting_ledger_{YYYY-MM-DD}.xlsx` | ## Conteúdo da Planilha ### Cabeçalho do Fundo Apresentado nas primeiras linhas da planilha: | Campo | Descrição | |-------|-----------| | Fundo | Nome completo da classe de fundo. | | CNPJ | CNPJ da classe de fundo. | :::warning O sinal do saldo aqui é diferente do Relatório de Balanço Neste relatório o saldo é o valor cru do fechamento (crédito positivo, débito negativo). No [Relatório de Balanço](/documentation/iaas/relatorios_dtvm/balance_report) o mesmo saldo é normalizado pela natureza da conta. A mesma conta pode, portanto, aparecer como `-45000.00` aqui e `45000.00` lá — são a mesma posição, em convenções de sinal diferentes. ::: ### Lançamentos por Conta Para cada conta com movimentações no período, o relatório exibe: 1. **Linha de saldo inicial** (em negrito) — saldo da conta na Data de Início. 2. **Linhas de lançamento** — um registro por movimento contábil. 3. **Linha de saldo final** (em negrito) — saldo da conta na Data Final com totais de débito e crédito. | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `Data` | data | `2026-07-15` | Data contábil do lançamento. Nas linhas de saldo inicial e final, exibe a Data de Início e a Data Final respectivamente. | | `Conta` | string | `"1.2.1.10.00.001.001-9"` | Número da conta no plano de contas, com dígito verificador. | | `Nome da Conta` | string | `"Direitos Creditórios sem Coobrigação"` | Nome descritivo da conta contábil. | | `Tipo do Lançamento` | string (enum) | `"A"` | Tipo do lançamento: `"A"` para automático; `"M"` para manual; `"I"` para linha de saldo inicial; `"F"` para linha de saldo final. | | `ContraPartida` | string | `"7.9.1.20.00.001.001-1"` | Número da conta de contrapartida do lançamento. Vazio nas linhas de saldo inicial e final. | | `Débito` | número | `1500.00` | Valor do lançamento a débito (em reais). Zero quando o lançamento é a crédito. | | `Crédito` | número | `0.00` | Valor do lançamento a crédito (em reais). Zero quando o lançamento é a débito. | | `Saldo` | número | `-196500.00` | Saldo acumulado da conta após o lançamento (em reais). Crédito soma e débito subtrai, **sem normalização pela natureza da conta** — por isso uma conta de ativo com saldo devedor aparece negativa aqui. | | `Descrição` | string | `"ACRUO DE ATIVOS - CCBs"` | Descrição do evento contábil associado ao lançamento. | --- # Composição de Carteira de Ativos URL: /documentation/iaas/relatorios_dtvm/assets_wallet_composition ## Visão Geral O relatório `assets_wallet_composition` apresenta a posição completa de todos os ativos que compõem o estoque do fundo em uma determinada data de referência. Ele é gerado uma vez ao dia e consolida três categorias de ativos: - **operações de crédito** (ex: CCB) — uma linha por **parcela** da operação; - **direitos creditórios descontados** (ex: duplicatas, CT-e, contratos descontados) — uma linha por título; - **títulos privados** (ex: debêntures, notas comerciais) — uma linha por parcela do título. Gestores e analistas utilizam este relatório para acompanhar o estoque, avaliar provisões para devedores duvidosos e monitorar a evolução da carteira. :::info Uma linha por parcela Para operações de crédito parceladas, a mesma operação aparece em várias linhas — uma por parcela — repetindo os dados cadastrais (`external_id`, `contract_number`, `purchase_value`) e variando `installment_number`, `face_value`, `maturity_date` e `installment_purchase_value`. ::: :::tip Também em PDF Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](./manual_relatorios_qi_tech.pdf) — revisão 2, julho de 2026. O manual cobre quatro relatórios: este, a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), a [Aquisição Consolidada](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) e a [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets). Nesta seção do manual os nomes das colunas aparecem em maiúsculas. No arquivo entregue eles vêm sempre em **minúsculas**, conforme a tabela de colunas abaixo. ::: ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. | | `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. | :::info Fundos de cota de abertura Para os fundos que operam com relatório de cota de abertura, a posição entregue é a do **dia anterior** à data de referência informada. ::: ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | CSV | | Encoding | UTF-8 | | Delimitador | `,` (vírgula) | | Cabeçalho | Sim (primeira linha) | | Nomenclatura | `{nome_resumido_fundo}_assets_wallet_composition_{AAAA-MM-DD}.csv` | Os nomes das colunas são gerados em **minúsculas**. Datas são escritas no formato `AAAA-MM-DD` e valores decimais usam ponto como separador, com até 8 casas decimais. ## Colunas | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `fund_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. | | `fund_document` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. | | `report_date` | data | `2026-07-30` | Data em que o relatório foi gerado. Nas linhas de títulos privados, esta coluna traz a data de referência da carteira. | | `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora da operação. Para títulos privados, o valor é `-`. | | `originator_document` | string | `"11.222.333/0001-44"` | CNPJ do originador. Para títulos privados, o valor é `-`. | | `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente da operação. Para títulos privados, o valor é `-`. | | `assignor_document` | string | `"22.333.444/0001-55"` | CNPJ do cedente. Para títulos privados, o valor é `-`. | | `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor. Para direitos creditórios descontados, é o sacado; para títulos privados, é o emissor. | | `borrower_document` | string | `"123.456.789-00"` | CPF ou CNPJ do devedor / sacado / emissor. | | `external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo, conforme informado na criação. | | `contract_number` | string | `"0900112233/EXA"` | Número do contrato ou número do pedido (`order_number`) associado à operação. | | `asset_type` | string (enum) | `"ccb"` | Tipo do ativo. Exemplos: `ccb`, `duplicata_mercantil`, `duplicata_servicos`, `cte`, `discounted_contract`, `debenture`. | | `face_value` | número | `1678.90` | Valor de face da parcela (ou do título) na data de referência, em reais. | | `present_value` | número | `1663.48` | Valor presente da parcela (ou do título) na data de referência, em reais. | | `purchase_value` | texto numérico | `4690.80` | Valor pelo qual o **ativo** foi adquirido pelo fundo, em reais. Repetido em todas as parcelas da mesma operação. | | `bad_provision_value` | número | `0.0` | Valor da provisão para devedores duvidosos (PDD) constituída sobre o ativo, em reais. | | `bad_provision_range` | string | `"AA"` | Faixa de classificação de risco da PDD — as usuais são `AA`, `A`, `B`, `C`, `D`, `E`, `F`, `G` e `H`, e ativos baixados podem trazer `WO`. Quando não há classificação, o relatório traz `AA`. | | `fund_date` | data | `2026-07-29` | Data de referência da carteira. | | `maturity_date` | data | `2026-08-28` | Data de vencimento da parcela (ou do título). | | `business_maturity_date` | data | `2026-08-28` | Data de vencimento ajustada para dia útil. | | `issue_date` | texto de data | `2026-07-28` | Data de emissão do contrato. Para direitos creditórios descontados, corresponde à data de aquisição. | | `purchase_date` | texto de data | `2026-07-29` | Data de aquisição do ativo pelo fundo. | | `total_duration` | inteiro | `30` | Prazo total em dias corridos, da aquisição até o vencimento. | | `present_duration` | inteiro | `30` | Prazo remanescente em dias corridos, da data de referência até o vencimento. Fica negativo quando o ativo está vencido. | | `asset_maturity_status` | string (enum) | `"on_time"` | Situação do vencimento: `OVERDUE` quando vencido, `on_time` quando dentro do prazo. | | `assignment_rate_of_return` | número | `0.0312` | Taxa interna de retorno (TIR) da cessão. Vazio para títulos privados. | | `purchase_rate_of_return` | texto numérico | `0.031874210` | TIR corrente da operação no momento da aquisição. Para títulos privados, o valor é `-`. | | `has_assignor_coobligation` | string | `"False"` | Indica coobrigação do cedente: `True` ou `False`. Para títulos privados, o valor é `-`. | | `installment_number` | inteiro | `1` | Número da parcela. Para direitos creditórios descontados, é sempre `1`. | | `bad_debt_type` | string | `"default"` | Tipo de classificação da PDD aplicada ao ativo. | | `nominal_rate` | número | `0.0231` | Taxa nominal mensal pré-fixada da operação. Vazio para direitos creditórios descontados e títulos privados. | | `operation_type` | string | `"ccb"` | Tipo da operação registrado no cadastro do ativo. Vazio para títulos privados. | | `installment_purchase_value` | texto numérico | `1598.74210000` | Valor pago pelo fundo pela **parcela** específica, em reais. Vazio para direitos creditórios descontados e títulos privados. | :::note Coluna adicional Quando a entrega é configurada com a opção `benefit_number`, o relatório traz uma coluna extra `benefit_type` ao final, com o tipo de benefício associado à garantia da operação. ::: --- # Composição de Ativos da Cessão URL: /documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition ## Visão Geral O relatório `assignment_assets_wallet_composition` detalha os ativos de **uma cessão específica**, no mesmo formato do relatório de [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition). É o relatório usado para conferir o que entrou na carteira imediatamente após uma aquisição, antes de o ativo passar a compor as posições diárias. - **operações de crédito** — uma linha por **parcela**; - **direitos creditórios descontados** — uma linha por **ativo**. :::tip Também em PDF Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](./manual_relatorios_qi_tech.pdf) — revisão 2, julho de 2026. O manual cobre quatro relatórios: este, a [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition), a [Aquisição Consolidada](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) e a [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets). Nesta seção do manual os nomes das colunas aparecem em maiúsculas. No arquivo entregue eles vêm sempre em **minúsculas**, conforme a tabela de colunas abaixo. ::: ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `external_id` | sempre | O "seu número" da cessão a consultar. | | `asset_type` | sempre | Define qual consulta é executada. Operações de crédito: `ccb`, `structured_ccb`, `cce`, `structured_cce`, `structured_cci`, `structured_nce`. Direitos creditórios descontados: `duplicata_mercantil`, `duplicata_servicos`, `discounted_contract`, `legal_fees`, `cte`. Um tipo fora dessas listas faz o relatório falhar. | | `fund_class_key` | só para direitos creditórios descontados | Classe de fundo sobre a qual o relatório é gerado. Para operações de crédito o filtro é feito apenas pela cessão, e o fundo informado é ignorado. | ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | CSV | | Encoding | UTF-8 | | Delimitador | `,` (vírgula) | | Cabeçalho | Sim (primeira linha) | | Nomenclatura | `{nome_resumido_fundo}_assignment_assets_wallet_composition_{AAAA-MM-DD}_{external_id}.csv` | :::note O nome do arquivo termina com o identificador da cessão Diferente dos relatórios diários, este acrescenta o `external_id` da cessão ao final do nome. Como o `external_id` é obrigatório, o sufixo está sempre presente. ::: ## O que o relatório traz - Todos os ativos da cessão informada, **exceto** os descartados (`discarded`) e os reprovados (`denied`). - As últimas colunas variam conforme o tipo de ativo — veja `asset_external_id` / `invoice_number` e `monthly_rate` na tabela abaixo. - Campos sem valor vêm vazios no arquivo. ## Colunas | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `fund_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. | | `fund_document` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. | | `fund_date` | data | `2026-07-29` | Data contábil corrente do fundo. | | `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome do originador. | | `originator_document` | string | `"11.222.333/0001-44"` | CNPJ do originador. | | `name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do **cedente**. Atenção ao cabeçalho genérico: apesar de `name`, o conteúdo é o cedente, não o fundo nem o devedor. | | `document_number` | string | `"22.333.444/0001-55"` | CNPJ do **cedente**. Mesma observação da coluna anterior. | | `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor ou do sacado. | | `borrower_document` | string | `"123.456.789-00"` | CPF ou CNPJ do devedor/sacado. | | `external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201-1"` | Identificador externo da **parcela** (operação de crédito) ou do **ativo** (direito creditório descontado). | | `contract_number` | string | `"0900112233/EXA"` | Número do contrato ou do pedido. | | `asset_type` | string (enum) | `"ccb"` | Tipo do ativo. | | `face_value` | número | `1678.90` | Valor de face/nominal (em reais). | | `present_value` | número | `1598.74210000` | Valor presente. Nesta visão, igual ao valor de compra. | | `purchase_value` | número | `1598.74210000` | Valor de aquisição (em reais). | | `bad_provision_value` | número | `0` | Provisão para devedores duvidosos. **Fixo em `0`** nesta visão. | | `bad_provision_range` | string | `"AA"` | Faixa de PDD. **Fixo em `AA`** (melhor faixa) nesta visão. | | `report_date` | data | `2026-07-30` | Data de geração do relatório. | | `maturity_date` | data | `2026-08-28` | Vencimento da parcela ou do ativo. | | `business_maturity_date` | data | `2026-08-28` | Vencimento ajustado. Nesta visão, repete o `maturity_date`. | | `issue_date` | data | `2026-07-29` | Data de emissão. Nesta visão, traz a **data da cessão**. | | `purchase_date` | data | `2026-07-29` | Data de aquisição. Nesta visão, traz a **data da cessão**. | | `total_duration` | número | `30` | Prazo total, em dias. | | `present_duration` | número | `30` | Prazo atual, em dias. | | `asset_maturity_status` | string (enum) | `"on_time"` | `OVERDUE` quando a data da cessão é posterior ao vencimento; `on_time` nos demais casos. | | `assignment_irr` | número | `0.0312` | Taxa de cessão. | | `purchase_irr` | número | `0.03187421` | Taxa de compra do recebível. | | `has_assignor_coobligation` | string | `"False"` | Coobrigação do cedente, como texto `"True"` ou `"False"`. | | `asset_external_id` **ou** `invoice_number` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Operação de crédito: identificador externo do ativo (`asset_external_id`). Direito creditório descontado: chave de acesso da NF-e (`invoice_number`). | | `monthly_rate` | string | `"0.0231"` | Taxa mensal pré-fixada. **Só existe no arquivo de operações de crédito** — no de direitos creditórios descontados a coluna não é emitida. | ## Colunas opcionais Podem ser solicitadas na geração do relatório e são acrescentadas **ao final** do arquivo, nesta ordem. Valem apenas para **operações de crédito**. | Coluna | Descrição | |--------|-----------| | `installment_number` | Número da parcela. | | `disbursement_value` | Valor desembolsado no contrato. | | `cet` | Custo Efetivo Total do contrato. | | `issue_value` | Valor de emissão do contrato. | | `interest_rate_type` | Tipo da taxa de juros da operação. | | `borrower_birthdate` | Data de nascimento do devedor (pessoa natural). | | `benefit_type` | Tipo de benefício da primeira garantia da operação. | :::note Como pedir as colunas opcionais A habilitação é feita pela QI CTVM na configuração da entrega, por relatório. Se você precisar de alguma dessas colunas, informe ao time de integração quais deseja. ::: --- # Lastros da Cessão URL: /documentation/iaas/relatorios_dtvm/assignment_documents ## Visão Geral O relatório `assignment_documents` lista os **documentos comprobatórios** dos ativos de uma cessão específica, com um link de download para cada arquivo. É o relatório usado para arquivar o lastro da operação: uma linha por documento, com a chave do ativo a que ele pertence. Ele é o complemento da [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition): aquele traz os valores e características dos ativos cedidos, este traz os arquivos que os comprovam. ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo da cessão. | | `external_id` | sim | O "seu número" da cessão a consultar. | Este relatório **não recebe data de referência** — ele sempre reflete os documentos existentes no momento da geração. ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | CSV | | Encoding | UTF-8 | | Delimitador | `,` (vírgula) | | Cabeçalho | Sim (primeira linha) | | Nomenclatura | `{nome_resumido_fundo}_assignment_documents_{external_id}_{AAAA-MM-DD}.csv` | :::warning A nomenclatura deste relatório é diferente Duas diferenças em relação aos outros relatórios: 1. o identificador da cessão vem **antes** da data, e não no fim do nome — compare com o `assignment_assets_wallet_composition`, que acrescenta o `external_id` no final; 2. a data no nome é a **data de geração do arquivo** (fuso de Brasília), não uma data de referência informada por você. Gerar o mesmo relatório em dois dias diferentes produz dois nomes diferentes para o mesmo conteúdo. ::: ## Colunas | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `assignment_external_id` | string | `"CESSAO-2026-07-29-001"` | Identificador externo da cessão. Igual em todas as linhas do arquivo. | | `asset_key` | string | `"1a2b3c40-0001-4aaa-9111-000000000101"` | Chave interna do ativo gerada pela QI Tech (UUID). Repete-se quando o ativo tem mais de um documento. | | `asset_external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo. | | `document_key` | string | `"50e60f70-0001-4fff-9666-000000000601"` | Chave interna do documento gerada pela QI Tech (UUID). | | `document_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"`, `"discounted_contract"`, `"cte"`, `"invoice"` | Tipo do documento. Acompanha o tipo do ativo, exceto `invoice`, que é a nota fiscal do recebível. | | `document_url` | string | `"https://...s3.amazonaws.com/...?X-Amz-Signature=..."` | Link de download direto do arquivo. Veja o aviso sobre validade abaixo. | :::danger Os links expiram em 5 dias `document_url` é uma URL pré-assinada, gerada no momento em que o relatório é produzido e válida por **5 dias (432.000 segundos)**. Depois disso o link retorna erro e é preciso gerar o relatório novamente para obter links novos. Não armazene as URLs como referência permanente do documento. Se você precisa guardar o lastro, **baixe os arquivos** dentro da janela de validade e use `document_key` como identificador estável do documento. ::: :::tip Testando a captura dos arquivos Para exercitar o download em sandbox com links reais — e com documentos de exemplo de cada `document_type` — siga o roteiro em [Testando a Captura de Lastro](/documentation/iaas/relatorios_dtvm/testar_captura_lastro). ::: ## O que o relatório traz - Os documentos de todos os ativos da cessão informada, **exceto** os dos ativos descartados (`discarded`) e reprovados (`denied`). - **Uma linha por documento.** Um ativo com contrato e nota fiscal aparece em duas linhas, com o mesmo `asset_key` e `document_type` diferentes. - Ativos sem documento anexado não aparecem no arquivo. :::tip Cruzando com a composição da cessão `asset_external_id` e `asset_key` são as chaves de junção com a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition). Cruzando os dois arquivos você confere se todo ativo cedido tem o lastro correspondente — um ativo presente na composição e ausente aqui é um ativo sem documento anexado. ::: --- # Relatório de Balanço URL: /documentation/iaas/relatorios_dtvm/balance_report ## Visão Geral O relatório `balance_report` apresenta o balanço contábil consolidado do fundo entre duas datas de referência. Ele exibe, para cada conta do plano de contas, o saldo inicial (Data de Início), os movimentos de débito e crédito ocorridos no período e o saldo final (Data Final). O relatório organiza as contas em uma estrutura hierárquica (grupos e subgrupos) e inclui totalizadores para ativo, passivo, patrimônio líquido, receitas, despesas e compensações. Administradores e analistas utilizam este relatório para verificar a consistência contábil e auditar a evolução do balanço do fundo. ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. | | `start_date` | sim | Data de início do período, no formato `AAAA-MM-DD`. | | `end_date` | sim | Data de fim do período, no formato `AAAA-MM-DD`. Precisa ser **posterior** à data de início. | :::warning É preciso haver contabilidade fechada nas duas datas O relatório só é gerado se existir fechamento contábil na data de início **e** na data de fim. Sem isso a solicitação é recusada com a mensagem "Não existe contabil na data ...". ::: :::warning As duas datas têm de estar no mesmo exercício contábil Além de existir fechamento nas duas datas, elas precisam pertencer ao **mesmo exercício** (mesmo *ledger*). Um período que atravessa o encerramento de exercício faz a geração falhar. ::: ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | XLSX | | Nomenclatura | `{nome_resumido_fundo}_balance_report_{YYYY-MM-DD}.xlsx` | ## Conteúdo da Planilha ### Cabeçalho do Fundo Apresentado nas primeiras linhas da planilha: | Campo | Descrição | |-------|-----------| | Nome do Fundo | Nome completo da classe de fundo. | | CNPJ do Fundo | CNPJ da classe de fundo. | | Data de Início | Data de início do período no formato `YYYY-MM-DD`. | | Data Final | Data de fim do período no formato `YYYY-MM-DD`. | | Total do Ativo | Soma do saldo final das contas de ativo. | | Total do Passivo | Soma do saldo final das contas de passivo. | | Total de PL | Saldo final das contas de patrimônio líquido. | | Total de Receitas | Saldo final das contas de receita. | | Total de Despesas | Saldo final das contas de despesa. | | Total de Compensação Ativa | Saldo final das contas de compensação ativa (grupo 3). | | Total de Compensação Passiva | Saldo final das contas de compensação passiva (grupo 9). | | PL por Contas Patrimoniais | `Total do Ativo - Total do Passivo` | | PL por Contas de Resultado | `Total de PL + Total de Receitas + Total de Despesas` | | Bate Compensação | `Total de Compensação Ativa - Total de Compensação Passiva` | :::note Os totais são fórmulas do Excel As células do cabeçalho não são valores fixos: elas referenciam as linhas de total da tabela de contas (por exemplo, `Total do Ativo` é `=G20`). Ao abrir o arquivo, o Excel recalcula tudo — e, se você editar a tabela, os totais acompanham. ::: ### Tabela de Contas Linhas organizadas hierarquicamente por número de conta, sem formatação especial — apenas a linha de cabeçalho da tabela vem em negrito: | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `Número da Conta` | string | `"1.1.2.80.00.010.001-8"` | Número da conta no plano de contas, com dígito verificador. As linhas de grupo trazem o número do nível correspondente — por exemplo `1-7` (ATIVO) e `1.1-6` (DISPONIBILIDADES). | | `Nome da Conta` | string | `"Conta Caixa - Banco Exemplo"` | Nome descritivo da conta contábil. | | `Tipo da Conta` | string (enum) | `"A"` | Tipo da linha: `"A"` para conta analítica; `"S"` para conta sintética (agrupadora, exibida em negrito). | | `Saldo em Término de {Data de Início}` | número | `40000.00` | Saldo da conta na Data de Início, em reais. Negativo indica saldo de natureza contrária à conta. | | `Movimentos de Débito` | número | `5000.00` | Soma dos lançamentos a débito no período (em reais). O sinal segue a natureza da conta: positivo nas contas devedoras, negativo nas credoras. | | `Movimentos de Crédito` | número | `0.00` | Soma dos lançamentos a crédito no período (em reais). Sinal invertido em relação à coluna de débito: negativo nas contas devedoras, positivo nas credoras. | | `Saldo em Término de {Data Final}` | número | `45000.00` | Saldo da conta na Data Final, em reais. | --- # Demonstrativo de Caixa URL: /documentation/iaas/relatorios_dtvm/cash_account_demonstrative ## Visão Geral O relatório `cash_account_demonstrative` é um extrato diário das movimentações e saldos das contas bancárias do fundo ao fim do dia. Ele é gerado uma vez por dia, após o encerramento do ciclo financeiro, e apresenta os saldos de abertura (D-1) e encerramento (D0) de cada conta, além de todas as transações ocorridas ao longo do dia. Gestores e administradores utilizam este relatório para conferir a posição de caixa e conciliar as movimentações financeiras do fundo. O relatório pode ser gerado em modo de fundo único ou em modo multi-fundo. No modo multi-fundo, cada classe de fundo é apresentada em uma aba separada dentro da mesma planilha. ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. | | `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. | ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | XLSX | | Aba | `Demonstrativo de Caixa` (no modo multi-fundo, uma aba por fundo, nomeada com o nome do fundo) | | Nomenclatura | `{nome_resumido_fundo}_cash_account_demonstrative_{AAAA-MM-DD}.xlsx` | :::tip Versão para conciliação automatizada Este relatório é uma planilha formatada para leitura. Para conciliar as movimentações de forma automatizada — com identificador de transação, tipo, status de conciliação e saldos antes e depois de cada lançamento — utilize o relatório [Movimentações de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements), em CSV. ::: ## Conteúdo da Planilha Cada aba da planilha (uma por fundo) contém as seguintes seções: ### Cabeçalho do Fundo Apresentado no topo da aba, com as informações de identificação da classe de fundo: | Campo | Descrição | |-------|-----------| | Data de referência | Data de referência do relatório no formato `YYYY-MM-DD`. | | Nome da classe de fundo | Nome completo da classe de fundo. | | CNPJ da classe de fundo | CNPJ da classe de fundo. | | Nome da gestora | Nome da gestora responsável pelo fundo. | | CNPJ da gestora | CNPJ da gestora responsável pelo fundo. | ### Extrato por Conta Bancária Abaixo do cabeçalho, sob o título **Extrato**, é exibida uma tabela por conta bancária do fundo, com as seguintes colunas: | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `Data de referência` | data | `2026-07-29` | Data de referência do relatório. | | `Banco` | string | `"999 - BANCO EXEMPLO S.A."` | Código COMPE e nome da instituição financeira, no formato `{código} - {nome}`. | | `Agência/Conta` | string | `"0001/4417206-9"` | Número da agência e da conta, no formato `{agência}/{conta}-{dígito}`. | | `Descrição` | string | `"Liquidação de parcelas"` | Descrição da movimentação conforme o grupo de conciliação da transação. | | `Valor (R$)` | número | `2417.86` | Valor da movimentação em reais. Valores negativos indicam saída de caixa. | Cada tabela de conta exibe ainda três linhas de resumo, em negrito e com fundo cinza. Nessas linhas, o rótulo (`Saldo D-1`, `Total`, `Saldo D0`) ocupa a primeira coluna, no lugar da data de referência: | Linha | Posição | Descrição | |-------|---------|-----------| | **Saldo D-1** | primeira linha da tabela | Saldo da conta ao início do dia (encerramento do dia anterior). | | **Total** | após as movimentações | Soma de todas as movimentações do dia para a conta. | | **Saldo D0** | última linha da tabela | Saldo da conta ao encerramento do dia de referência. | --- # Movimentações de Caixa URL: /documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements ## Visão Geral O relatório `cash_account_demonstrative_movements` lista, transação a transação, todas as movimentações das contas bancárias do fundo na data de referência. É a versão tabular do [Demonstrativo de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative): enquanto o demonstrativo é uma planilha formatada para leitura, este arquivo é um CSV pensado para conciliação automatizada, com o identificador de cada transação, o tipo, o status de conciliação e os saldos antes e depois do lançamento. :::info Janela do dia São consideradas as transações registradas entre 03:00 (UTC) da data de referência e 03:00 (UTC) do dia seguinte — ou seja, o dia inteiro no horário de Brasília. As linhas vêm ordenadas por data e hora da transação. ::: ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. | | `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. | ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | CSV | | Encoding | UTF-8 | | Delimitador | `,` (vírgula) | | Cabeçalho | Sim (primeira linha) | | Nomenclatura | `{nome_resumido_fundo}_cash_account_demonstrative_movements_{AAAA-MM-DD}.csv` | :::warning Valores em centavos As colunas `amount`, `previous_balance` e `post_balance` são números **inteiros em centavos** — `241786` significa R$ 2.417,86. Diferente dos demais relatórios, que trazem valores em reais. ::: ## Colunas | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `fund_class_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. | | `fund_class_document_number` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. | | `account_number` | string | `"4417206"` | Número da conta bancária, sem o dígito. | | `account_digit` | string | `"9"` | Dígito verificador da conta. | | `account_branch` | string | `"0001"` | Agência da conta. | | `if_name` | string | `"BANCO EXEMPLO S.A."` | Nome da instituição financeira. | | `if_code` | string | `"999"` | Código COMPE da instituição financeira. | | `if_ispb` | string | `"99999999"` | ISPB da instituição financeira. | | `transaction_key` | string | `"30c40d50-0001-4ddd-9444-000000000401"` | Identificador único da transação na QI CTVM (UUID). | | `external_key` | string | `"40d50e60-0001-4eee-9555-000000000501"` | Identificador da transação na instituição financeira de origem. | | `transaction_description` | string | `"Liquidação de parcelas de CCB"` | Descrição da transação conforme informada pela instituição financeira. | | `transaction_type` | string (enum) | `"incoming_pix"` | Tipo da transação. Ver [tabela de tipos](#tipos-de-transação). | | `transaction_status` | string (enum) | `"reconciled"` | Status de conciliação: `created`, `pending_conciliation` ou `reconciled`. | | `amount` | inteiro (centavos) | `241786` | Valor da transação. Negativo indica saída de caixa. | | `previous_balance` | inteiro (centavos) | `52811947` | Saldo da conta antes da transação. | | `post_balance` | inteiro (centavos) | `53053733` | Saldo da conta após a transação. | | `transaction_datetime` | data | `2026-07-29` | Data e hora da transação. **No arquivo, o campo é exportado apenas com a data**, no formato `AAAA-MM-DD`. | | `accounting_date` | data | `2026-07-29` | Data contábil atribuída à transação. | | `conciliation_description` | string | `"Liquidação de parcelas"` | Descrição do grupo de conciliação ao qual a transação foi associada. Vazio enquanto a transação não é conciliada. | ## Tipos de transação | Valor | Descrição | |-------|-----------| | `incoming_pix` | Pix recebido. | | `outgoing_pix` | Pix enviado. | | `incoming_wire_transfer` | TED recebida. | | `outgoing_wire_transfer` | TED enviada. | | `outgoing_bank_slip_payment` | Pagamento de boleto. | | `incoming_bank_slip_payment_reversal` | Estorno de pagamento de boleto. | | `outgoing_bankslip_registration` | Custo de registro de boleto. | | `outgoing_bankslip_payment` | Custo de pagamento de boleto. | | `outgoing_bankslip_due_date_extension` | Custo de prorrogação de vencimento de boleto. | | `outgoing_bankslip_permanence` | Custo de permanência de boleto. | | `outgoing_bankslip_rebate` | Custo de abatimento de boleto. | | `outgoing_bankslip_write_off` | Custo de baixa de boleto. | --- # Aquisição Consolidada de Direitos Creditórios URL: /documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets ## Visão Geral O relatório `consolidated_credit_rights_acquisition_assets` lista os direitos creditórios adquiridos pelo fundo na data de referência, com os valores de compra, o spread e as características da operação. Em um único arquivo, ele reúne as duas naturezas de ativo: - **operações de crédito** (ex: CCB) — uma linha por **parcela** adquirida; - **direitos creditórios descontados** (ex: duplicatas) — uma linha por **ativo**, já que não têm parcelas. Este relatório substitui os antigos `credit_rights_acquisition_assets`, `credit_rights_acquisition_installments` e `discounted_credit_rights_acquisition_assets`, que deixaram de ser entregues. :::tip Também em PDF Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](./manual_relatorios_qi_tech.pdf) — revisão 2, julho de 2026. O manual cobre quatro relatórios: este, a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), a [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) e a [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets). ::: ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. | | `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. | ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | CSV | | Encoding | UTF-8 | | Delimitador | `,` (vírgula) | | Cabeçalho | Sim (primeira linha) | | Nomenclatura | `{nome_resumido_fundo}_consolidated_credit_rights_acquisition_assets_{YYYY-MM-DD}.csv` | ## O que o relatório traz - Os ativos comprados na data de referência (`purchase_date` igual à data informada). - Ativos inativos são excluídos. - Campos sem valor vêm **vazios** no arquivo. :::info Fundos de cota de abertura Para os fundos que operam com relatório de cota de abertura, o ramo de direitos creditórios descontados usa o **dia útil imediatamente anterior** à data de referência, enquanto o ramo de operações de crédito usa a própria data. As duas naturezas convivem no mesmo arquivo com datas de referência diferentes. ::: ## Colunas | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `reference_date` | data | `2026-07-29` | Data de compra do ativo. | | `fund_class_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. | | `fund_class_document_number` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. | | `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora do ativo. | | `originator_document_number` | string | `"11.222.333/0001-44"` | CNPJ do originador. | | `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente. | | `assignor_document_number` | string | `"22.333.444/0001-55"` | CNPJ do cedente. | | `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor (tomador do crédito) ou do sacado. | | `borrower_document_number` | string | `"123.456.789-00"` | CPF ou CNPJ do devedor/sacado. | | `asset_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"` | Tipo do ativo. Determina qual dos dois ramos originou a linha. | | `has_assignor_coobligation` | booleano | `False` | Indica se há coobrigação do cedente. | | `asset_key` | string | `"1a2b3c40-0001-4aaa-9111-000000000101"` | Chave interna do ativo gerada pela QI Tech (UUID). | | `contract_number` | string | `"0900112233/EXA"` | Número do contrato (operação de crédito) ou do pedido (direito creditório descontado). Para direito creditório descontado sem número de pedido, cai no número do contrato. | | `external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo. | | `installment_number` | número | `1` | Número da parcela. Para direito creditório descontado, sempre `1`. | | `issue_date` | data | `2026-07-28` | Data de emissão do contrato. Para direito creditório descontado, vem `-`. | | `purchase_date` | data | `2026-07-29` | Data de compra do ativo pelo fundo. | | `installment_maturity_date` | data | `2026-08-28` | Data de vencimento da parcela. Para direito creditório descontado, é o vencimento do próprio ativo. | | `total_purchase_value` | número | `4712.35` | Valor total pago pelo ativo, incluindo encargos (em reais). Repete-se em todas as parcelas do mesmo ativo. | | `asset_purchase_value` | número | `4690.8` | Valor do ativo sem encargos e sem spread (em reais). | | `installment_purchase_value` | número | `1598.7421` | Valor de compra da parcela (em reais). Para direito creditório descontado, é igual ao `total_purchase_value`. | | `principal_value` | número | `1480.12` | Valor de principal da parcela (em reais). Para direito creditório descontado, vem **vazio**. | | `face_value` | número | `1678.9` | Valor de face da parcela ou do ativo (em reais). | | `index` | string (enum) | `"pre_fixed"` | Indexador / tipo de taxa de juros. Para direito creditório descontado, sempre `pre_fixed`. | | `index_calendar_base` | string (enum) | `"calendar_365"`, `"calendar_360"`, `"workdays"` | Base de calendário usada na apropriação de juros. Para direito creditório descontado, sempre `workdays`. | | `monthly_rate` | string | `"0.0231"` | Taxa mensal pré-fixada do contrato. Para direito creditório descontado, traz a **taxa de compra do recebível (TIR)**, e não uma taxa mensal — no exemplo, `0.19842300000000`. | | `calendar_base` | string (enum) | `"calendar_365"` | Base de calendário do pré-fixado. Para direito creditório descontado, sempre `workdays`. | | `iof_value` | string | `"52.40"` | Valor de IOF do contrato. Para direito creditório descontado, vem `-`. | | `maturity_date` | data | `2026-10-28` | Data de vencimento final do ativo. | | `total_purchase_spread` | número | `21.55` | Spread de aquisição (`total_purchase_value − asset_purchase_value`), em reais. **Nunca negativo**: quando a diferença é menor que zero, o campo vem `0`. | :::note Como cruzar as linhas de um mesmo ativo As parcelas de uma operação de crédito repetem `asset_key`, `external_id` e `contract_number`, e variam apenas em `installment_number`, `installment_maturity_date`, `installment_purchase_value`, `principal_value` e `face_value`. Os valores de nível de ativo (`total_purchase_value`, `asset_purchase_value`, `total_purchase_spread`) se repetem em todas as parcelas — **não devem ser somados** por linha. ::: --- # Conciliação Consolidada de Direitos Creditórios URL: /documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets ## Visão Geral O relatório `consolidated_credit_rights_conciliation_assets` lista os eventos de pagamento dos direitos creditórios registrados em uma data contábil, mostrando o efeito de cada pagamento sobre o valor do ativo: valor antes, valor depois, redução e resultado contábil apurado. Em um único arquivo, ele reúne as duas naturezas de ativo: - **operações de crédito** (ex: CCB); - **direitos creditórios descontados** (ex: duplicatas). Este relatório substitui os antigos `credit_rights_conciliation_assets`, `credit_rights_conciliation_installments` e `discounted_credit_rights_conciliation_assets`, que deixaram de ser entregues. :::tip Também em PDF Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](./manual_relatorios_qi_tech.pdf) — revisão 2, julho de 2026. O manual cobre quatro relatórios: este, a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), a [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) e a [Aquisição Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets). ::: ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. | | `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. | ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | CSV | | Encoding | UTF-8 | | Delimitador | `,` (vírgula) | | Cabeçalho | Sim (primeira linha) | | Nomenclatura | `{nome_resumido_fundo}_consolidated_credit_rights_conciliation_assets_{YYYY-MM-DD}.csv` | ## O que o relatório traz - Os eventos de pagamento cuja data contábil é a data de referência. - Considera os ativos nas situações **ativo**, **vendido**, **liquidado** e **baixado**. - Cada linha é **um evento de pagamento** — um mesmo ativo pode aparecer em várias linhas no mesmo dia. :::info Campos sem valor vêm como `-` Diferente dos outros relatórios em CSV, este preenche os campos nulos com `-` em vez de deixá-los vazios. ::: :::info Fundos de cota de abertura Para os fundos que operam com relatório de cota de abertura, o ramo de direitos creditórios descontados usa o **dia anterior** à data de referência, enquanto o ramo de operações de crédito usa a própria data. ::: ## Colunas | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `reference_date` | data | `2026-07-29` | Data contábil do evento de pagamento. | | `fund_class_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. | | `fund_class_document_number` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. | | `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora do ativo. | | `originator_document_number` | string | `"11.222.333/0001-44"` | CNPJ do originador. | | `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente. | | `assignor_document_number` | string | `"22.333.444/0001-55"` | CNPJ do cedente. | | `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor (tomador do crédito) ou do sacado. | | `borrower_document_number` | string | `"123.456.789-00"` | CPF ou CNPJ do devedor/sacado. | | `asset_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"` | Tipo do ativo. Determina qual dos dois ramos originou a linha. | | `asset_key` | string | `"1a2b3c40-0003-4aaa-9111-000000000103"` | Chave interna do ativo gerada pela QI Tech (UUID). | | `external_id` | string | `"10a20b30-0003-4bbb-9222-000000000203"` | Identificador externo do ativo. | | `contract_number` | string | `"0900098765/EXC"` | Número do contrato (operação de crédito) ou do pedido (direito creditório descontado). Para direito creditório descontado sem número de pedido, cai no número do contrato. | | `maturity_date` | data | `2027-01-11` | Data de vencimento final do ativo. | | `total_purchase_value` | número | `5324.8` | Valor total pago pelo fundo na aquisição do ativo (em reais). | | `purchase_date` | data | `2026-01-12` | Data de aquisição do ativo pelo fundo. | | `internal_rate_of_return` | número | `0.0231` | Taxa interna de retorno do ativo. Operação de crédito: taxa corrente. Direito creditório descontado: taxa de compra do recebível. | | `payment_date` | data | `2026-07-29` | Data contábil do pagamento. Traz sempre o mesmo valor de `reference_date`. | | `payment_amount` | número | `512.68` | Valor pago no evento (em reais). | | `payment_key` | string | `"20b30c40-0001-4ccc-9333-000000000301"` | Chave interna do evento de pagamento gerada pela QI Tech (UUID). | | `payment_type` | string (enum) | `"installment_settlement"`, `"installment_amortization"`, `"asset_settlement"`, `"asset_amortization"`, `"fine_payment"`, `"gloss"`, ... | Tipo do pagamento. | | `payment_event_type` | string (enum) | `"settlement"`, `"substitution"`, `"repurchase"`, `"unperformed"` | Natureza do evento que originou o pagamento: liquidação, substituição, recompra ou inadimplemento. Eventos anteriores à criação deste campo vêm como `-`. | | `old_asset_current_value` | número | `5361.42` | Valor contábil do ativo imediatamente **antes** do evento (em reais). | | `new_asset_current_value` | número | `4890.33` | Valor contábil do ativo imediatamente **depois** do evento (em reais). | | `asset_reduction_value` | número | `471.09` | Redução do valor contábil do ativo (`old − new`), em reais. | | `result_value` | número | `41.59` | Resultado contábil apurado no evento (em reais). | | `written_off_accounting_result_value` | número inteiro | `0` | Resultado contábil de baixa (*write-off*) associado ao evento, **em centavos** — este é o único campo monetário do arquivo que não é convertido para reais. Para direito creditório descontado, sempre `0`. | | `installment_number` | string | `"1"` | Número da parcela liquidada. Para direito creditório descontado, é o sufixo do número do pedido quando ele existe (`8977-3` → `3`); caso contrário, `-`. | :::tip Conferindo o resultado do dia A soma de `result_value` é o resultado contábil reconhecido pelos direitos creditórios na data, e deve fechar com as contas de receita correspondentes no [Relatório de Balanço](/documentation/iaas/relatorios_dtvm/balance_report) e na [Razão Contábil](/documentation/iaas/relatorios_dtvm/accounting_ledger). A soma de `asset_reduction_value` é a variação do estoque explicada por pagamentos no dia. ::: --- # Relatórios DTVM URL: /documentation/iaas/relatorios_dtvm/ Os relatórios DTVM fornecem uma visão detalhada das operações e posições financeiras dos fundos de investimento administrados pela QI CTVM. Eles são destinados a gestores e analistas que precisam acompanhar a composição da carteira, as aquisições e liquidações de ativos, e a movimentação de caixa do fundo em cada data de referência. ## Exemplos de relatórios Baixe exemplos de todos os relatórios disponíveis: [example_reports.zip](./example_reports.zip) O pacote contém um arquivo de cada relatório, gerado pelo mesmo código que produz os arquivos em produção, com dados fictícios. Os exemplos são consistentes entre si: descrevem o mesmo fundo (`FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA`), na mesma data de referência (`2026-07-29`), e fecham entre si — o patrimônio líquido, o saldo de caixa e a posição por classe de ativo são os mesmos em todos os arquivos que trazem esses números. ## Nomenclatura dos arquivos Todos os arquivos seguem o padrão `{nome_resumido_fundo}_{modelo}_{data_de_referência}.{extensão}`, onde: - **nome resumido do fundo** é derivado do nome curto cadastrado para a classe de fundo, em minúsculas, sem acentos e com espaços convertidos em `_` (nos exemplos, `example_name`); - **modelo** é o nome do relatório, conforme a coluna "Modelo" da tabela abaixo; - **data de referência** está no formato `AAAA-MM-DD`. O prefixo vem do cadastro da classe, não da configuração da entrega, e não muda depois. Se você precisa de um prefixo diferente, fale com o time de integração. Há três exceções ao padrão: o `wallet_composition_by_composition` é entregue como `wallet_composition` (sem o sufixo do modelo); o `assignment_assets_wallet_composition` acrescenta o identificador da cessão ao final do nome; e o `assignment_documents` coloca o identificador da cessão **antes** da data, que nele é a data de geração do arquivo. :::info Relatórios de período `quota_mec`, `balance_report` e `accounting_ledger` são gerados a partir de um intervalo (`start_date` / `end_date`), e não de uma única data. Nesses casos, a data no nome do arquivo é a data de referência da entrega. ::: ## Convenções dos arquivos CSV Valem para todos os relatórios em CSV: | Atributo | Padrão | |----------|--------| | Encoding | UTF-8, **sem BOM** | | Delimitador | `,` (vírgula) | | Separador decimal | `.` (ponto) | | Fim de linha | `CRLF` (`\r\n`) | | Cabeçalho | sempre presente, na primeira linha, com os nomes das colunas em minúsculas | :::note Delimitador e separador decimal são configuráveis Se o seu processo exigir `;` como delimitador ou `,` como separador decimal, a QI CTVM pode configurar isso por fundo na entrega. Sem configuração específica, valem os padrões da tabela acima. A exceção é o `quota_mec` em CSV, que usa `;` por definição do relatório. ::: ## Como os relatórios são entregues A entrega é organizada em **rotinas**, configuradas por fundo. Cada rotina define três coisas: **quais** relatórios entram, com **qual periodicidade**, e para **qual destino**. | Elemento | Opções | |----------|--------| | Periodicidade | diária · semanal (primeiro dia útil da semana) · mensal (último dia útil do mês) | | Destino | SFTP · e-mail | Um mesmo fundo pode ter mais de uma rotina — por exemplo, uma diária em SFTP e uma mensal por e-mail. Para incluir ou remover um relatório, mudar a periodicidade ou o destino, entre em contato com o time de integração. ### Quando a rotina é disparada O gatilho é o **fechamento do dia daquele fundo**, e não um horário fixo. O fechamento acontece somente em dia útil, e dispara os relatórios em três momentos distintos: | Momento | Contém | |---------|--------| | Pré-cota | Relatórios apurados antes do cálculo da cota do dia. | | Fechamento | Relatórios da posição consolidada do dia, com a cota de fechamento. | | Abertura | Relatórios apurados sobre a cota de abertura. | Cada relatório é entregue no momento previsto na configuração da rotina do fundo — é por isso que os arquivos de um mesmo dia não chegam todos juntos. Uma rotina semanal ou mensal só materializa arquivos na data em que a periodicidade dela cai; nos outros dias o fechamento roda e ela não produz nada. ### Relatórios fora da rotina Dois relatórios não seguem a periodicidade da rotina, porque não são do dia do fundo e sim de uma operação: a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) e os [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents). Os dois são gerados quando a cessão entra na etapa de aprovação, desde que estejam habilitados na configuração de cessão, e são gravados na mesma pasta de SFTP do fundo. Eles **não** emitem o [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega) — o acompanhamento é pelo [webhook de status do lote de cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). ### Entrega via SFTP Cada arquivo é gravado na pasta configurada para o fundo, com exatamente o nome descrito acima. Para instruções de conexão, credenciais e exemplos de código para download, consulte a [documentação de integração SFTP](/documentation/iaas/integracao_sftp/inicio). :::tip Você pode ser avisado a cada entrega concluída Em vez de varrer a pasta em intervalos fixos, configure o [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega): ao fim de cada entrega, a QI CTVM notifica a sua aplicação com a lista de arquivos gravados e o status de cada relatório. ::: ## Relatórios disponíveis | Relatório | Descrição | Modelo | Formato do arquivo | |-----------|-----------|--------|-------------------| | [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) | Posição completa de todos os ativos que compõem o estoque do fundo em uma data de referência, ativo a ativo. | `assets_wallet_composition` | CSV | | [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) | Ativos de uma cessão específica, no mesmo formato da composição de carteira. Gerado por cessão, fora da rotina diária. | `assignment_assets_wallet_composition` | CSV | | [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) | Documentos comprobatórios dos ativos de uma cessão, com link de download por arquivo. Gerado por cessão, fora da rotina diária. | `assignment_documents` | CSV | | [Composição da Carteira](/documentation/iaas/relatorios_dtvm/wallet_composition) | Carteira consolidada do fundo ao fim do dia, por classe de ativo, com séries de emissão, valores a pagar e a receber, caixa, rentabilidade e resultado. | `wallet_composition_by_composition` | XLSX | | [Aquisição Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) | Direitos creditórios adquiridos em um dia — operações de crédito por parcela e direitos creditórios descontados por ativo, no mesmo arquivo. | `consolidated_credit_rights_acquisition_assets` | CSV | | [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets) | Eventos de pagamento dos direitos creditórios em uma data contábil, com o efeito de cada pagamento sobre o valor do ativo. | `consolidated_credit_rights_conciliation_assets` | CSV | | [Demonstrativo de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative) | Extrato diário das movimentações e saldos das contas bancárias do fundo. | `cash_account_demonstrative` | XLSX | | [Movimentações de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements) | Mesma movimentação do demonstrativo de caixa em formato tabular, transação a transação, para conciliação automatizada. | `cash_account_demonstrative_movements` | CSV | | [Cotas MEC](/documentation/iaas/relatorios_dtvm/quota_mec) | Evolução diária de cotas, patrimônio e rentabilidade das séries de emissão. | `quota_mec` | XLSX ou CSV | | [Relatório de Balanço](/documentation/iaas/relatorios_dtvm/balance_report) | Balanço contábil consolidado do fundo com saldos e movimentações por conta. | `balance_report` | XLSX | | [Razão Contábil](/documentation/iaas/relatorios_dtvm/accounting_ledger) | Razão contábil detalhado com todos os lançamentos por conta no período. | `accounting_ledger` | XLSX | | [XML ANBIMA (tipos 5 e 401)](/documentation/iaas/relatorios_dtvm/xml_anbima) | Arquivos de posição no padrão ANBIMA, gerados a partir da composição da carteira. | `xml_5_by_composition` `xml_401_by_composition` | XML | --- # Cotas MEC URL: /documentation/iaas/relatorios_dtvm/quota_mec ## Visão Geral O relatório `quota_mec` apresenta a evolução diária das cotas e do patrimônio do fundo em um intervalo de datas, calculada com base nos fechamentos de série de emissão. Cada linha representa um dia útil de uma série de emissão, contendo valores de patrimônio bruto e líquido, cota de fechamento, movimentações de aplicação e resgate, come-cotas e rentabilidade acumulada diária, mensal e anual. Gestores e administradores utilizam este relatório para acompanhar a performance do fundo e enviar informações regulatórias ao MEC (Método de Envio de Cota). O relatório pode ser gerado nos formatos XLSX (uma aba por classe de fundo) ou CSV. O CSV só é aceito quando o pedido cobre **uma única classe de fundo**. ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. | | `start_date` | sim | Data de início do período, no formato `AAAA-MM-DD`. | | `end_date` | sim | Data de fim do período, no formato `AAAA-MM-DD`. Não pode ser anterior à data de início. | | `include_secondary_market` | não | Booleano. Quando omitido, vale `true`. | | `file_format` | não | `xlsx` (padrão) ou `csv`. Qualquer outro valor é recusado. | | `issuance_serie_key` | não | Restringe o arquivo a uma única série de emissão. | :::warning É preciso haver cota no período O relatório só é gerado se ao menos uma série de emissão da classe tiver valor de cota (de abertura ou de fechamento) dentro do intervalo. Sem isso a solicitação é recusada. ::: ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | XLSX ou CSV | | Encoding | UTF-8 | | Delimitador (CSV) | `;` (ponto e vírgula) | | Nomenclatura | `{nome_resumido_fundo}_quota_mec_{AAAA-MM-DD}.xlsx` (ou `.csv`) | No XLSX, cada classe de fundo ocupa uma aba, nomeada com o nome do fundo (limitado a 31 caracteres pelo Excel), o cabeçalho vem em português e as linhas em ordem cronológica crescente. Datas são apresentadas no formato `DD/MM/AAAA`. :::info Variação no formato CSV O CSV é gerado apenas para uma classe de fundo por arquivo e difere do XLSX em dois pontos: o cabeçalho vem com os **nomes técnicos em inglês** (`fund_class_name`, `fund_class_document_number`, `sub_class_name`, `issuance_serie_name`, `accounting_date`, `gross_net_worth`, `gross_quota_value`, `performance_fee_current_value`, `net_net_worth`, `net_quota_value`, `final_net_worth`, `final_quota_value`, `total_net_worth`, `issued_quotas`, `total_daily_applications`, `redeemed_quotas`, `total_daily_redemptions`, `tax_anticipated_quotas`, `total_daily_tax_anticipations`, `total_daily_amortizations`, `daily_rentability`, `monthly_rentability`, `yearly_rentability`), na mesma ordem da tabela abaixo; e as linhas vêm em ordem **cronológica decrescente**, da data mais recente para a mais antiga. ::: ## Colunas | Coluna | Tipo | Formato / Exemplo | Descrição | |--------|------|-------------------|-----------| | `Nome do Fundo` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. | | `CNPJ do Fundo` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. | | `Sub Classe` | string | `"SUBORDINADA"` | Nome da subclasse do fundo. | | `Série de Emissão` | string | `"PRIMEIRA"` | Nome da série de emissão. | | `Data de Referência` | data | `29/07/2026` | Data contábil de referência (apenas dias úteis). | | `Patrimônio Bruto` | número | `10500000.00` | Patrimônio líquido bruto antes da provisão de taxa de performance (em reais). | | `Cota Bruta` | número | `1.050000` | Valor da cota bruta antes da taxa de performance. | | `Taxa de Performance` | número | `5000.00` | Valor corrente da taxa de performance provisionada (em reais). | | `PL Pré Movimentação` | número | `10495000.00` | Patrimônio líquido antes das movimentações do dia (em reais). | | `Cota Pré Movimentação` | número | `1.049500` | Valor da cota antes das movimentações do dia. | | `PL de Fechamento` | número | `10495000.00` | Patrimônio líquido de fechamento antes das amortizações (em reais). | | `Cota de Fechamento` | número | `1.049500` | Valor da cota de fechamento antes das amortizações. | | `PL Pós Movimentações` | número | `10490000.00` | Patrimônio líquido total após todas as movimentações do dia (em reais). | | `Cotas Integralizadas` | número | `1000.00000` | Quantidade de cotas emitidas (aplicadas) no dia. | | `Total Aplicado` | número | `1049500.00` | Valor total aplicado no dia (em reais). | | `Cotas Resgatadas` | número | `500.00000` | Quantidade de cotas resgatadas no dia. | | `Total Resgatado` | número | `524750.00` | Valor total resgatado no dia (em reais). | | `Come-cotas` | número | `200.00000` | Quantidade de cotas consumidas pela antecipação de IR (come-cotas). | | `Total de Come-cotas` | número | `200.00` | Valor total do come-cotas do dia (em reais). | | `Total Amortizado` | número | `0.00` | Valor total amortizado no dia (em reais). | | `Rentabilidade Diária` | número | `0.000420` | Rentabilidade do dia, calculada como `(cota_pré_movimentação / cota_fechamento_anterior) - 1`. | | `Rentabilidade Mensal` | número | `0.005200` | Rentabilidade acumulada no mês corrente (base composta). Reinicia no início de cada mês. | | `Rentabilidade Anual` | número | `0.063000` | Rentabilidade acumulada no ano corrente (base composta). Reinicia no início de cada ano. | --- # Testando a Captura de Lastro URL: /documentation/iaas/relatorios_dtvm/testar_captura_lastro Esta página é um roteiro para quem está construindo a leitura automatizada dos [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) e precisa de um `document_url` que funcione de verdade para testar antes de ir a produção. A ideia é simples: em sandbox, você roda uma cessão de ponta a ponta usando os PDFs de exemplo que disponibilizamos abaixo. O `assignment_documents` é gerado pelo mesmo código que gera o relatório em produção, com links pré-assinados legítimos — nada é montado à mão. :::info Por que não entregamos um arquivo pronto com links `document_url` é uma URL pré-assinada de S3, gerada no momento em que o relatório é produzido e válida por 5 dias. Um arquivo estático com links reais expiraria antes de chegar até você. Rodando o roteiro, você gera links novos sempre que precisar. ::: ## O que você precisa ter em sandbox Este teste usa o fluxo normal de cessão, então ele pressupõe o mesmo setup de qualquer integração: | Item | Como obter | |------|------------| | Classe de fundo (`fund_class_key`) | Fornecida pelo time de integração. | | Configuração de cessão (`assignment_configuration_key`) | Fornecida pelo time de integração. Ela define o tipo de ativo da cessão e quais documentos são exigidos. | | `assignment_documents` na rotina de relatórios da configuração | Peça ao time de integração para incluir o relatório na configuração de cessão. Sem isso o arquivo não é gerado. | | Destino de entrega (SFTP) | Configurado junto com a rotina de relatórios. Veja a [integração SFTP](/documentation/iaas/integracao_sftp/inicio). | :::warning Não há atalho para o setup Não existe caminho que produza um `document_url` real sem uma cessão real em sandbox — o relatório é uma consulta aos documentos efetivamente anexados aos ativos daquela cessão. Se o seu objetivo é apenas conferir a estrutura das colunas, use o [pacote de exemplos](/documentation/iaas/relatorios_dtvm/) da introdução, que traz o CSV com URL de exemplo no formato correto. ::: ## Arquivos de exemplo Um documento por `document_type`, com dados fictícios, texto extraível (não são imagem) e a estrutura típica de cada tipo: [📦 Baixar todos (lastros_exemplo.zip)](/downloads/lastros_exemplo.zip) | Arquivo | `document_type` | O que é | |---------|-----------------|---------| | [ccb_exemplo_01.pdf](/downloads/lastros_exemplo/ccb_exemplo_01.pdf) | `ccb` | CCB emitida pela QI SCD, 3 parcelas, 22 páginas com cadeia de endossos | | [ccb_exemplo_02.pdf](/downloads/lastros_exemplo/ccb_exemplo_02.pdf) | `ccb` | CCB emitida pela QI SCD, 2 parcelas, 22 páginas com cadeia de endossos | | [duplicata_mercantil_exemplo.pdf](/downloads/lastros_exemplo/duplicata_mercantil_exemplo.pdf) | `duplicata_mercantil` | Duplicata mercantil com chave de acesso da NF-e | | [invoice_exemplo.pdf](/downloads/lastros_exemplo/invoice_exemplo.pdf) | `invoice` | DANFE da NF-e referenciada pela duplicata | | [duplicata_servicos_exemplo.pdf](/downloads/lastros_exemplo/duplicata_servicos_exemplo.pdf) | `duplicata_servicos` | Duplicata de prestação de serviços, referenciando NFS-e | | [cte_exemplo.pdf](/downloads/lastros_exemplo/cte_exemplo.pdf) | `cte` | DACTE | | [discounted_contract_exemplo.pdf](/downloads/lastros_exemplo/discounted_contract_exemplo.pdf) | `discounted_contract` | Contrato de prestação de serviços com cláusula de cessão | :::danger Estes arquivos são fictícios Nenhum deles tem validade jurídica ou fiscal, nenhum foi transmitido à SEFAZ e nenhum contém dados de pessoas ou empresas reais. Servem exclusivamente para teste de leitura. ::: Os dois PDFs de `ccb` são consistentes com o `example_reports.zip` publicado na [introdução aos relatórios](/documentation/iaas/relatorios_dtvm/): mesmos números de contrato (`0900112233/EXA` e `0900112247/EXB`), mesmos valores de parcela, mesmos vencimentos e mesma taxa mensal que aparecem no `assignment_assets_wallet_composition` de exemplo. :::tip As CCBs de exemplo seguem o layout real de emissão da QI Tech Os dois PDFs de `ccb` são a estrutura de verdade de uma CCB emitida pela **QI Sociedade de Crédito Direto S.A.** — os Quadros I a XI na ordem em que aparecem no documento real, com o texto integral das condições gerais e especiais, a página de assinatura eletrônica do emitente e a **cadeia de endossos** até o fundo. É o documento que o seu leitor vai encontrar em produção quando o originador emite pela QI Tech, com os dados trocados por fictícios. Três partes que costumam ser as mais úteis para validação de lastro: - **Quadro V, item 5** — a tabela com as datas possíveis de liberação. Cada linha tem seu próprio Valor Total, IOF, Valor Líquido e CET; a linha que vale é a da data em que os recursos foram efetivamente liberados. Um leitor que assuma uma linha só extrai o valor errado. - **Quadro V, item 13** — o demonstrativo do CET, que reconcilia com a **primeira** linha da tabela do item 5. - **Endossos (últimas páginas)** — a cadeia `QI SCD → cedente → fundo`, cada elo com sua própria página de assinatura digital (hash, data, signatários). É por aí que se comprova a titularidade do título pelo fundo. O `document_type` do relatório continua sendo a fonte de verdade sobre o tipo — não tente inferir da estrutura interna. ::: :::warning Duas duplicações do template foram preservadas de propósito O template de produção repete palavras em dois pontos, e os exemplos reproduzem isso: - item 1.1 do Quadro V — `2,3100% % a.m. (dois inteiros e três mil e cem décimos de milésimo por cento por cento)`, com `%` e `por cento` duplicados; - item 2 do Quadro V — `2. Prazo: 91 dias dias corridos.` Não é erro destes arquivos. Mantivemos como está para o seu leitor encontrar em sandbox exatamente o texto que vai encontrar em produção — se você normalizar o texto antes de casar o padrão, esses dois campos são os que mais provavelmente quebram. Quando o template for corrigido, os exemplos são regerados. ::: :::note CPF e CNPJ destes PDFs têm dígito verificador válido Os documentos de exemplo do restante da documentação usam CPF e CNPJ de fachada, com dígito verificador **inválido** — `123.456.789-00`, `12.345.678/0001-99` e afins. Isso não incomoda quem só lê um payload de exemplo, mas reprovaria em qualquer validação de lastro que confira DV. Nestes PDFs os dígitos verificadores foram corrigidos, preservando os 12 primeiros dígitos: `123.456.789-09`, `12.345.678/0001-95`, `22.333.444/0001-81`. As chaves de acesso de NF-e e CT-e também têm DV correto e embutem o CNPJ do emitente já corrigido. Consequência: o `borrower_document` do `assignment_assets_wallet_composition` de exemplo difere do CPF impresso no PDF nos dois últimos dígitos. Se você está testando o cruzamento entre os dois arquivos, use `asset_external_id`, `asset_key`, número de contrato, valores e vencimentos — não o documento do sacado. ::: ## Roteiro ### 1. Crie a cessão ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment MÉTODO POST O `external_id` que você informar aqui é o mesmo que vai aparecer na coluna `assignment_external_id` do relatório e no nome do arquivo. Detalhes em [Criação da Cessão](/documentation/iaas/negociacao_recebiveis/assignment/criacao). ### 2. Insira o ativo ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset MÉTODO POST O payload depende do tipo de ativo da sua configuração de cessão — veja [Criação de Ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) para operação de crédito, ou as páginas de [duplicata](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata), [CT-e](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte) e [contrato descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract). Guarde o `external_id` do ativo: ele é a chave de junção com os outros relatórios. ### 3. Anexe o documento de exemplo Converta o PDF escolhido para Base64: ```bash base64 -w 0 ccb_exemplo_01.pdf > ccb_exemplo_01.b64 ``` ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}/document MÉTODO POST ```json title="Request Body" { "document_type": "ccb", "document_b64": "JVBERi0xLjcKJfCflqQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..." } ``` Os tipos aceitos em `document_type` são os que a **sua** configuração de cessão exige, não a lista completa de tipos existentes. Detalhes e erros possíveis em [Inserção de Documentos do Ativo](/documentation/iaas/negociacao_recebiveis/asset/documents). :::note Duplicatas mercantis podem não passar por aqui Para ativos do tipo `duplicata_mercantil`, a plataforma pode gerar a documentação automaticamente a partir dos dados da nota fiscal — nesse caso não há upload a fazer, e o lastro aparece no relatório sem você anexar nada. Isso **depende da configuração de cessão**: em algumas configurações a geração automática não acontece e o documento é esperado por upload. Confirme com o time de integração qual dos dois casos se aplica à sua antes de montar o teste. Independente disso, os PDFs de `duplicata_mercantil` e `invoice` deste pacote servem como referência de estrutura para o seu leitor. ::: ### 4. Encerre a inserção ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id} MÉTODO PUT ```json title="Request Body" { "assignment_status": "completed_assets_insertion" } ``` A partir daqui a cessão segue para a elegibilidade e para a aprovação — veja [Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento) e [Aprovação da cessão](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao). ### 5. Receba o arquivo O `assignment_documents` é gerado quando a cessão passa pela etapa de aprovação e gravado na pasta de SFTP configurada para o fundo, com o nome: ``` {nome_resumido_fundo}_assignment_documents_{external_id}_{AAAA-MM-DD}.csv ``` É o CSV com os links — os PDFs em si não são transferidos para o SFTP. Instruções de conexão e exemplos de download em [Integração SFTP](/documentation/iaas/integracao_sftp/inicio). :::danger O arquivo espera na pasta, os links não Este é o ponto de atenção mais importante da entrega por SFTP. A validade de 5 dias dos links começa a contar na **geração** do relatório, não na hora em que você busca o arquivo. O CSV continua na pasta indefinidamente, mas um arquivo coletado no sexto dia traz links que já não funcionam. Colete o arquivo assim que ele chegar, ou trate o erro de link expirado como sinal de que o relatório precisa ser gerado novamente — e não como falha do seu leitor. ::: :::warning Este relatório não emite o Webhook de Entrega O [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega) cobre as rotinas de relatório do fundo, e não as entregas geradas por cessão. Para o `assignment_documents` não há aviso de arquivo disponível. O sinal mais próximo é o [webhook de status do lote de cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). Em fluxos com aprovação manual, a passagem para `pending_consultant_approval` ou `pending_manager_approval` marca a entrada na etapa de aprovação, que é quando o relatório é gerado — use esse evento para agendar a coleta. Em fluxos com aprovação automática esses dois status não ocorrem, e o sinal utilizável é o status seguinte do lote no seu fluxo. Em ambos os casos o arquivo aparece na pasta em seguida, não no mesmo instante do webhook. ::: ## O que validar no seu leitor Três comportamentos do `document_url` que costumam quebrar implementações e que você consegue exercitar com o arquivo que acabou de receber: **Os links expiram em 5 dias.** São URLs pré-assinadas com `X-Amz-Expires=432000`, contados do momento da geração do relatório. Passado o prazo o link retorna erro e é preciso gerar o relatório novamente. O identificador estável do documento é o `document_key` — nunca a URL. Se você precisa arquivar o lastro, baixe os arquivos dentro da janela. **O arquivo chega sem nome útil e sem extensão.** O download vem com os headers: ```http Content-Disposition: attachment; filename="file" Content-Type: binary/octet-stream ``` Ou seja: o arquivo se chama `file`, sem extensão, e o content-type não identifica o formato. Não infira o tipo pelo nome nem pelo content-type — use a coluna `document_type` do CSV. O conteúdo é sempre PDF. **Um ativo pode ocupar mais de uma linha.** Quando o ativo tem mais de um documento, ele aparece repetido, com o mesmo `asset_key` e `document_type` diferente. Ativos sem documento anexado não aparecem, e ativos descartados (`discarded`) ou reprovados (`denied`) são excluídos do arquivo. :::caution `document_url` não é sempre uma URL Se a assinatura do link falhar no momento em que o relatório é gerado, a coluna vem preenchida com uma **mensagem de erro em texto**, não com uma URL — e o CSV é entregue normalmente, com as outras colunas íntegras. Trate `document_url` como campo não confiável: valide que o valor começa com `https://` antes de tentar baixar. Uma linha nessa condição significa que aquele documento precisa ser obtido em uma nova geração do relatório, não que o arquivo não exista. Um leitor que assuma "toda linha tem URL válida" quebra no primeiro caso desses. ::: ## Cruzando com a composição da cessão Para validação de lastro, o cruzamento mais útil é entre este relatório e a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), pelas colunas `asset_external_id` e `asset_key`. Ativo que aparece na composição e não aparece no lastro é ativo sem documento anexado. ## Um limite deste teste **Não existe um layout QI Tech DTVM por tipo de documento.** Os arquivos de lastro são os documentos originais do cedente ou do originador — a CCB emitida pelo originador, o DANFE gerado pelo ERP dele, o DACTE da transportadora. A DTVM armazena e valida esses arquivos, não os gera, e é por isso que a validação de cada tipo é configurada por template do nosso lado. :::note "QI Tech" não é o mesmo que "QI Tech DTVM" A distinção importa aqui. A QI Tech **emite** crédito por outras frentes — BaaS e LaaS — e essas emissões têm, sim, um layout próprio de CCB, que é o das CCBs de exemplo desta página. O que não existe é um layout definido pela **DTVM** para o lastro que ela recebe: quando o originador é a própria QI Tech, o documento segue o padrão daquela emissão; quando é outro originador, segue o padrão dele. Ou seja: a CCB de exemplo é *um* layout de lastro possível — o mais provável, se o seu originador emite pela QI Tech — e não *o* layout que a DTVM exige. ::: Consequência prática: o que você pode tratar como contrato estável é o CSV — colunas, tipos e semântica. O interior do PDF varia por originador. Se o seu fundo compra de mais de um originador, ou se o originador não emite pela QI Tech, teste também contra um arquivo real dele antes de fechar a implementação. Os outros cinco exemplos (duplicata, invoice, CT-e, contrato) reproduzem a estrutura típica de cada tipo, mas não vêm de um emissor específico — são referência de campos, não de layout. --- # Composição da Carteira URL: /documentation/iaas/relatorios_dtvm/wallet_composition ## Visão Geral O relatório `wallet_composition_by_composition` é a foto consolidada da carteira do fundo ao fim do dia. Ele reúne, em uma única planilha, o patrimônio e a cota de cada série de emissão, a posição por classe de ativo (títulos públicos, emissões, operações de crédito, direitos creditórios descontados, cotas de fundo, swaps e imóveis), os valores a pagar e a receber, os saldos de caixa e a rentabilidade das séries — sempre com o percentual que cada linha representa do patrimônio líquido. É o relatório usado por gestores e administradores para conferir o fechamento do dia: o somatório das seções de ativos, menos os valores a pagar e mais os valores a receber, reconcilia com o patrimônio líquido informado no cabeçalho. :::info Base do relatório O relatório é gerado a partir de uma **composição** de carteira já fechada — confirmada ou aguardando confirmação. Por padrão é usada a composição de cota de fechamento (`final_quota`); mediante configuração, também pode ser gerado sobre a composição de cota de abertura (`opening_quota`) ou pré-cota (`pre_quota`). ::: ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. | | `reference_date` | sim, se não informar `composition_key` | Data de referência, no formato `AAAA-MM-DD`. | | `composition_key` | alternativa à data | Identificador de uma composição específica. | | `composition_type` | não | `final_quota` (padrão), `opening_quota` ou `pre_quota`. Qualquer outro valor é recusado. | :::warning É preciso existir composição na data Se não houver composição do tipo pedido na data de referência, a solicitação é recusada com a mensagem "Não existe composition para esta 'reference_date'". ::: ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | XLSX | | Abas | `Sheet` (composição) e `P&L` (receitas e despesas do dia) | | Nomenclatura | `{nome_resumido_fundo}_wallet_composition_{AAAA-MM-DD}.xlsx` | :::note Nome do arquivo O modelo a ser solicitado é `wallet_composition_by_composition`, mas o arquivo entregue é nomeado `wallet_composition`, sem o sufixo. ::: Cada seção é apresentada com um título em negrito, uma linha de cabeçalho e, ao final, linhas de total por tipo de ativo e um total geral da seção — essas linhas de total aparecem em negrito e com fundo cinza. **Seções sem posição na data não são impressas**: um fundo que não tem imóveis, por exemplo, não terá a seção `IMÓVEIS`. :::tip Como conferir o fechamento Somando a coluna `% do PL` dos totais gerais de todas as seções — ativos, mais valores a receber, menos valores a pagar, mais caixa — o resultado é 100% do patrimônio líquido do cabeçalho. Uma diferença pequena pode aparecer quando o fundo tem **emissões com ágio ainda não diferido**: na seção `EMISSÕES` o `Valor D0 (R$)` é apurado pelo valor contábil do papel, enquanto nas demais classes ele considera o valor justo. O ágio a diferir, nesse caso, fica fora da soma das seções, mas está dentro do patrimônio líquido. ::: ## Aba `Sheet` ### Cabeçalho do fundo | Campo | Descrição | |-------|-----------| | Data de referência | Data da composição, no formato `AAAA-MM-DD`. | | Nome da classe de fundo | Nome completo da classe de fundo. | | CNPJ da classe de fundo | CNPJ da classe de fundo. | | Nome da gestora | Nome da gestora do fundo. | | CNPJ da gestora | CNPJ da gestora do fundo. | | Patrimônio bruto (R$) | Soma do patrimônio bruto de todas as séries de emissão. | | Patrimônio líquido (R$) | Soma do patrimônio líquido de todas as séries de emissão. É o denominador da coluna `% do PL` em todas as seções. | | Número de cotas | Soma das cotas de todas as séries de emissão. | ### `SÉRIES DE EMISSÃO` | Coluna | Descrição | |--------|-----------| | Nome | Nome da série de emissão. | | Patrimônio bruto (R$) | Patrimônio bruto da série, antes da provisão de taxa de performance. | | Cota bruta (R$) | Valor da cota bruta da série. | | Patrimônio líquido (R$) | Patrimônio líquido da série. | | Cota líquida (R$) | Valor da cota líquida da série. | | Número de cotas | Quantidade de cotas da série. | ### `TÍTULOS PÚBLICOS` Uma linha por título público em estoque (LFT, LTN, NTN-B e suas versões compromissadas). | Coluna | Descrição | |--------|-----------| | Data de referência | Data da composição. | | Identificador / Código SELIC | Código SELIC do título. | | Tipo do ativo | `LFT`, `LTN`, `NTN-B`, `LFT COMPROMISSADA`, etc. | | Emissor | `Tesouro Nacional`. | | Tipo de amortização | `No vencimento` ou `Juros semestrais`. | | Data de emissão / Data de compra / Data de vencimento | Datas do título e da aquisição. | | Unidades compradas / Unidades atuais | Quantidade de títulos adquirida e em estoque. | | PU de compra (R$) / PU D0 (R$) | Preço unitário de aquisição e preço unitário na data de referência. | | Valor de compra (R$) / Valor D0 (R$) | Valor financeiro de aquisição e valor na data de referência. | | % de Tesouros | Participação do título no total de títulos públicos. | | % do PL | Participação do título no patrimônio líquido do fundo. | ### `EMISSÕES` Uma linha por título privado ofertado (debênture, CRI, CRA, CDB, letra financeira). Notas comerciais são apresentadas em seção própria, com colunas equivalentes, em ordem própria. | Coluna | Descrição | |--------|-----------| | Data de referência | Data da composição. | | Identificador | Código externo do papel. | | Tipo do ativo | `DEBENTURE`, `CRI`, `CRA`, `CDB`, `Letra Financeira`, `NOTA COMERCIAL`. | | Código ISIN / Código B3 | Códigos de identificação do papel. | | Emissor | Nome do emissor. | | Data de emissão / Data de compra / Data de vencimento | Datas do papel e da aquisição. | | Unidades compradas / Unidades atuais | Quantidade adquirida e em estoque. | | PU de compra (R$) / PU do ativo (R$) / PU D0 (R$) | Preço unitário de aquisição, preço unitário contábil e preço unitário líquido de PDD. | | Valor de compra (R$) / Valor do ativo (R$) / Valor D0 (R$) | Valor de aquisição, valor contábil e valor líquido de PDD. | | PDD (R$) / PDD (%) | Provisão para devedores duvidosos, em reais (negativa) e em percentual. | | Valor vencido (R$) / Valor não vencido (R$) | Parcela vencida e não vencida do valor contábil. | | % de Emissões | Participação do papel no total de emissões. | | % do PL | Participação do papel no patrimônio líquido do fundo. | ### `OPERAÇÕES DE CRÉDITO` Operações de crédito (CCB, CCE, NCE e suas versões estruturadas). Para os tipos consolidados — `CCB`, `CCE`, `NCE` — a carteira é apresentada em **uma única linha por tipo**, identificada como `CCB CONSOLIDADO`, e não operação a operação; o detalhamento ativo a ativo está no relatório [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition). | Coluna | Descrição | |--------|-----------| | Data de referência | Data da composição. | | Identificador | Número do contrato da operação ou `{TIPO} CONSOLIDADO` nas linhas consolidadas. | | Tipo do ativo | `CCB`, `CCB ESTRUTURADA`, `CCE`, `NCE ESTRUTURADA`, etc. | | Código IF | Código do papel na B3, quando registrado. | | Data de emissão / Data de compra / Data de vencimento | Datas do contrato e da aquisição. Vazias nas linhas consolidadas. | | Unidades atuais | Quantidade de operações em estoque. | | PU de compra (R$) / PU em acruo (R$) / PU D0 (R$) | Preços unitários. Vazios nas linhas consolidadas. | | Valor D0 (R$) | Valor da posição líquido de PDD. | | PDD (R$) / PDD (%) | Provisão para devedores duvidosos. | | Valor do ativo (R$) | Valor contábil da posição. | | Valor vencido (R$) / Valor em acruo (R$) | Parcela vencida e parcela em acruo do valor contábil. | | Ágio restante (R$) | Ágio ainda não diferido (valor justo menos valor contábil). | | Juros pós-vencimento (R$) / Juros de mora (R$) / Multa por atraso (R$) | Encargos por atraso. **Estas três colunas só aparecem quando há algum encargo de atraso na carteira de CCB.** | | % de Operações de Crédito | Participação da linha no total de operações de crédito. | | % do PL | Participação da linha no patrimônio líquido do fundo. | ### `DC DESCONTADOS` Direitos creditórios descontados (duplicatas mercantis e de serviços, CT-e, contratos descontados). Sempre apresentados de forma consolidada, uma linha por tipo. | Coluna | Descrição | |--------|-----------| | Data de referência | Data da composição. | | Identificador | `{TIPO} CONSOLIDADO`. | | Tipo do ativo | `DUPLICATA MERCANTIL`, `DUPLICATA SERVIÇOS`, `CTE`, `CONTRATO`. | | Valor D0 (R$) | Valor da posição líquido de PDD. | | Valor do ativo (R$) | Valor contábil da posição. | | Valor vencido (R$) / Valor em acruo (R$) | Parcela vencida e parcela em acruo do valor contábil. | | PDD (R$) | Provisão para devedores duvidosos (negativa). | | % de Direitos Creditórios Descontados | Participação da linha no total de direitos creditórios descontados. | | % do PL | Participação da linha no patrimônio líquido do fundo. | ### `COTAS DE FUNDOS` | Coluna | Descrição | |--------|-----------| | Data de referência | Data da composição. | | Tipo do ativo | `FIDC`, `RENDA FIXA`, `MULTIMERCADO`, `FIA`, `FIP`, `FII`. | | Nome do Fundo / Documento do Fundo | Nome e CNPJ do fundo investido. | | Senioridade | `SÊNIOR`, `MEZANINO` ou `SUBORDINADA`. | | Código Interno | Código interno da classe investida. | | Data de compra | Sempre vazia nesta seção. | | Valor de compra (R$) / Unidades compradas / PU de compra (R$) | Dados da aquisição. | | Unidades atuais / Valor D0 (R$) / PU D0 (R$) | Posição na data de referência. | | % de Cotas | Participação da linha no total de cotas de fundos. | | % do PL | Participação da linha no patrimônio líquido do fundo. | ### `SWAP` e `IMÓVEIS` Apresentadas apenas para fundos que possuem esses ativos. `SWAP` traz contraparte, valores nominais e valores atualizados de ativo e passivo; `IMÓVEIS` traz número de matrícula, valor e data de avaliação e a próxima avaliação prevista. ### `VALORES A PAGAR` | Coluna | Descrição | |--------|-----------| | Data de referência | Data da composição. | | Tipo de a pagar | Descrição da despesa (ex: `TAXA DE ADMINISTRAÇÃO`). | | Total provisionado | Valor total provisionado da despesa. | | Valor reconhecido | Valor já reconhecido no resultado, apresentado como negativo. | | Valor restante | Diferença entre o total provisionado e o valor reconhecido. | | Inicio da provisão / Fim da provisão / Data do pagamento | Datas da provisão e do pagamento previsto. | | % do PL | Participação do valor reconhecido no patrimônio líquido (negativa). | ### `VALORES A RECEBER` Mesma estrutura da seção anterior, com as colunas `Total a diferir`, `Valor diferido`, `Valor restante`, `Inicio do diferimento` e `Fim do diferimento`. ### `CONTAS CAIXA` | Coluna | Descrição | |--------|-----------| | Data de referência | Data da composição. | | Nome da conta | Instituição financeira e identificação contábil da conta. | | Dados da conta | Agência e conta no formato `Ag.: {agência} \| Cc.: {conta}-{dígito}`. | | Entrada a conciliar / Saída a conciliar | Valores creditados ou debitados ainda não conciliados. | | Saldo | Saldo da conta na data de referência. | | % do PL | Participação do saldo no patrimônio líquido do fundo. | ### `RENTABILIDADE` Um bloco por série de emissão, com uma linha por janela de apuração. | Coluna | Descrição | |--------|-----------| | Tipo | `Diária`, `Mensal`, `Anual` ou `D-N` (janela de N dias corridos). | | Data de Referência | Data inicial da janela de apuração. | | Cota de Referência | Valor da cota na data inicial da janela. | | Cota Benchmark | Valor da cota do benchmark (DI) na data inicial da janela. | | Cota Atual | Valor da cota líquida na data da composição. | | Rendimento Total | Rentabilidade da cota na janela, em percentual. | | Rendimento (%CDI) | Rentabilidade como percentual do CDI. `-` quando não há benchmark na janela. | | Rendimento (CDI+) | Rentabilidade expressa como CDI mais spread anualizado (252 dias úteis). `-` quando o resultado é negativo ou não há benchmark. | ## Aba `P&L` Compara os saldos das contas de resultado (grupos contábeis `07` — receitas — e `08` — despesas) entre o dia útil anterior e a data de referência. ### `RESUMIDO` | Coluna | Descrição | |--------|-----------| | Data de Referência | Data da composição. | | Tipo | `Receitas`, `Despesas` ou `Resultado`. A classificação usa o **sinal do saldo final** de cada conta, não o grupo do plano de contas: uma conta de receita com saldo negativo entra em `Despesas`. | | Valor (R$) | Variação do dia. `Resultado` é a soma de receitas e despesas. | ### `DETALHES` | Coluna | Descrição | |--------|-----------| | Nome da Conta | Nome da conta contábil de resultado. | | Data Inicial / Valor Inicial (R$) | Dia útil anterior e saldo da conta nessa data. | | Data Final / Valor Final (R$) | Data de referência e saldo da conta nessa data. | | Resultado (R$) | Variação do saldo no dia. | | Variação (%) | Variação percentual em relação ao saldo inicial. | Somente contas com variação no dia aparecem na seção. --- # Webhook de Entrega URL: /documentation/iaas/relatorios_dtvm/webhook_de_entrega ## Visão Geral Sempre que uma entrega de relatórios é concluída, a QI CTVM pode notificar a sua aplicação por webhook. A notificação diz **qual entrega terminou, para qual destino, e quais arquivos ela levou** — com o status de cada relatório. É o sinal para você disparar a coleta no SFTP em vez de varrer a pasta em intervalos fixos. O webhook é **opcional** e configurado por rotina de entrega. Sem configuração, nenhuma notificação é enviada. :::info Como habilitar Informe ao time de integração a URL que vai receber as notificações. Devolvemos uma *Signature Key* para você validar a assinatura, e vinculamos a configuração à rotina de entrega do fundo. A habilitação é por rotina — um fundo com duas rotinas configura as duas. ::: ## Quando é enviado Uma notificação por **destino concluído**, no momento em que aquele destino termina de ser processado. Um destino só é processado depois que **todos** os relatórios da entrega chegam a um estado final — `generated` ou `failed`. Só então os arquivos são transferidos e a notificação sai. Ou seja: quando o webhook chega, a pasta já tem os arquivos. | Situação | Status do destino | Webhook | |----------|-------------------|---------| | Todos os relatórios gerados | `delivered` | enviado | | Parte dos relatórios falhou | `delivered` | enviado — os que falharam aparecem em `reports`, mas **não têm arquivo** na pasta | | Todos os relatórios falharam | `failed` | enviado — nenhum arquivo é transferido | :::warning É um webhook por destino, não por arquivo Uma rotina que entrega oito relatórios em uma pasta SFTP gera **uma** notificação, com oito entradas em `reports`. Não há uma notificação por arquivo. Se a mesma entrega tem dois destinos — por exemplo uma pasta SFTP e um e-mail — são **duas** notificações, uma por destino, e as duas trazem a mesma lista de `reports`. ::: :::info Cada destino é notificado uma única vez A notificação de um destino é registrada quando é enviada e não se repete. Um reprocessamento do envio não gera notificação nova. Para reenviar uma notificação já emitida, veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ::: ## Tipos de webhook | `webhook_type` | Quando | |----------------|--------| | `report.recurring_delivery_destination_completed` | Entrega originada de uma **rotina** — o caso da entrega diária de relatórios do fundo. | | `report.delivery_destination_completed` | Entrega **avulsa**, criada fora da rotina. | A diferença de payload está em `data`: o tipo de rotina acrescenta `recurring_delivery_key` e `description`. ## Estrutura do webhook ```json title="Webhook Body — rotina, destino SFTP" { "webhook_type": "report.recurring_delivery_destination_completed", "webhook_datetime": "2026-07-30T09:12:44Z", "data": { "solicitation_time": "2026-07-30T09:05:00Z", "delivery_key": "3f1c9b7e-0a44-4c21-9f18-6b2d5e7a1c33", "recurring_delivery_key": "b8d2a6f4-77c1-4e90-8a3b-1d5f9c0e2a77", "description": "Relatórios diários — FUNDO EXEMPLO FIDC", "destination": { "destination_key": "c4e7a1b9-2d63-4f85-90ab-7c1e3f5d8b02", "destination_type": "sftp", "folder_path": "/fundos/fundo_exemplo", "status": "delivered" }, "reports": [ { "report_type": "consolidated_credit_rights_acquisition_assets", "file_name": "example_name_consolidated_credit_rights_acquisition_assets_2026-07-29.csv", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "reference_date": "2026-07-29", "status": "generated" }, { "report_type": "cash_account_demonstrative", "file_name": "example_name_cash_account_demonstrative_2026-07-29.xlsx", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860", "reference_date": "2026-07-29", "status": "generated" } ] } } ``` ### Atributos de `data` | Campo | Tipo | Descrição | |-------|------|-----------| | `solicitation_time` | string | Data e hora em que a entrega foi solicitada, em ISO 8601 (UTC). | | `delivery_key` | string | Identificador da entrega (UUID). Único por execução da rotina. | | `recurring_delivery_key` | string | Identificador da rotina. **Presente apenas** em `report.recurring_delivery_destination_completed` — é estável entre execuções e serve para identificar de qual rotina veio a entrega. | | `description` | string | Descrição cadastrada na rotina. **Presente apenas** em `report.recurring_delivery_destination_completed`. | | `destination` | object | Destino concluído. Veja **[Atributos de `destination`](#atributos-de-destination)**. | | `reports` | array | Relatórios da entrega. Veja **[Atributos de `reports`](#atributos-de-reports)**. | ### Atributos de `destination` | Campo | Tipo | Descrição | |-------|------|-----------| | `destination_key` | string | Identificador do destino (UUID). É a chave desta notificação: um `destination_key` é notificado uma única vez. | | `destination_type` | string (enum) | `sftp` ou `email`. | | `status` | string (enum) | `delivered` ou `failed`. Veja a tabela de [quando é enviado](#quando-é-enviado). | | `folder_path` | string | Pasta de destino no SFTP. **Presente apenas** quando `destination_type` é `sftp`. | | `recipients` | array | Destinatários do e-mail. **Presente apenas** quando `destination_type` é `email`. | | `title` | string | Assunto do e-mail. **Presente apenas** quando `destination_type` é `email`. | Os arquivos são gravados em `folder_path` com exatamente o `file_name` de cada relatório — o caminho completo é `{folder_path}/{file_name}`. ### Atributos de `reports` | Campo | Tipo | Descrição | |-------|------|-----------| | `report_type` | string (enum) | Modelo do relatório, conforme a coluna "Modelo" da [lista de relatórios disponíveis](/documentation/iaas/relatorios_dtvm/). | | `file_name` | string | Nome do arquivo entregue, já com o prefixo do fundo e a data. | | `fund_class_key` | string | Classe de fundo do relatório. | | `reference_date` | string | Data de referência, em `AAAA-MM-DD`. **Pode vir nulo** nos relatórios gerados por intervalo (`quota_mec`, `balance_report`, `accounting_ledger`), que são parametrizados por `start_date` e `end_date` em vez de uma data única — trate o campo como opcional e use `file_name` para identificar o arquivo. | | `status` | string (enum) | `generated` ou `failed`. | :::danger Confira o `status` de cada relatório Um webhook recebido **não** significa que todos os arquivos estão na pasta. Relatórios com `status: "failed"` aparecem na lista e não têm arquivo correspondente. Um leitor que itere `reports` e tente baixar tudo vai falhar no primeiro relatório com erro. Filtre por `status == "generated"` antes de montar a lista de arquivos a coletar, e trate a presença de `failed` como alerta operacional — não como ausência de entrega. ::: ## Autenticação e reenvio A validação da assinatura, a lista de IPs de origem, a política de tentativas e o reenvio são iguais aos dos demais webhooks da QI CTVM — veja **[Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks)**. ## Onde não há webhook Duas entregas de relatório **não** emitem esta notificação: - **Relatórios de cessão** — o [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) e a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) são gerados na etapa de aprovação da cessão, e não na rotina do fundo. Para esses dois, o acompanhamento é pelo [webhook de status do lote de cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) e pela coleta na pasta. - **Download sob demanda da carteira** — a rota de [Baixar a Carteira](/documentation/iaas/composicao_carteira/baixar_carteira) é síncrona e devolve o arquivo na própria resposta, em base64. Não passa por entrega, destino, nem webhook. :::caution Atenção ao lastro da cessão O `assignment_documents` é justamente o relatório em que o aviso de chegada faria mais diferença, porque os links de download dentro dele expiram em 5 dias contados da **geração**. Como ele não emite webhook, a orientação de coleta continua sendo a do roteiro de [Testando a Captura de Lastro](/documentation/iaas/relatorios_dtvm/testar_captura_lastro). ::: --- # XML ANBIMA (tipos 5 e 401) URL: /documentation/iaas/relatorios_dtvm/xml_anbima ## Visão Geral A QI CTVM gera os arquivos de posição de carteira no padrão ANBIMA a partir da composição de carteira do fundo. São dois modelos, entregues como arquivos independentes: | Modelo | Padrão | Descrição | |--------|--------|-----------| | `xml_5_by_composition` | Arquivo de Posição ANBIMA 5.0 (ISO 20022, `semt.003.001.04`) | Posição da carteira em estrutura ISO 20022, com identificação de administrador, gestor e custodiante, posição por ativo, valores a pagar e a receber. | | `xml_401_by_composition` | Arquivo de Posição ANBIMA 4.01 | Posição da carteira no layout 4.01, com cabeçalho do fundo e blocos por classe de ativo. | :::info Qual é o "XML da ANBIMA" Quando se fala do XML da ANBIMA no dia a dia, o arquivo em questão é o **`xml_5_by_composition`** — a versão 5.0 do arquivo de posição. O `xml_401_by_composition` é a versão anterior do mesmo padrão, ainda exigida por alguns consumidores. ::: ## O que você precisa informar | Variável | Obrigatória | Descrição | |----------|-------------|-----------| | `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o arquivo é gerado. | | `reference_date` | sim | Data de referência da posição, no formato `AAAA-MM-DD`. | | `type_fund_code_anbima` | não | Código do tipo de fundo na tabela da ANBIMA. Quando omitido, é derivado do cadastro do fundo. Um código fora da lista de válidos faz a geração falhar. | | `issuance_serie_key` | não (só XML 401) | Restringe o arquivo a uma única série de emissão. Sem ele, todas as séries da classe entram no arquivo. | ## Estrutura do Arquivo | Atributo | Valor | |----------|-------| | Formato | XML | | Encoding | UTF-8 | | Nomenclatura | `{nome_resumido_fundo}_xml_5_by_composition_{AAAA-MM-DD}.xml` e `{nome_resumido_fundo}_xml_401_by_composition_{AAAA-MM-DD}.xml` | Ambos os arquivos são gerados a partir de uma **composição de carteira** já fechada na data de referência — confirmada ou aguardando confirmação. Antes de montar o arquivo, o serviço reconcilia a posição: a soma dos ativos, mais os valores a receber, menos os valores a pagar, tem que fechar com o patrimônio líquido informado pelas séries de emissão. Quando não fecha, o arquivo não é gerado. ## Como receber Há duas formas, que podem ser usadas em conjunto: 1. **Na rotina de entrega do fundo**, junto com os demais relatórios — veja [como os relatórios são entregues](/documentation/iaas/relatorios_dtvm/). Basta solicitar ao time de integração a inclusão dos modelos `xml_5_by_composition` e/ou `xml_401_by_composition` na configuração da entrega. 2. **Sob demanda, pela API**, com a rota de download de relatório da composição: ENDPOINT /composition/fund_class/{fund_class_key}/report MÉTODO POST ```json title="Request Body" { "composition_type": "final_quota", "report_type": "xml_5_by_composition", "reference_date": "2026-07-29" } ``` A resposta devolve o arquivo em base64, no campo `document_b64`. A carteira precisa estar no status **confirmed** para o download ser possível. Detalhes em [Carteira - Baixar a Carteira](/documentation/iaas/composicao_carteira/baixar_carteira). ## Conteúdo do arquivo tipo 5 O arquivo tem o elemento raiz `PosicaoAtivosCarteira` e é dividido em duas partes: - **`AppHdr`** — cabeçalho da mensagem: administrador remetente (nome e CNPJ), fundo destinatário, identificador da mensagem, versão do layout (`semt.003.001.04`), serviço (`Arquivo de Posicao 5.0`) e data/hora de geração. - **`Document / SctiesBalAcctgRpt`** — corpo da posição: | Elemento | Conteúdo | |----------|----------| | `Pgntn` | Paginação do arquivo. | | `StmtGnlDtls` | Dados gerais do extrato: data da composição, frequência e tipo de atualização. | | `AcctOwnr` | CNPJ do administrador (titular da conta). | | `AcctSvcr` | CNPJ da gestora. | | `SfkpgAcct` | CNPJ e nome do custodiante. | | `BalForAcct` | Classe de fundo e séries de emissão, com ISIN, quantidade de cotas, valor da cota, valor total dos ativos, e o detalhamento de valores a pagar (`PAYA`) e a receber (`RECE`). | | `SubAcctDtls` | Uma entrada por ativo da carteira: títulos públicos, títulos privados, debêntures, cotas de fundo, direitos creditórios, swaps, imóveis e contas caixa. | | `AcctBaseCcyTtlAmts` | Patrimônio líquido total do fundo. | Os valores a pagar são classificados com os códigos ISO correspondentes à natureza da despesa — `ADMF` (taxa de administração), `MANF` (gestão), `PERF` (performance), `CETI` (CETIP), `REGF` (CVM), `ANBI` (ANBIMA), `AUDT` (auditoria), `SELC` (SELIC), `CUST` (custódia), `LEGA` (serviços) — ou `OTHR` para os demais. ## Conteúdo do arquivo tipo 401 O arquivo tem o elemento raiz `arquivoposicao_4_01`, com um elemento `fundo` que reúne: | Bloco | Conteúdo | |-------|----------| | `header` | ISIN, CNPJ e nome do fundo, data da posição, administrador, gestor e custodiante, valor e quantidade de cotas, patrimônio líquido, valor dos ativos, valores a receber e a pagar, tipo de fundo ANBIMA. | | `titpublico` | Um bloco por título público, com código SELIC, datas, quantidades, PUs, indexador e valor financeiro. | | `titprivado` | Um bloco por título privado que não seja debênture. | | `debenture` | Um bloco por debênture. | | `swap` | Um bloco por contrato de swap, com valores de ativo e passivo. | | `cotas` | Um bloco por cota de fundo investida, com ISIN, CNPJ do fundo, quantidade e PU. | | `caixa` | Saldo das contas caixa. | | `despesas` | Taxas de administração e performance do fundo. | | `outrasdespesas` | Demais despesas provisionadas. | | `provisao` | Provisões constituídas, com data e valor. | | `fidc` | Valor financeiro total dos direitos creditórios da carteira. | Blocos sem posição na data não são incluídos no arquivo. --- # Criação de um ativo a ser recomprado/vendido URL: /documentation/iaas/venda_ativos/asset/criacao_recompra --- ### Request ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/EXTERNAL_ID/asset MÉTODO POST ```json title='Request Body' { "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "sale_value": 1234.56 } ``` :::info O external_id informado na payload deve corresponder ao external_id de um ativo que está presente na carteira do fundo. ::: #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `external_id` * | string | Chave única de identificação do ativo a ser recomprado/vendido informada pelo parceiro. | Até 50 | | `sale_value` *| float | Valor pelo qual o ativo será baixado | 2 casas decimais | ### Response STATUS 201 ```json title='Response Body' { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "pending_assets_insertion", } ``` --- # Criação de um lote de recompra URL: /documentation/iaas/venda_ativos/assignment/criacao_recompra --- ### Request ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment MÉTODO POST ```json title='Request Body' { "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "assignment_date": "2024-04-01", "assignment_configuration_key": "d9308a2b-21fa-4724-9bbe-59ae65287b10", "source_account":{ "document_number": "95.031.521/0001-12" } } ``` #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `external_id` * | string | Chave única de identificação deste lote no sistema do parceiro integrador. | Até 50 | | `assignment_date` *| string | Data da recompra | YYYY-MM-DD | | `assignment_configuration_key` *| string | Chave única fornecida pela CTVM | 36 | | `source_account` *| objeto | Objeto da conta que irá realizar o pagamento ao fundo | - | ### Objeto de source account | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `document_number` * | string | Número do documento da conta que irá realizar o pagamento ao fundo. | Até 18 | ### Response STATUS 201 ```json title='Response Body' { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "pending_assets_insertion", } ``` --- # Encerrar Inserção de Ativos URL: /documentation/iaas/venda_ativos/assignment/fechamento_recompra ### Request ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/EXTERNAL_ID MÉTODO PUT ```json title='Request Body' { "assignment_status": "completed_assets_insertion" } ``` ### Response STATUS 201 ```json title='Response Body' { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "completed_assets_insertion", } ``` --- # Recompra e Venda de Ativos URL: /documentation/iaas/venda_ativos/inicio Esta seção documenta as APIs que viabilizam a **venda e a recompra de direitos creditórios** já encarteirados nos fundos administrados pela QI CTVM. O fluxo abrange desde a criação do lote até a baixa dos ativos da carteira do fundo. :::tip Contexto Este serviço apenas **baixa os ativos da carteira** do fundo. Ele não envia dados para outras administradoras. Existem dois conceitos fundamentais: o **lote** (`assignment`) e o **ativo** (`asset`). Um lote é composto por um ou mais ativos, e cada ativo inserido precisa já estar na carteira do fundo. ::: :::info Pré-requisitos - Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de Homologação (Sandbox) e Produção. - Você precisará da `fund_class_key` (chave do fundo), que compõe a URL base de todos os endpoints desta API, e da `assignment_configuration_key` (chave da configuração), informada na criação do lote: ``` /trade_resolve/fund_class/{fund_class_key} ``` ::: ## Fluxo de venda/recompra O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação. 5%', dashed: true }, { from: 'validacao', to: 'encerramento', label: 'confirmado', dashed: true }, { from: 'ativos', to: 'encerramento' }, { from: 'encerramento', to: 'descartado', label: 'discarded', tone: 'end' }, { from: 'encerramento', to: 'termo', label: 'encerrado', tone: 'ok' }, { from: 'termo', to: 'credito', label: 'assinado' }, { from: 'credito', to: 'baixa', label: 'pago' }, ]} /> ## Passo a passo ### 1. Criação do Lote Crie o lote informando um identificador único (`external_id`), a data da operação e a conta que fará o pagamento ao fundo. O lote nasce em `pending_assets_insertion` e é o contêiner de todos os ativos que serão baixados. **[Acessar documentação da criação do lote](/documentation/iaas/venda_ativos/assignment/criacao_recompra)** ### 2. Inserção dos Ativos Insira um ativo por requisição, identificando-o pelo mesmo `external_id` com que ele foi encarteirado. O ativo precisa estar **ativo** na carteira do fundo no momento da inserção. **[Acessar documentação da inserção de ativos](/documentation/iaas/venda_ativos/asset/criacao_recompra)** :::caution Divergência de preço acima de 5% Se o preço de venda informado divergir em **mais de 5%** do valor justo contábil do ativo, o ativo não segue automaticamente: ele fica em `pending_validation` e exige uma confirmação explícita do integrador antes de entrar na baixa. Divergências de até 5% seguem direto para `pending_wallet_sale`. O endpoint de confirmação ainda não está documentado nesta seção — se o seu fluxo pode gerar divergências acima de 5%, alinhe o procedimento com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). ::: ### 3. Encerramento do Lote Após inserir todos os ativos, encerre o lote. É necessário ter ao menos um ativo não descartado. Opcionalmente, você pode enviar `number_of_assets` e `total_value` para que a API confira a quantidade e o valor total consolidados antes de aceitar o encerramento. O descarte do lote está disponível **até esta etapa**: depois que o termo entra em circulação, o lote não pode mais ser descartado. **[Acessar documentação do encerramento](/documentation/iaas/venda_ativos/assignment/fechamento_recompra)** ### 4. Termo de Recompra O responsável pela emissão do Termo de Recompra depende da configuração do lote: - **Termo interno** — a QI Tech gera o termo e coleta as assinaturas das partes. Nenhuma ação do integrador é necessária. - **Termo externo** — o lote passa para `pending_signed_term_submission` e o integrador precisa enviar o termo já assinado para que o fluxo prossiga. Em ambos os casos, com o termo assinado o lote passa a `pending_payment`, aguardando o crédito na conta do fundo. ### 5. Pagamento e Baixa dos Ativos As etapas finais são automatizadas: a QI Tech confirma o crédito na conta do fundo, os ativos são baixados da carteira e, quando todos os ativos são concluídos, o lote é encerrado em `completed`. --- # Recuperando Informações da Conta URL: /documentation/iaas/visibildade_de_caixa/get_accounts --- ### Request ENDPOINT /cash_account/fund_class/FUND_CLASS_KEY/accounts MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { { "data":[ { "account_key":"fdbe66e9-4b1d-4254-8473-523b8d3587be", "account_type":"checking_account", "financial_institution":{ "ispb":"32402502", "code":"329", "name":"QI Sociedade de Crédito Direto" }, "account_status":"open", "account_number":"999999", "account_digit":"9", "account_branch":"0001", "accounting_identification":1, "balance":0, "owner":{ "name":"FUNDO DE INVESTIMENTO EM DIREITOS CREDITORIOS", "document_number":"16.958.441/0001-30" }, "owner_document_number":"16.958.441/0001-30" }, { "account_key":"e40dd24e-4341-4736-a868-f3e767dd6c31", "account_type":"checking_account", "financial_institution":{ "ispb":"32402502", "code":"329", "name":"QI Sociedade de Crédito Direto" }, "account_status":"open", "account_number":"77777", "account_digit":"7", "account_branch":"0001", "accounting_identification":2, "balance":0, "owner":{ "name":"FUNDO DE INVESTIMENTO EM DIREITOS CREDITORIOS", "document_number":"16.958.441/0001-30" }, "owner_document_number":"16.958.441/0001-30" } ], "limit":10, "page":0, "is_last_page":true } } ``` ### Response Fields | Campo | Tipo | Descrição | |---------------|--------|--------------------------------------------------------| | `data` | array | Lista de objetos de **[Account](#account)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última| ### Account | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|------------------------------------------------|------------| | `account_key` | string | Chave única identificadora da conta no sistema | 36 | | `account_type` | string | Tipo de conta | Até 50 | | `financial_institution` | JSON | Objeto de instituição financeira | - | | `account_status` | string | Status da conta | Até 50 | | `account_number` | string | Número da conta | Até 50 | | `account_digit` | string | Digito da conta | 1 | | `account_branch` | string | Agência da conta | Até 50 | | `accounting_identification` | int | Identificador ordinal da conta | - | | `balance` | int | Saldo da conta no momento | - | | `owner` | JSON | Objeto de proprietário | - | | `owner_document_number` | string | Documento do proprietário | 14 ou 18 | :::caution **Atenção** O saldo é disponibilizado concatenando reais e centavos ex.: 1234 = R$ 12,34 ::: ### Finacial institution | Campo | Tipo | Descrição | Caracteres | |--------|--------|--------------------------------------------------|------------| | `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro| 8 | | `code` | string | Código da instituição financeira | 3 | | `name` | string | Nome da instituição financeira | Até 255 | ### Owner | Campo | Tipo | Descrição | Caracteres | |-------------------|--------|---------------------------|------------| | `name` | string | Nome do proprietário | até 255 | | `document_number` | string | Documento do proprietário | 14 ou 18 | --- # Recuperando Transações de uma Conta URL: /documentation/iaas/visibildade_de_caixa/get_transactions --- ### Request ENDPOINT /cash_account/account/ACCOUNT_KEY/transactions MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { "data": [ { "transaction_key": "ed585534-8c05-431d-b829-0dc7883b24ba", "transaction_type": "outgoing_wire_transfer", "transaction_status": "pending_conciliation", "transaction_description": "Descrição do pagamento", "amount": -70000, "transaction_datetime": "2025-01-01T14:00:00Z", "account_balance": 500000, "transaction_data": { "counter_part_account": { "owner": { "name": "Nome da Contraparte", "document_number": "***.805.49*-**" }, "account_digit": "8", "account_branch": "1", "account_number": "1234567", "financial_institution": { "code": "329", "ispb": "32402502" } }, }, "account": { "account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44", "account_type": "checking_account", "financial_institution": { "ispb": "32402502", "code": "329", "name": "QI Sociedade de Crédito Direto" }, "account_status": "open", "account_number": "3289018", "account_digit": "7", "account_branch": "0001", "accounting_identification": 1, "balance": 500000, "owner": { "name": "FUNDO TESTE", "document_number": "93.625.214/0001-34" }, "owner_document_number": "93.625.214/0001-34", "account_configuration": { "pix": true, "wire_transfer": true }, "billings": [] } }, { "transaction_key": "16c9c463-266e-4e73-b87d-efc32aa6727a", "transaction_type": "incoming_wire_transfer", "transaction_status": "reconciled", "transaction_description": "Descrição", "amount": 300000, "transaction_datetime": "2025-06-04T13:00:00Z", "account_balance": 570000, "transaction_data": { "counter_part_account": { "owner": { "name": "FUNDO TESTE", "document_number": "93.625.214/0001-34" }, "account_digit": "8", "account_branch": "73", "account_number": "567567", "financial_institution": { "code": "341", "ispb": "60701190", } }, }, "account": { "account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44", "account_type": "checking_account", "financial_institution": { "ispb": "32402502", "code": "329", "name": "QI Sociedade de Crédito Direto" }, "account_status": "open", "account_number": "3289018", "account_digit": "7", "account_branch": "0001", "accounting_identification": 1, "balance": 500000, "owner": { "name": "FUNDO TESTE", "document_number": "93.625.214/0001-34" }, "owner_document_number": "93.625.214/0001-34", "account_configuration": { "pix": true, "wire_transfer": true }, "billings": [] }, "conciliation_group": { "description": "TRANSFERÊNCIA: CONTA COBRANÇA -> CONTA PRINCIPAL", "conciliation_group_key": "1ac2921c-6c81-481b-8472-6c4126bba4bf", "conciliation_group_datetime": "2025-01-01T13:28:58Z" } } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Query Params | Campo | Tipo | Descrição | |---------------|--------|----------------------------| | `status` | string | Status da transação | | `start_date` | string | Data inicial de consulta | | `end_date` | string | Data final de consulta | | `page` | string | Número da página recuperada| ### Response Fields | Campo | Tipo | Descrição | |---------------|--------|--------------------------------------------------------| | `data` | array | Lista de objetos de **[Transaction](#transaction)** | | `limit` | int | Limite de objetos recuperados por página | | `page` | int | Número da página recuperada | | `is_last_page`| boolean| Informação que indica se a página recuperada é a última| ### Transaction | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|---------------------------------------------------|------------| | `transaction_key` | string | Chave única identificadora da transação | 36 | | `transaction_type` | string | Tipo de transação | Até 50 | | `transaction_status` | string | status da transação | Até 50 | | `transaction_description` | string | Descrição da transação fornecida pelo banco | Até 255 | | `amount` | bigint | Valor da transação vezes 100 (ex: R$1,00 == 100) | - | | `transaction_datetime` | string | Data e hora da transação | ISO 8601 | | `account_balance` | bigint | Saldo da conta após a transação | - | | `transaction_data` | JSON | Objeto com informações adicionais da transação | - | | `account` | JSON | Objeto da conta contendo a transação | - | ### Account | Campo | Tipo | Descrição | Caracteres | |-----------------------------|--------|-------------------------------------|------------| | `account_key` | string | Chave única identificadora da conta | 36 | | `account_type` | string | Tipo de conta | Até 50 | | `financial_institution` | JSON | Objeto de instituição financeira | - | | `account_status` | string | Status da conta | Até 50 | | `account_number` | string | Número da conta | Até 50 | | `account_digit` | string | Digito da conta | 1 | | `account_branch` | string | Agência da conta | Até 50 | | `accounting_identification` | int | Identificador ordinal da conta | - | | `balance` | int | Saldo da conta no momento | - | | `owner` | JSON | Objeto de proprietário | - | | `owner_document_number` | string | Documento do proprietário | 14 ou 18 | :::caution **Atenção** O saldo é disponibilizado concatenando reais e centavos ex.: 1234 = R$ 12,34 ::: ### Finacial institution | Campo | Tipo | Descrição | Caracteres | |--------|--------|---------------------------------------------------|------------| | `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro | 8 | | `code` | string | Código da instituição financeira | 3 | | `name` | string | Nome da instituição financeira | Até 255 | ### Owner | Campo | Tipo | Descrição | Caracteres | |-------------------|--------|---------------------------|------------| | `name` | string | Nome do proprietário | até 255 | | `document_number` | string | Documento do proprietário | 14 ou 18 | ### Conciliation Group | Campo | Tipo | Descrição | Caracteres | |-------------------------------|--------|------------------------------------------|------------| | `description` | string | Descrição da conciliação da transação | Até 255 | | `conciliation_group_key` | string | Chave única identificadora da conciliação| 36 | | `conciliation_group_datetime` | string | data e horário da conciliação | ISO 8601 | --- # Introdução URL: /documentation/iaas/visibildade_de_caixa/inicio A visibilidade das movimentações de caixa é extremamente importante para a gestão de um fundo de investimento. Nesta seção iremos explicar as ferramentas disponibilizadas para consultar as informações de contas. Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox), quanto em ambiente produtivo. ### Informações de conta Nessa ferramenta é possível resgatar uma lista de informações das contas de um fundo, conforme descrito em: [5.7.2.1 Recuperando Informações da Conta](/documentation/iaas/visibildade_de_caixa/get_accounts). --- # Transferência entre contas do fundo URL: /documentation/iaas/visibildade_de_caixa/post_internal_transfer Esse recurso permite realizar uma transferência de valores entre duas contas pertencentes ao mesmo fundo, debitando a conta de origem e creditando a conta de destino. --- ### Request ENDPOINT /transfer/fund_class/FUND_CLASS_KEY/internal_transfer MÉTODO POST ```json title='Request Body' { "amount": 15000, "description": "Internal transfer", "origin_key": "", "origin_type": "manual_transfer", "source_account_key": "", "target_account_key": "", "transfer_type": "pix" } ``` ### Response STATUS 201 ```json title='Response Body' { "internal_transfer_key": "", "internal_transfer_status": "created" } ``` ### Path Params | Campo | Tipo | Descrição | |------------------|--------|------------------------------------------------| | `fund_class_key` | string | Chave única identificadora do fundo na QI CTVM | ### Body Params | Campo | Tipo | Descrição | |-----------------------|--------|------------------------------------------------------------------------------------------------------------------| | `amount` | int | Valor a ser transferido, em centavos (ex.: `15000` = R$ 150,00) | | `description` | string | Descrição da transferência | | `origin_key` | string | Chave única de idempotência da transferência (UUID v4), gerada pelo integrador a cada solicitação | | `origin_type` | string | Tipo de origem da transferência. Deve ser enviado como `manual_transfer` | | `source_account_key` | string | Chave única identificadora da conta a ser debitada (origem) | | `target_account_key` | string | Chave única identificadora da conta a ser creditada (destino) | | `transfer_type` | string | Tipo de transferência. Aceita `pix` ou `wire_transfer`, limitado ao que a conta de origem suporta | :::caution **Atenção** Para receber o resultado da transferência, é necessário a configuração do webhook de confirmação da transferência. ::: --- # Criando Pedido de Estorno URL: /documentation/iaas/visibildade_de_caixa/post_transaction_reversal --- ### Request ENDPOINT /transaction_reversal/fund_class/FUND_CLASS_KEY/transaction_reversal MÉTODO POST ### Response STATUS 201 ```json title='Response Body' { "amount": 125.25, "description": "Estorno - transferência indevida", "reversal_type": "pix", "reference_date": "2025-01-01", "source_account": { "owner": { "name": "Nome do Fundo", "document_number": "123.805.491-24" }, "account_digit": "8", "account_branch": "0001", "account_number": "1234567", "financial_institution": { "ispb": "32402502", "code": "329", "name": "QI Sociedade de Crédito Direto" }, }, "transaction_key": "4208d7d1-9077-4d00-aa4a-a4368b954867" } ``` ### Path Params | Campo | Tipo | Descrição | |-----------------|--------|------------------------------------------------| | `fund_class_key`| string | Chave única identificadora do fundo na QI CTVM | ### Body Params | Campo | Tipo | Descrição | |----------------------------------|-------------------------|----------------------------------------------------------------------------| | `amount`* | float | Valor a ser estornado | | `description`* | string | Descrição do estorno realizado | | `reversal_type`* | string | Tipo de estorno a ser enviado | | `reference_date`* | string | Data de referência para o processamento do estorno | | `source_account_key` | int | Chave única identificadora da conta de origem do estorno | | `source_account` | **[Account](#account)** | Objeto de conta de origem do estorno | | `transaction_key`* | string | Chave única identificadora da transferência a estornar no sistema de caixa | | `reference_key` | string | Chave de referencia da transferência a estornar no banco de origem | | `conciliation_field` | string | Campo para conciliação em múltiplas expectativas | | `end_to_end_id` | string | Identificador do pix a estornar | | `external_key` | string | Chave única da transação a estornar no banco de origem | | `bank_slip_settlement_group_key` | string | Chave única da liquidação de boleto a estornar no banco de origem | :::caution **Atenção** O Campos `source_account_key` e `source_account` são campos identificadores da origem do valor a ser estornado. Devem ser enviados **1 campo de cada**, caso sejam enviados múltiplos, retornará erro 400. ::: ### Account | Campo | Tipo | Descrição | Caracteres | |-----------------------------|---------------------------------------------------|-------------------------------------|------------| | `account_number` | string | Número da conta | Até 50 | | `account_digit` | string | Digito da conta | 1 | | `account_branch` | string | Agência da conta | Até 4 | | `financial_institution` | **[Financial Institution](#financial_institution)** | Objeto de instituição financeira | - | | `owner` | **[Owner](#owner)** | Objeto de proprietário | - | ### Financial institution {#financial_institution} | Campo | Tipo | Descrição | Caracteres | |--------|--------|---------------------------------------------------|------------| | `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro | 8 | | `code` | string | Código da instituição financeira | 3 | | `name` | string | Nome da instituição financeira | Até 255 | ### Owner | Campo | Tipo | Descrição | Caracteres | |-------------------|--------|---------------------------|------------| | `name` | string | Nome do proprietário | até 255 | | `document_number` | string | Documento do proprietário | 14 ou 18 | --- # Webhooks URL: /documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal --- #### Liquidação concluida STATUS Settled ```json title='Webhook Body' { "data":{ "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1", "amount": 123.45, "status": "paid", "description": "Valor de liquidação indevido", "reference_date": "2025-03-23", "fund_class_document_number": "12.345.678/0009-10", "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487", "source_account": { "account_digit": "7", "account_branch": "0001", "account_number": "0099999", "owner": { "name": "FUNDO DE INVESTIMENTO", "document_number": "12.345.678/0009-10" }, "financial_institution": { "code": "329", "ispb": "32402502", "name": "QI Sociedade de Crédito Direto" }, }, "target_account":{ "owner": { "name": "Nome fictício", "document_number": "111.202.188-99" }, "account_digit": "0", "account_branch": "0001", "account_number": "1029490", "target_pix_key": "1232221", "financial_institution": { "code": "033", "ispb": "90400888", "name": "BCO SANTANDER (BRASIL) S.A." } }, "external_key":"40054daa-c3c5-49cd-add7-858b576c5887" }, "webhook_type":"transaction_reversal.transaction_reversal_status_change", "webhook_datetime":"2025-03-23T15:08:30Z" } ```