# 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 410 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) - Consulta de documentos (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/consultar-documento) - 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) - Consulta de templates disponíveis (/documentation/escrituracao/emissao-de-notas/geracao-minutas/consulta-minutas-disponiveis) - 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) - Entrega e Reenvio de Webhooks (/documentation/escrituracao/entrega-webhooks) - 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) - Consulta do Termo de Adesão Assinado (/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-termo-assinado) - 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) - Retentativa de Abertura de Conta de Liquidação (/documentation/escrituracao/integralizacao-cotas/retentativa-conta-liquidacao) - 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 CNAB de aquisição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-cnab-aquisicao) - 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) - Consulta de Título Público (/documentation/iaas/boletador/consulta_titulo_publico) - Listagem de Títulos Públicos (/documentation/iaas/boletador/listagem_titulos_publicos) - Do ativo ao boleto (/documentation/iaas/boletos/campos_do_boleto) - 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) - Webhooks da carteira (/documentation/iaas/composicao_carteira/webhooks) - 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) - Documentos de despesas consolidadas (/documentation/iaas/despesas/despesa_consolidada/documentos) - 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) - 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) - 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) - 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) - Introdução (/documentation/iaas/homologacao_cedente/inicio) - Integração via SFTP (/documentation/iaas/integracao_sftp/inicio) - Recebimento de Webhooks (/documentation/iaas/introducao/autenticacao_webhooks) - Erros da API (/documentation/iaas/introducao/erros) - 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) - 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) - Listar investidores (/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) - consultar_detalhes_assinatura (/documentation/iaas/investidor/cadastro/consultar_detalhes_assinatura) - 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) - enviar_documento_investor_owner (/documentation/iaas/investidor/cadastro/investor_owner/enviar_documento_investor_owner) - 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) - buscar_fundo_por_cnpj (/documentation/iaas/investidor/carteira_administrada/fundos/buscar_fundo_por_cnpj) - remover_fundo (/documentation/iaas/investidor/carteira_administrada/fundos/remover_fundo) - selecionar_fundo (/documentation/iaas/investidor/carteira_administrada/fundos/selecionar_fundo) - 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) - 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) - consultar_detalhes_assinatura (/documentation/iaas/investidor/distribuicao_externa/consultar_detalhes_assinatura) - 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) - buscar_fundo_por_cnpj (/documentation/iaas/investidor/distribuicao_externa/fundos/buscar_fundo_por_cnpj) - remover_fundo (/documentation/iaas/investidor/distribuicao_externa/fundos/remover_fundo) - selecionar_fundo (/documentation/iaas/investidor/distribuicao_externa/fundos/selecionar_fundo) - Introdução (/documentation/iaas/investidor/distribuicao_externa/introducao) - 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/) - Consulta de Liquidação (/documentation/iaas/liquidacao_ativos/ativos/recuperacao) - 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) - Consulta de Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao) - Webhooks do Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) - Layout CNAB 400 — Contratos Parcelados (/documentation/iaas/negociacao_recebiveis/arquivo/cnab400_contrato) - Layout CNAB 444 — Cessão (/documentation/iaas/negociacao_recebiveis/arquivo/cnab444) - Layout CSV — Contratos Parcelados (/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado) - Layout CSV — Duplicatas, CT-e, Cheques e Notas Promissórias (/documentation/iaas/negociacao_recebiveis/arquivo/csv_duplicatas_titulos) - 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) - Envio do Lastro do Ativo (/documentation/iaas/negociacao_recebiveis/asset/documents) - Qual ativo enviar (/documentation/iaas/negociacao_recebiveis/asset/qual_ativo_enviar) - 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 Lote (/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) - Criação do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/criacao) - Termo de Cessão do Lote (/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) - Resumo de ativos do lote (/documentation/iaas/negociacao_recebiveis/assignment/resumo_ativos) - 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 dos fechamentos de uma série de emissão (/documentation/iaas/passivo/consultas/consultar_fechamentos_serie_de_emissao) - 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. Em ativo com carência, a parcela com Valor Presente 0 na `reference_date` recebe cota 0 e é quitada sem pagamento, nas condições descritas em [Regras de Negócio](/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio#parcelas-com-valor-presente-0). 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 e sem repetição) é 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` e sem números repetidos (`uniqueItems`) — repetir um número retorna `QIT000001` (400). 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). Em `full_amortization`, as parcelas com Valor Presente 0 seguem regras próprias — veja [Regras de Negócio](/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio#parcelas-com-valor-presente-0). | | `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. Em `full_amortization`, é `0` na parcela com Valor Presente 0 quitada sem pagamento, que também tem `discount_amount` `0` — veja [Regras de Negócio](/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio#parcelas-com-valor-presente-0). | | `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), item de `installment_list` que não é inteiro ≥ 1 ou número repetido em `installment_list`. | | 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, inclusive após o arredondamento para centavos — selecione apenas parcelas que o `amount` cubra. Em `full_amortization`, também é retornado para parcela com Valor Presente 0 quando o ativo, o investidor ou a parcela não atendem às condições de quitação sem pagamento. | | EVC100035 | 400 | `amount` excede a soma dos Valores Presentes das parcelas selecionadas (tipos precificados a Valor Presente). | | EVC100037 | 400 | Em `full_amortization`, `installment_list` traz parcela com Valor Presente 0, mas não quita todo o principal em aberto. A mensagem lista as parcelas com principal que faltam. | | EVC100038 | 400 | Em `full_amortization`, a requisição quita todo o principal em aberto, mas não lista todas as parcelas em aberto com Valor Presente 0 que vencem depois da `reference_date`. A mensagem lista as parcelas faltantes. | 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 cinco 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`. ## Cenário 5: quitação integral de ativo com carência (full_amortization) Um ativo pré-fixado de R$ 30.000,00 tem quatro parcelas trimestrais, juros de 6% ao trimestre e todo o principal na parcela 4 — as parcelas 1 a 3 são de carência e pagam só juros. O ativo tem um único investidor, detentor de todas as cotas integralizadas, não é liquidado via CETIP e o investidor é liquidado pelo novo sistema interno. Emissor e investidor acordam quitar toda a dívida por R$ 31.500,00 em 2026-02-20, antes do vencimento da parcela 1. Nessa `reference_date`, as parcelas valem: | Parcela | Vencimento | Principal | Juros | Valor Presente | |---------|------------|--------------|-------------|----------------| | 1 | 2026-03-10 | R$ 0,00 | R$ 1.800,00 | R$ 1.780,13 | | 2 | 2026-06-10 | R$ 0,00 | R$ 1.800,00 | R$ 0,00 | | 3 | 2026-09-10 | R$ 0,00 | R$ 1.800,00 | R$ 0,00 | | 4 | 2026-12-10 | R$ 30.000,00 | R$ 1.800,00 | R$ 30.000,00 | A parcela 1, a primeira a vencer, vale seus juros descontados até a `reference_date`; as demais valem só o principal. Por isso as parcelas 2 e 3 têm Valor Presente 0 e são quitadas sem pagamento, nas condições descritas em [Regras de Negócio](/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio#parcelas-com-valor-presente-0). A requisição lista todas as parcelas em aberto: ```json { "security_key": "55555555-5555-4555-8555-555555555555", "investment_key": "", "amortization_type": "full_amortization", "amount": 31500.00, "reference_date": "2026-02-20", "due_date": "2026-02-20", "installment_list": [1, 2, 3, 4] } ``` Resposta `201 Created` — quatro eventos de conciliação da parcela, com `total_expected_amount` `31500.00`: | Parcela | `expected_amount` | `discount_amount` | |---------|-------------------|-------------------| | 1 | `1764.44` | `15.69` | | 2 | `0.00` | `0.00` | | 3 | `0.00` | `0.00` | | 4 | `29735.56` | `264.44` | A QI Tech liquida primeiro as parcelas 1 e 4, conforme os pagamentos entram; com as duas pagas, quita internamente as parcelas 2 e 3 com valor 0, sem transferência. O evento passa a `paid` quando as quatro parcelas estão quitadas e, com toda a dívida liquidada, o ativo passa a `matured`. Duas variações dessa requisição são rejeitadas. Com `installment_list` `[1, 2]` e `amount` `1700.00`, a requisição traz a parcela 2, de Valor Presente 0, sem quitar o principal da parcela 4 — `400 Bad Request`: ```json { "title": "Bad Request", "description": "Installment 2 has present value 0 and can only be settled with 0 when the request settles all outstanding principal. Missing installments: [4].", "translation": "A parcela 2 tem valor presente 0 e so pode ser liquidada com 0 quando a solicitacao quita todo o principal em aberto. Parcelas faltantes: [4].", "code": "EVC100037" } ``` Com `installment_list` `[1, 4]` e o mesmo `amount` `31500.00`, a requisição quita todo o principal em aberto, mas deixa de fora as parcelas 2 e 3 — `400 Bad Request`: ```json { "title": "Bad Request", "description": "The request settles all outstanding principal and must also list the installments with present value 0 due after the reference date. Missing installments: [2, 3].", "translation": "A solicitacao quita todo o principal em aberto e deve listar tambem as parcelas com valor presente 0 que vencem depois da data de referencia. Parcelas faltantes: [2, 3].", "code": "EVC100038" } ``` O serviço não acrescenta parcelas por conta própria: liste em `installment_list` tudo o que a requisição quita. ## 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), itens não inteiros ou números repetidos 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, inclusive após o arredondamento para centavos (por exemplo, `total_discount` igual ao Valor Presente, ou `amount` que se esgota antes da última parcela). Selecione apenas parcelas que o `amount` cubra. Em `full_amortization`, parcela com Valor Presente 0 também retorna este código quando o ativo tem mais de um investidor ou é liquidado via CETIP, quando o investidor não é liquidado pelo novo sistema ou quando a parcela já está quitada ou cancelada, vencida ou vence na `reference_date`. - **`EVC100035`** (400, AmountExceedsInstallmentsPresentValue) — o `amount` excede a soma dos Valores Presentes das parcelas selecionadas. Reduza o `amount`. - **`EVC100037`** (400) — em `full_amortization`, `installment_list` traz parcela com Valor Presente 0, mas deixa de fora parcela em aberto com principal. Inclua as parcelas listadas na mensagem ou retire de `installment_list` as parcelas com Valor Presente 0: elas só são quitadas sem pagamento quando a requisição quita todo o principal em aberto. - **`EVC100038`** (400) — em `full_amortization`, a requisição quita todo o principal em aberto, mas não lista todas as parcelas em aberto com Valor Presente 0 que vencem depois da `reference_date`. Inclua as parcelas listadas na mensagem; o serviço não as acrescenta por conta própria. - **`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: parcela com Valor Presente positivo recebe cota positiva, e parcela com Valor Presente 0 recebe cota 0 (veja [Parcelas com Valor Presente 0](#parcelas-com-valor-presente-0)). - 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 o que falta para quitar a parte do investidor, como desconto. Com investidor único, o desconto cobre todo o saldo restante da parcela, que termina zerada. O mesmo vale para `present_amount`. ### Parcelas com Valor Presente 0 Na `reference_date`, a primeira parcela a vencer vale principal e juros descontados pro-rata; as demais parcelas futuras valem apenas o principal. Em um ativo com carência, as parcelas só de juros (principal 0) que vencem depois da primeira têm, por isso, Valor Presente 0 e recebem cota 0 no rateio. Cada parcela de `installment_list` com Valor Presente exatamente 0 gera um `event_conciliation` com `expected_amount` 0 e `discount_amount` 0 — a parcela é quitada sem pagamento — quando **todas** as condições abaixo são atendidas: - o ativo tem um único investidor, que detém todas as cotas integralizadas; - o ativo não é liquidado via CETIP; - o investidor é liquidado pelo novo sistema interno da QI Tech (`internal_new_system`); - a parcela está em aberto (`installment_status` diferente de `paid`, `paid_early`, `paid_overdue` e `canceled`) e vence depois da `reference_date`; - `installment_list` inclui todas as parcelas em aberto que ainda têm principal (`principal_amortization_amount` maior que 0). Duas regras amarram essas parcelas ao principal em aberto: 1. **Regra 1 — parcela com Valor Presente 0 exige todo o principal.** Em ativo com investidor único e fora da CETIP, se `installment_list` traz parcela com Valor Presente 0 em aberto e com vencimento depois da `reference_date`, mas deixa de fora alguma parcela em aberto com principal, a criação é rejeitada com `EVC100037`, que lista as parcelas faltantes. 2. **Regra 2 — todo o principal exige as parcelas com Valor Presente 0.** Se a requisição quita todo o principal em aberto de um ativo com investidor único, fora da CETIP e com investidor no novo sistema, `installment_list` também precisa incluir todas as parcelas em aberto com Valor Presente 0 que vencem depois da `reference_date` — caso contrário, `EVC100038`, que lista as parcelas faltantes. O serviço nunca acrescenta parcelas por conta própria: o integrador lista o que está quitando. Nos demais casos — ativo com mais de um investidor ou liquidado via CETIP, investidor fora do novo sistema (como o sistema legado, `internal_legacy_system`), parcela já quitada ou cancelada, vencida ou que vence na própria `reference_date` — a parcela com Valor Presente 0 é rejeitada com `EVC100034`. A ordem das verificações está em [Consistência entre `amount` e a distribuição](#consistencia-entre-amount-e-a-distribuicao). ## Consistência entre `amount` e a distribuição Após distribuir o `amount`, o serviço valida o resultado nesta ordem; as verificações 2 e 3 são feitas juntas, parcela a parcela. As verificações 3, 6 e 7 são exclusivas de `full_amortization`; as demais valem para **todos** os tipos: 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`; selecione apenas parcelas que o `amount` cubra. A única exceção é a parcela com Valor Presente 0 de `full_amortization` em ativo com investidor único e fora da CETIP, desde que esteja em aberto e vença depois da `reference_date` (veja [Parcelas com Valor Presente 0](#parcelas-com-valor-presente-0)). 3. A parcela com Valor Presente 0 da exceção acima está em `installment_list`, mas falta alguma parcela em aberto com principal (regra 1) → `EVC100037`, com a lista das parcelas faltantes. 4. 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`. 5. Os `expected_amount` são arredondados para centavos, com o resíduo de arredondamento na **última parcela com `expected_amount` positivo**. Toda parcela, exceto as quitadas sem pagamento, precisa continuar com `expected_amount` positivo depois do arredondamento — caso contrário, `EVC100034`. 6. A requisição quita todo o principal em aberto, mas não lista todas as parcelas em aberto com Valor Presente 0 que vencem depois da `reference_date` (regra 2) → `EVC100038`, com a lista das parcelas faltantes. Só se aplica a ativo com investidor único, fora da CETIP, e a investidor no novo sistema. 7. Parcela com Valor Presente 0 de investidor que não é liquidado pelo novo sistema → `EVC100034`. Assim, `total_expected_amount` do evento é sempre igual à soma dos filhos, e as parcelas quitadas sem pagamento permanecem com `expected_amount` 0. ## 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`. **Parcelas com `expected_amount` 0 são quitadas por último, sem transferência.** Em `full_amortization`, a QI Tech liquida primeiro as parcelas com `expected_amount` positivo, conforme os pagamentos entram. Só depois que todas elas estão pagas, cada parcela com `expected_amount` 0 é liquidada internamente com valor 0 — sem transferência de recursos e sem envio de liquidação à QI DTVM — e o security-service a quita integralmente, com desconto de todo o saldo da parcela. Pela liquidação, o evento só passa a `paid` quando todas as parcelas, inclusive as de valor 0, estão quitadas. Com as parcelas de valor positivo já pagas, o evento também não é finalizado enquanto restar parcela de valor 0 por quitar; se ele for finalizado com alguma parcela de valor positivo ainda sem pagamento, as parcelas de valor 0 são canceladas junto com as demais parcelas não pagas. Quando a liquidação quita toda a dívida, o ativo passa a `matured`. ## 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. | | 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. | | 409 | COM000085 | Conflict | Vehicle with chassis (chassis) already belongs to a validated vehicle_stock collateral of this operation. | O veículo com chassi (chassis) já está em uma garantia de estoque de veículos validada desta operação. | | 422 | COM000086 | Unprocessable Entity | Operation (operation_key) was signed but the collateral application failed; the operation is now failed. | A operação (operation_key) foi assinada, mas a aplicação da garantia falhou; a operação ficou com status failed. | | 422 | COM000087 | Unprocessable Entity | Vehicle with chassis (chassis) could not be validated on B3 (code: (b3_code), description: (b3_description)); the vehicle_stock collateral was registered as canceled. | O veículo com chassi (chassis) não pôde ser validado na B3 (código: (b3_code), descrição: (b3_description)); a garantia de estoque de veículos foi registrada como cancelada. | | 400 | COM000091 | Bad Request | The issuer's liquidation account request was rejected by the BaaS. The rejection is not cleared automatically: resolve it with the issuer and request the account again. | A abertura da conta de liquidação do emissor foi recusada pelo BaaS. A recusa não é liberada automaticamente: resolva o motivo junto ao emissor e solicite a abertura da conta novamente. | ## 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. | | 400 | EVC100037 | Bad Request | The installment has present value 0 and can only be settled with 0 when the request settles all outstanding principal; the message lists the missing installments. | A parcela tem Valor Presente 0 e só pode ser liquidada com 0 quando a solicitação quita todo o principal em aberto; a mensagem lista as parcelas faltantes. | | 400 | EVC100038 | Bad Request | The request settles all outstanding principal and must also list the installments with present value 0 due after the reference date; the message lists the missing installments. | A solicitação quita todo o principal em aberto e deve listar também as parcelas com Valor Presente 0 que vencem depois da data de referência; a mensagem lista as parcelas faltantes. | | 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. | --- ## Tabela de erros possíveis na consulta e no reenvio de webhooks | Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (pt-BR) | |------------|----------------|--------|-----------------|------------------| | 404 | OWB0000001 | Not Found | Webhook not found. | Webhook não encontrado. | | 400 | OWB0000005 | Bad Request | You do not have access to this tenant. | Você não tem acesso a este tenant. | | 409 | OWB0000007 | Conflict | Webhook is `{webhook_status}` and cannot be sent again. | O webhook está `{webhook_status}` e não pode ser reenviado. | | 409 | OWB0000008 | Conflict | Webhook is already being sent by another process. | O webhook já está sendo enviado por outro processo. | --- # 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`** — cada garantia representa **um único veículo**, enviado no campo `vehicle`. Para cadastrar N veículos, envie N requisições `POST`, uma por veículo. Cada requisição cria uma garantia própria, com o seu `collateral_key` e o seu `collateral_status`. Request Body ```json { "collateral_type": "vehicle_stock", "additional_documents": [ { "document_type": "vehicle_crlv_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ], "vehicle": { "chassis": "9BWZZZ377VT004251", "plate": "ABC1D23", "plate_state": "SP", "renavam": "12345678901", "value": 85000.00, "year": 2023, "mileage": 32000 } } ``` ### **vehicle object** | 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** | | `value` | number | Valor do veículo. Maior ou igual a 0. | Não | | `year` | integer | Ano do veículo. Maior ou igual a 1900 e no máximo o ano seguinte ao atual. | Não | | `mileage` | integer | Quilometragem do veículo. Maior ou igual a 0. Exige `plate`, `plate_state` e `renavam`. | 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). Um veículo 0km também não pode enviar `mileage`. ::: ### **Tipos de Documentos** | Enum | Descrição | |-----------------------------|----------------------------------------------------| | `vehicle_crlv_certificate` | Certificado de Registro e Licenciamento de Veículo (CRLV). | O CRLV é enviado em `additional_documents`, na raiz do request body (ver **[additional_documents list](#additional_documents-list)**). O envio é opcional e só é aceito o tipo `vehicle_crlv_certificate`. O documento é gravado na garantia e retorna no campo `additional_documents` da resposta, e não dentro de `collateral_data`. ### **Validação do veículo** No cadastro, o veículo é **consultado** (não gravado) na base de estoque de veículos da B3: - **Veículo livre** (sem reserva ativa ou não encontrado na B3): a garantia é criada como `validated` e a requisição responde **201** com a garantia. - **Veículo com reserva ativa na B3** ou **erro na consulta**: a garantia é gravada como `canceled` e a requisição responde **422** com o código `COM000087`. A garantia cancelada retorna no campo `collateral` do corpo do erro. Uma garantia `canceled` não entra na minuta nem na emissão, e não aparece na listagem de garantias da operação. - **Chassi já presente em outra garantia `validated` da mesma operação**: a requisição é rejeitada com **409** (`COM000085`) e nada é gravado. Um chassi cuja garantia anterior foi cancelada pode ser enviado novamente. ### **Response** Response Body (201) ```json { "collateral_key": "8a0c6e0e-3f5b-4c2a-9d7e-1b2f3c4d5e6f", "collateral_type": "vehicle_stock", "collateral_status": "validated", "collateral_data": { "vehicle": { "chassis": "9BWZZZ377VT004251", "plate": "ABC1D23", "plate_state": "SP", "renavam": "12345678901", "value": 85000.00, "year": 2023, "mileage": 32000 } }, "collateral_document_key": null, "collateral_instrument_document_key": null, "additional_documents": [ { "collateral_document_key": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "collateral_document_type": "vehicle_crlv_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" } ], "collateral_event_list": [ { "collateral_status": "validated", "event_type": "collateral_status_change", "event_data": { "from": "created", "to": "validated", "reason": "vehicle_consult_free", "b3_response": { "reservations": [] }, "b3_code": null, "b3_description": null, "b3_http_status": 200 }, "event_datetime": "2026-09-28T14:32:10.123456+00:00" } ] } ``` Response Body (422 — COM000087) ```json { "title": "Unprocessable Entity", "description": "Vehicle with chassis '9BWZZZ377VT004251' could not be validated on B3 (code: None, description: Vehicle has an active reservation with status 'Ativo'); the vehicle_stock collateral was registered as canceled.", "translation": "O veiculo com chassi '9BWZZZ377VT004251' nao pode ser validado na B3 (codigo: None, descricao: Vehicle has an active reservation with status 'Ativo'); a garantia de estoque de veiculos foi registrada como cancelada.", "code": "COM000087", "collateral": { "collateral_key": "8a0c6e0e-3f5b-4c2a-9d7e-1b2f3c4d5e6f", "collateral_type": "vehicle_stock", "collateral_status": "canceled", "collateral_data": { "vehicle": { "chassis": "9BWZZZ377VT004251", "plate": "ABC1D23", "plate_state": "SP", "renavam": "12345678901" } }, "collateral_document_key": null, "collateral_instrument_document_key": null, "additional_documents": [], "collateral_event_list": [ { "collateral_status": "canceled", "event_type": "collateral_status_change", "event_data": { "from": "created", "to": "canceled", "reason": "vehicle_consult_marked", "b3_response": { "reservations": [ { "reservation_status": "Ativo" } ] }, "b3_code": null, "b3_description": "Vehicle has an active reservation with status 'Ativo'", "b3_http_status": 200 }, "event_datetime": "2026-09-28T14:32:10.123456+00:00" } ] } } ``` ### **Status da garantia (`collateral_status`)** Toda garantia, de qualquer tipo, retorna o campo `collateral_status`. Para os tipos que não dependem de validação externa, a garantia nasce `validated` e passa a `finished` na assinatura. Para `vehicle_stock`, o ciclo completo é: | Status | Descrição | |--------------|----------------------------------------------------------------------------------------------------------------------------| | `validated` | Garantia aceita no cadastro. Para `vehicle_stock`, o veículo foi consultado e está livre na B3. | | `canceled` | Garantia cancelada: veículo com reserva ativa ou erro na consulta no cadastro, garantia removida ou operação cancelada. Não entra na minuta nem na emissão. | | `pending` | Operação assinada; o veículo aguarda a gravação na B3. | | `finished` | Veículo gravado na B3 (ou, para os demais tipos, operação assinada). | | `failed` | A gravação do veículo na B3 falhou após a assinatura. | ### **Histórico de eventos (`collateral_event_list`)** Toda garantia retorna o campo `collateral_event_list`, com o histórico de mudanças de status em ordem cronológica. | Campo | Tipo | Descrição | |------------------|--------|------------------------------------------------------------------------------------------------------------| | `collateral_status` | string | Status da garantia após o evento. | | `event_type` | string | Tipo do evento. `collateral_status_change` para mudanças de status. | | `event_data` | object | Dados do evento: `from` (status anterior), `to` (novo status), `reason` (motivo) e, para `vehicle_stock`, a resposta da B3 (`b3_response`, `b3_code`, `b3_description`, `b3_http_status`). | | `event_datetime` | string | Data e hora do evento (ISO 8601, UTC). | ### **Fluxo após a assinatura** - Quando todos os envolvidos assinam, a operação passa para `pending_collateral` e cada veículo com garantia `validated` é consultado de novo e gravado na B3. - Se todos os veículos forem gravados, as garantias passam a `finished` e a operação segue para `issued`. - Se a consulta ou a gravação de algum veículo falhar, as garantias afetadas passam a `failed` e a operação passa a `failed`. A operação sai de `failed` por reprocessamento feito pela QI Tech ou por cancelamento. ### **Erros** | HTTP Status | Código | Descrição | |-------------|-------------|-------------------------------------------------------------------------------------------------------------| | 400 | — | Erro de validação de schema (por exemplo, grupo `plate`/`plate_state`/`renavam` incompleto). | | 400 | `COM000083` | Tenant não possui acesso a esse tipo de garantia. | | 400 | `COM000084` | Ano do veículo maior que o ano seguinte ao atual. | | 409 | `COM000085` | O chassi já está em uma garantia `validated` da mesma operação. | | 422 | `COM000087` | Veículo com reserva ativa na B3 ou erro na consulta. A garantia fica gravada como `canceled` e retorna no campo `collateral` do corpo do erro. | Consulte também o [catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). ## **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` — veja [Garantia de estoque de veículos (Floor Plan)](#garantia-de-estoque-de-veículos-floor-plan). | | `others` | Outras garantias. | --- # Consulta de documentos URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/consultar-documento Este endpoint permite a **consulta de documentos** previamente enviados para uma operação. Utilize-o para recuperar o conteúdo dos documentos vinculados a uma garantia, como o instrumento da garantia (`collateral_document_key`) e os documentos acessórios (`additional_documents[].document_key`), a partir da `document_key` retornada no [envio de documentos](./upload-documento.md) ou na consulta da operação. --- ## **Consulta de Documento (GET)** ## **Request** ENDPOINT /commercial_paper/document/ DOCUMENT-KEY MÉTODO GET ### **Path Params** | Campo | Tipo | Descrição | Caracteres Máx. | |------------------|--------|-----------------------------------------------|-----------------| | `DOCUMENT-KEY` * | string | Chave única do documento a ser consultado (UUID v4). | 36 | ## **Response** STATUS 200 Response Body ```json { "document_base64": "sringb64" } ``` ## **Response Body Params** | Campo | Tipo | Descrição | |---------------------|--------|------------------------------------------------| | `document_base64` * | string | Conteúdo do documento codificado em Base64. | --- --- # 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. | | `pending_collateral` | Operação assinada; aguardando a aplicação das garantias. | | `failed` | Falha na operação. | | `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. | | `pending_collateral` | Operação assinada; aguardando a aplicação das garantias. | | `failed` | Falha na operação. | | `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. --- # Consulta de templates disponíveis URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/consulta-minutas-disponiveis Este endpoint permite a consulta de todos os templates disponíveis para serem utilizados no sistema de escrituração. ### **Request** ENDPOINT /document_generator/document_template MÉTODO GET ### **Query Params** | Campo | Tipo | Descrição | Obrigatório | |----------------------------|----------|-----------------------------------------------|-------------| | `document_type` | string | Tipo do documento. **[Enumeradores document_type](#enumeradores-document_type)** | Não | | `page` | integer | Número da página (padrão: 1). | Não | | `page_size` | integer | Itens por página (padrão e máximo: 100). | Não | --- ## Response STATUS 200 Response Body ```json { "data": [ { "name": "NC - Padrão", "document_template_key": "7668cf4a-e19a-4f94-b209-8186909ea650", "document_type": "commercial_paper", "version": 1, "extra_fields": [] }, { "name": "TA Sandbox", "document_template_key": "2165ba90-99c8-442a-9dc3-3f651a08c113", "document_type": "adhesion_term", "version": 1, "extra_fields": [] } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 2 } } ``` ### **Response Body Params** | Campo | Tipo | Descrição | Caracteres Máx. | |---------------------------|----------|---------------------------------------------------------------------------|-----------------| | `name` * | string | Nome do template. | 255 | | `document_template_key` * | string | Chave única do template (UUID v4). É o valor enviado no cadastro da operação. | 36 | | `document_type` * | string | Tipo do documento gerado a partir do template. **[Enumeradores document_type](#enumeradores-document_type)** | 50 | | `version` * | integer | Versão atual do template. | - | | `extra_fields` * | array | Campos extras exigidos pelo template. Lista vazia quando o template não exige nenhum. **[Campos extras](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields)** | - | #### **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. | --- ## Erros | Status | Código | Descrição | | --- | --- | --- | | 400 | `QIT000010` | `page` ou `page_size` fora do formato inteiro. | Erros transversais da integração seguem o formato descrito no [Catálogo de Erros](/documentation/escrituracao/catalogo-erros/catalogo-erros). --- ## **Enumeradores document_type** Tipos utilizados no fluxo de emissão de nota comercial: | Valor | Descrição | |---------------------|------------------------------------------------------------------| | `commercial_paper` | Minuta da nota comercial. | | `adhesion_term` | Termo de adesão. | | `subscription_note` | Boletim de subscrição. | | `amendment_term` | Termo de aditamento. | --- # 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`. --- --- # Entrega e Reenvio de Webhooks URL: /documentation/escrituracao/entrega-webhooks Esta página descreve o que a QI Tech faz quando a entrega de um webhook falha e os endpoints que permitem consultar o histórico de entregas e forçar um reenvio. Para a lista dos eventos emitidos, consulte **[Eventos de Escrituração](/documentation/escrituracao/webhooks-escrituracao)**; para cadastrar a URL de destino, **[Configuração de Webhooks](/documentation/escrituracao/configuracao-webhooks)**. Todo evento gerado é registrado antes de ser entregue. A primeira entrega é síncrona, no mesmo instante em que o evento nasce; se ela falhar, o evento entra na fila de reenvio. --- ## Política de reenvio Uma entrega falha quando o seu endpoint responde com um status `3xx`, `4xx` ou `5xx`, ou quando a requisição não chega a receber resposta (falha de DNS, conexão recusada ou timeout). Cada evento é entregue no máximo **8 vezes**: a tentativa inicial e mais 7 reenvios, com intervalo crescente entre eles. | Tentativa | Intervalo desde a anterior | Tempo desde a primeira | | --------- | -------------------------- | ---------------------- | | 1 | — | 0 | | 2 | 1 minuto | 1 minuto | | 3 | 5 minutos | 6 minutos | | 4 | 15 minutos | 21 minutos | | 5 | 1 hora | 1h21 | | 6 | 3 horas | 4h21 | | 7 | 6 horas | 10h21 | | 8 | 12 horas | 22h21 | Esgotadas as 8 tentativas, o evento passa para `failed` e não é mais enviado. A fila de reenvio é processada a cada 5 minutos, então o intervalo efetivo pode ser até 5 minutos maior que o da tabela. :::warning Seu endpoint pode receber o mesmo evento mais de uma vez Se o seu sistema processar o evento e a resposta não chegar até nós, por timeout ou por um erro posterior ao processamento, a entrega é contada como falha e o evento é reenviado. O corpo é idêntico em todas as tentativas. O `event_datetime` marca o momento em que o evento foi gerado, não o do envio, então ele não muda entre as tentativas: use a combinação de `event_type`, `event_datetime` e os identificadores de `event_data` para reconhecer o que você já processou. ::: --- ## Status do webhook | Status | Descrição | | ------------------ | ------------------------------------------------------------------------------ | | `pending_shipment` | A última entrega falhou. O campo `next_attempt_at` indica quando será a próxima. | | `on_queue` | Reenvio enfileirado, aguardando processamento. | | `sent` | Entregue. O seu endpoint respondeu `2xx`. | | `failed` | As 8 tentativas se esgotaram. O evento não será mais enviado. | --- ## Consulta de Webhooks (GET) Retorna os eventos do seu tenant, do mais recente para o mais antigo. Use esta consulta para reconciliar o que a QI Tech enviou com o que o seu sistema processou. ### Request ENDPOINT /outgoing_webhook/webhook MÉTODO GET ### Query Params | Campo | Tipo | Descrição | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------ | | `status` | string | Filtra pelo status da entrega. Aceita `pending_shipment`, `on_queue`, `sent` ou `failed`. | | `event_type` | string | Filtra pelo tipo do evento, por exemplo `commercial_paper.operation_status_change`. | | `created_after` | string | Retorna os eventos gerados a partir desta data e hora, no formato `YYYY-MM-DDTHH:MM:SS`. | | `created_before` | string | Retorna os eventos gerados até esta data e hora, no mesmo formato. | | `page` | integer | Página desejada, começando em `1`. Padrão `1`. | | `page_size` | integer | Registros por página. Padrão e máximo `100`. | --- ### Response STATUS 200 Response Body ```json { "data": [ { "webhook_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "status": "pending_shipment", "number_of_attempts": 2, "next_attempt_at": "2026-05-05T13:27:01", "webhook_data": { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2026-05-05T13:22:01Z", "event_data": { "operation_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753", "operation_status": "issued" } }, "created_at": "2026-05-05T13:22:01" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 1 } } ``` --- ### Response Body Params | Campo | Tipo | Descrição | | -------------------- | ------- | ------------------------------------------------------------------------------------------- | | `webhook_key` | string | Chave única do evento (UUID v4). É o identificador usado no reenvio manual. | | `tenant_key` | string | Chave do tenant dono do evento. | | `status` | string | Status atual da entrega. **[Enumeradores status](#status-do-webhook)** | | `number_of_attempts` | integer | Quantidade de entregas que falharam. Uma entrega aceita não incrementa o contador. | | `next_attempt_at` | string | Data e hora do próximo reenvio. `null` quando não há reenvio programado. | | `webhook_data` | object | Corpo enviado ao seu endpoint, idêntico ao da entrega. | | `created_at` | string | Data e hora em que o evento foi gerado. | --- ## Consulta de um Webhook (GET) ### Request ENDPOINT /outgoing_webhook/webhook/ WEBHOOK-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------- | ------ | -------------------------------- | ---------- | | `WEBHOOK-KEY` | string | Chave única do evento (UUID v4). | 36 | --- ### Response STATUS 200 Response Body ```json { "webhook_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec", "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "status": "pending_shipment", "number_of_attempts": 2, "next_attempt_at": "2026-05-05T13:27:01", "webhook_data": { "event_type": "commercial_paper.operation_status_change", "event_datetime": "2026-05-05T13:22:01Z", "event_data": { "operation_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753", "operation_status": "issued" } }, "created_at": "2026-05-05T13:22:01" } ``` Os campos são os mesmos descritos em **[Response Body Params](#response-body-params)**. --- ## Reenvio Manual (PUT) Envia o evento na hora, sem esperar a próxima janela da política de reenvio. Serve para quando o seu sistema voltou ao ar antes do próximo intervalo. A tentativa manual segue as mesmas regras das automáticas: se falhar, incrementa o contador e agenda o próximo degrau; na oitava falha, o evento passa para `failed`. Só eventos em `pending_shipment` ou `on_queue` podem ser reenviados. ### Request ENDPOINT /outgoing_webhook/webhook/ WEBHOOK-KEY /synchronous MÉTODO PUT ### Path Params | Campo | Tipo | Descrição | Caracteres | | ------------- | ------ | -------------------------------- | ---------- | | `WEBHOOK-KEY` | string | Chave única do evento (UUID v4). | 36 | --- ### Response STATUS 202 A resposta não tem corpo. O `202` confirma que a tentativa foi executada, não que o seu endpoint a aceitou: consulte o evento para saber o resultado. --- ## Erros | Código HTTP | Código do Erro | Descrição (eng) | Tradução (pt-BR) | | ----------- | -------------- | ------------------------------------------------------- | ------------------------------------------------------- | | 404 | OWB0000001 | Webhook not found. | Webhook não encontrado. | | 400 | OWB0000005 | You do not have access to this tenant. | Você não tem acesso a este tenant. | | 409 | OWB0000007 | Webhook is `{webhook_status}` and cannot be sent again. | O webhook está `{webhook_status}` e não pode ser reenviado. | | 409 | OWB0000008 | Webhook is already being sent by another process. | O webhook já está sendo enviado por outro processo. | --- ## Referências - [Eventos de Escrituração](/documentation/escrituracao/webhooks-escrituracao) - [Configuração de Webhooks](/documentation/escrituracao/configuracao-webhooks) - [Autenticação de Webhooks](/documentation/escrituracao/introducao/autenticacao_webhooks) --- # 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. | --- # Consulta do Termo de Adesão Assinado URL: /documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-termo-assinado Este endpoint retorna o **link para download do termo de adesão assinado** da auto-assinatura, com o relatório de assinaturas do QI SIGN. O termo assinado fica disponível quando a auto-assinatura chega a `enabled`, ou seja, depois que todos os assinantes concluem a assinatura pelos [links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura). Em qualquer outro status, este endpoint responde `ISS0000030`. :::info Link temporário O `signed_url` é um link temporário, válido por **24 horas**. Para obter um link novo, consulte o endpoint novamente. ::: --- ## Consulta do Termo Assinado (GET) ### Request ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature/report 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 ```json { "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34", "status": "signed", "signed_file_url": null, "documents": [ { "document_type": "adhesion_auto_signature_term", "signed_url": "https://qisign-dossiers.s3.amazonaws.com/7bcf5868-784a-4356-85fb-dd72fd53cd4a.pdf?X-Amz-Expires=86400&X-Amz-Signature=...", "signers": [] } ], "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. Sempre `signed`. | | `signed_file_url` | null | Não utilizado na auto-assinatura. O link do termo assinado vem em `documents[].signed_url`. | | `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`. | | `signed_url` | string | Link temporário (24 horas) para download do PDF do termo assinado, com o relatório de assinaturas. | | `signers` | array | Sempre vazio nesta consulta. Para os assinantes, use a [consulta dos links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura). | --- ### Erros | HTTP | Código | Quando ocorre | | ---- | ------------------------------------------ | ----------------------------------------------------------------------------------- | | 400 | `ISS0000030` (`AutoSignatureInWrongStatus`) | A auto-assinatura não está em `enabled` — o termo de adesão ainda não foi assinado. | | 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. O termo assinado pode ser baixado pela [consulta do termo assinado](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-termo-assinado). 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 | | [`GET .../auto_signature/report`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-termo-assinado) | Baixar o termo de adesão assinado, depois que a auto-assinatura estiver em `enabled` | ## 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. Quando a solicitação passa pelas validações do BaaS mas a conta ainda não foi aberta, o status é `approved`, com a mesma estrutura de resposta do `pending`. Se a solicitação de abertura tiver sido recusada pelo BaaS, o endpoint retorna `account_status: "rejected"` com o campo `rejection_reason`. Nesse estado o emissor não tem conta apta a receber a integralização, e uma nova solicitação de abertura precisa ser aprovada. --- ## 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 — conta recusada ```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": "rejected", "rejection_reason": "Rejeitado devido ao Bacen Protege+" } ``` --- ### 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 solicitação não foi decidida, `approved` quando passou pelas validações do BaaS mas a conta ainda não foi aberta, `opened` após a abertura e `rejected` quando a solicitação foi recusada. | | `rejection_reason` | string | Motivo da recusa informado pelo BaaS. Presente apenas quando `account_status` é `rejected`. | | `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", "issuer_key": "1bc06a53-9503-4520-916c-38b5a6bb5912", "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. | | `issuer_key` | string | Chave única do emissor associado à 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", "payment_destination": { "pix_key": "40008675000100", "pix_key_type": "cnpj", "payment_method": "pix", "beneficiary": { "name": "Fornecedor Exemplo", "document_number": "40008675000100" } }, "baas_payment_key": null, "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`). | | `payment_destination` | object | Instrução de desembolso a terceiro usada na transferência. `null` quando o pagamento foi para o próprio emissor. | | `baas_payment_key` | string | Chave do pagamento no BaaS, quando houver. | | `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 --- # Retentativa de Abertura de Conta de Liquidação URL: /documentation/escrituracao/integralizacao-cotas/retentativa-conta-liquidacao Quando o BaaS recusa a abertura da conta de liquidação de um emissor, a solicitação recusada não pode ser reaproveitada: é preciso enviar uma nova. Este endpoint faz esse reenvio. O caso mais comum é o bloqueio no **Bacen Protege+**: o titular cadastrou o CNPJ do emissor no serviço, o que impede a abertura de contas em seu nome. Depois que o emissor desativa a proteção, uma nova solicitação passa normalmente. O fluxo esperado é: 1. O cadastro do emissor dispara automaticamente a solicitação de abertura da conta. 2. Se ela for recusada, chega o webhook [`liquidation_account.account_request_status_change`](../webhooks-escrituracao.md) com `status: "rejected"` e o motivo em `rejection_reason`. 3. Resolvido o motivo com o emissor, este endpoint envia uma solicitação nova. 4. O resultado chega pelo mesmo webhook: `approved` se passar, `rejected` de novo se o bloqueio continuar de pé. Resolver a recusa no cadastro evita que o problema apareça depois, na criação ou na emissão da operação. --- ## Retentativa de Abertura de Conta de Liquidação (PUT) ### Request ENDPOINT /account_liquidation/issuer/ ISSUER-KEY /retry_account_request MÉTODO PUT ### Path Params | Campo | Tipo | Descrição | Caracteres | |--------------|--------|-----------------------------------|------------| | `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36 | O corpo da requisição é vazio. --- ### Response STATUS 201 ```json { "request_account_key": "1c0a2e54-77a8-4f0e-8d8e-6f2b9b3c1d22", "account_number": "1234567", "account_digit": "8", "account_branch": "0001", "issuer_key": "23d933e9-88ba-4291-a6a4-33f025ab361f", "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154" } ``` ### Response Body Params | Campo | Tipo | Descrição | |-----------------------|--------|----------------------------------------------------| | `request_account_key` | string | Chave única da nova solicitação de abertura. | | `account_number` | string | Número reservado para a conta. | | `account_digit` | string | Dígito da conta. | | `account_branch` | string | Agência da conta. | | `issuer_key` | string | Chave única do emissor. | | `tenant_key` | string | Chave única do cliente. | :::info A conta ainda não existe nesse momento: o retorno traz os dados reservados para ela. Acompanhe o resultado pelo webhook ou pela [consulta da conta de liquidação](./consulta-conta-liquidacao.md). ::: --- ### Erros | Código HTTP | Código do Erro | Descrição | |-------------|----------------|-----------| | 400 | ACL000065 | O emissor não possui solicitação de abertura de conta recusada para retentar: ou ele já tem uma solicitação ativa, ou nunca teve uma recusada. | --- # 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. Obrigatório quando `subscripted_quantity_percentage` não for enviado. | | `subscripted_quantity_percentage` | number | Percentual da emissão a subscrever, de 0 a 100. Obrigatório quando `subscripted_quantity` não for enviado. | | `financial_base_date` | string | Data base financeira. Quando omitida, assume a data base da operação. | | `subscription_date`* | string | Data da subscrição. | | `subscription_note_template_key`* | string | Template do boletim de subscrição. | :::info Quantidade ou percentual Envie **apenas um** entre `subscripted_quantity` e `subscripted_quantity_percentage`. Ao enviar o percentual, a quantidade de cotas é derivada da quantidade total da emissão e arredondada para baixo. ::: --- ### Response STATUS 201 Response Body ```json { "subscription_key": "2f7e00b5-988f-4214-bb46-4728d9081148", "issuer_key": "1bc06a53-9503-4520-916c-38b5a6bb5912", "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). | | `issuer_key` | string | Chave única do emissor associado à 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 CNAB de aquisição URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-cnab-aquisicao Devolve o CNAB de aquisição da subscrição, no layout posicional de 444 caracteres, codificado em Base64. O arquivo é **gerado no momento da consulta**, a partir dos dados atuais da operação. Ele não é armazenado, então duas consultas em dias diferentes devolvem nomes de arquivo e datas de gravação diferentes. Use este endpoint para **reenviar** o arquivo ao destino, não como registro do que foi enviado anteriormente. --- ## Consulta de CNAB de aquisição (GET) ### Request ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /acquisition_cnab MÉTODO GET ### 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 | --- ### Response STATUS 200 Response Body ```json { "file_name": "CBNC210900.REM", "document_base64": "MDFSRU1FU1NBMDFDT0JSQU5DQSAgICAgICAwMDAwMDAwMDAwMDAwMDAxMjM1NEZVTkRPIEhN..." } ``` ### Response Body Params | Campo | Tipo | Descrição | | --- | --- | --- | | `file_name` | string | Nome do arquivo, no formato `CBNC00.REM`. O dia e o mês são os da geração. | | `document_base64` | string | Conteúdo do arquivo em Base64. | :::note Ao decodificar o Base64 você obtém um arquivo de **texto**, não um PDF: uma linha de 444 caracteres por registro, com um header, um detalhe por parcela e um trailer. ::: --- ### Erros | HTTP | Código | Quando ocorre | |------|--------|---------------| | 400 | `INT000005` (`SubscriptionNotLinked`) | A subscrição não pertence ao processo de integralização informado. | | 403 | `INT000003` (`IntegralizationNotBelongToTenant`) | O processo de integralização não pertence ao cliente que fez a requisição. | | 404 | `INT000004` (`SubscriptionNotFound`) | Subscrição não encontrada. | | 422 | `INT000036` (`FinancialIndexNotSupported`) | O índice de correção da operação não é suportado na geração do CNAB. | | 422 | `INT000043` (`AcquisitionCnabNumeroDocumentoDoesNotFit`) | O número do contrato não cabe no campo de número do documento. | | 422 | `INT000044` (`TenantInvestorNameMissing`) | O investidor da subscrição não tem nome cadastrado. | --- # 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", "issuer_key": "1bc06a53-9503-4520-916c-38b5a6bb5912", "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). | | `issuer_key` | string | Chave única do emissor associado à 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. O token carrega os seguintes claims: | Claim | Descrição | |---------------|---------------------------------------------------------------------------| | `timestamp` | Data e hora UTC da geração da assinatura, no formato `YYYY-MM-DDTHH:MM:SS`. | | `method` | Método HTTP da requisição. Sempre `POST`. | | `uri` | URL completa configurada para o recebimento do webhook. | | `payload_md5` | MD5 do corpo da requisição, em hexadecimal. Presente sempre que há corpo. | O corpo da requisição não é assinado diretamente. Para validar a integridade, decodifique o token e compare o `payload_md5` com o MD5 do corpo recebido. 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 um header `SIGNATURE` com um JWT assinado em HS256 com a *Signature Key* compartilhada com o parceiro. O corpo da requisição não é assinado diretamente: ele entra no token pelo claim `payload_md5`. Esta assinatura deve ser validada em seu sistema para garantir a autenticidade e integridade dos dados recebidos. Para o passo a passo da 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 #### Mudança de Status da Solicitação de Conta de Liquidação Enviado quando a solicitação de abertura da conta de liquidação do emissor muda de estado. O campo `event_data.status` diz qual mudança ocorreu, e **deve ser consultado antes de qualquer tratamento**, porque o mesmo `event_type` carrega tanto a recusa quanto a abertura. | `status` | Significado | |------------|-------------| | `rejected` | O BaaS recusou a abertura, 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. Resolvido o motivo com o emissor, use a [retentativa de abertura](./integralizacao-cotas/retentativa-conta-liquidacao.md). | | `approved` | A solicitação passou pelas validações do BaaS. A conta ainda não existe: ela é aberta na emissão da primeira operação do emissor. | | `opened` | A conta foi aberta e já pode receber a integralização. | O `approved` chega poucos minutos depois do cadastro do emissor e é a contrapartida do `rejected`. É por ele que se sabe que a abertura da conta vai ser possível, sem precisar esperar a primeira emissão. **Event Type:** `liquidation_account.account_request_status_change` **Payload de recusa:** ```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" } } } ``` Na recusa, 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. **Payload de aprovação:** ```json { "event_type": "liquidation_account.account_request_status_change", "event_datetime": "2025-07-30T16:07:30Z", "event_data": { "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "account_request_key": "7e1c53d6-d372-4020-be6b-ed94248d7ae9", "status": "approved", "account_info": { "account_branch": "0001", "account_number": "1234567", "account_digit": "3" } } } ``` **Payload de abertura:** ```json { "event_type": "liquidation_account.account_request_status_change", "event_datetime": "2025-07-30T16:12:00Z", "event_data": { "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "account_request_key": "7e1c53d6-d372-4020-be6b-ed94248d7ae9", "status": "opened", "account_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec", "account_info": { "account_branch": "0001", "account_number": "1234567", "account_digit": "3" } } } ``` O estado corrente da conta também pode ser consultado a qualquer momento pela [consulta da conta de liquidação](./integralizacao-cotas/consulta-conta-liquidacao.md). #### Desembolso Recusado Enviado quando uma TED de desembolso saída da conta de liquidação não chega ao destino — seja porque o BaaS recusou a transferência, seja porque o valor foi estornado de volta para a conta. Nos dois casos o valor permanece na conta de liquidação e o pagamento ao destinatário não foi concluído, exigindo intervenção manual (correção dos dados bancários do destinatário e novo envio). O evento é enviado em paralelo ao alerta interno da operação QI Tech; ele não substitui nem bloqueia o tratamento manual. **Event Type:** `liquidation_account.disbursement_failed` **Payload:** ```json { "event_type": "liquidation_account.disbursement_failed", "event_datetime": "2025-07-30T16:05:00Z", "event_data": { "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43", "account_key": "a3f9c1e2-5b7d-4e8a-9c21-6d0f4b8e7a15", "transaction_amount": 154300.75, "refusal_reason": "Estorno de Transferência", "transfer_key": "3f2a91b4-77d0-4c8e-9a12-6b5e0c7d8a44", "transfer_target": "341 3832 38650-3 42.361.523/0001-03 - EMPRESA DESTINATARIA LTDA" } } ``` | Campo | Descrição | |---|---| | `issuer_key` | Chave do emissor dono da conta de liquidação. | | `account_key` | Chave da conta de liquidação de onde a TED saiu. | | `transaction_amount` | Valor da TED recusada ou estornada. | | `refusal_reason` | Motivo da recusa, repassado como recebido do BaaS (por exemplo, `invalid_target_account` ou `Estorno de Transferência`). | | `transfer_key` | Chave da transferência no BaaS, útil para conciliação com o extrato da conta. | | `transfer_target` | Descrição do destinatário (banco, agência, conta e documento). Opcional: só é enviado quando a recusa chega como estorno, pois o BaaS informa o destinatário apenas nesse caso. | ### 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. Um evento recusado é reenviado até 7 vezes ao longo de cerca de 22 horas, então o seu endpoint pode receber o mesmo evento mais de uma vez. Veja como reconhecer uma repetição na [política de reenvio](/documentation/escrituracao/entrega-webhooks#politica-de-reenvio). 4. **Validação de assinatura**: Sempre valide o JWT do header `SIGNATURE` antes de processar o webhook. 5. **Logs e monitoramento**: Mantenha logs detalhados de todos os webhooks recebidos para auditoria e debugging. ## Referências - [Entrega e Reenvio de Webhooks](/documentation/escrituracao/entrega-webhooks) - [Configuração de Webhooks](./introducao/autenticacao_webhooks.md) --- # Inserção de documentos URL: /documentation/iaas/aditamento_recebiveis/envio_documento Envia o termo de aditamento de um aditamento em `pending_document`. Com o documento recebido, o aditamento passa para `pending_approval`. Só é aceito quando a esteira de aditamento exige documento (`amendment_configuration.requires_document: true`). Em esteira sem exigência de documento, a API devolve `AAM000038`. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------------------------------------ | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::caution Gestora A `manager-api` não expõe este endpoint. Veja o que fazer com um aditamento da gestora parado em `pending_document` em [Criação de pedido de aditamento](/documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato). ::: ## 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": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSPj4Kc3RyZWFtCg==" } ``` ### Body Params | Campo | Tipo | Descrição | |-|-|-| | `document_type` * | string | Tipo do documento. Único valor aceito: `amendment_term` | | `document_b64` * | string | Arquivo PDF do termo de aditamento, codificado em Base64 | ## Response STATUS 201 A resposta é o aditamento atualizado, no mesmo formato da [criação do pedido](/documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato#response). ```json title='Response Body' { "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642", "status": "pending_approval", "amendment_type": "all_contract", "amendment_configuration": { "amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22", "fund_class": { "fund_class_key": "", "document_number": "11.222.333/0001-81", "name": "FUNDO EXEMPLO FIDC", "manager": { "manager_key": "", "document_number": "22.333.444/0001-81", "manager_name": "GESTORA EXEMPLO LTDA" }, "accounting_date": "2024-04-01" }, "requires_document": true }, "asset_type": "ccb", "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10", "amendment_date": "2024-04-01", "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "source": "api_integration", "status_history": [ { "status": "pending_document", "event_datetime": "2024-04-01T13:02:45Z" }, { "status": "pending_approval", "event_datetime": "2024-04-01T13:10:02Z" } ] } ``` ## Erros | Status | Código | Quando acontece | |-|-|-| | 400 | `AAM000038` | A esteira de aditamento não exige documento | | 400 | `AAM000026` | `document_type` diferente de `amendment_term` | | 400 | `AAM000025` | `document_b64` não é um Base64 válido | | 404 | `AAM000009` | Aditamento não encontrado para esse fundo e essa esteira | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 a configuração da esteira de aditamento (`amendment_configuration_key`, fornecida pela QI Tech). Nos aditamentos realizados por este sistema é permitida a alteração do fluxo de pagamento, da taxa nominal do contrato ou de ambos. Também é possível definir que o aditamento será realizado juntamente com uma entrada paga pelo devedor. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------------------------------------ | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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", "asset_type": "ccb", "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-28", "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 | Identificador do contrato que está sendo aditado, o mesmo com que ele foi encarteirado. Até 50 caracteres. | Um dos dois: `asset_external_id` ou `contract_number` | | `contract_number` | string | Número do contrato a ser aditado, alternativa ao `asset_external_id`. Até 50 caracteres. | Um dos dois: `asset_external_id` ou `contract_number` | | `asset_type` | string | Tipo do ativo aditado: `ccb` ou `structured_cci` | Sim | | `amendment_date` | string | Data em 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 (maior ou igual a 0) | Não | | `installments` | array | Lista de parcelas do contrato após o aditamento | Depende do `amendment_type` | | `installments[].maturity_date` | string | Data de vencimento da parcela (formato: YYYY-MM-DD) | Sim | | `installments[].face_value` | number | Valor nominal da parcela (maior ou igual a 0) | Sim | | `installments[].installment_number` | integer | Número sequencial da parcela, a partir de 1 | Sim | | `installments[].external_id` | string | Identificador da parcela no seu sistema | Não | | `pre_fixed` | object | Configurações da taxa pré-fixada | Depende do `amendment_type` | | `pre_fixed.monthly_rate` | number | Taxa mensal a ser aplicada | Sim | | `pre_fixed.calendar_base` | string | Base de calendário para cálculo. Único valor aceito: `workdays` | Sim | :::info Identificação do contrato Envie **exatamente um** entre `asset_external_id` e `contract_number`. Sem nenhum dos dois a API devolve `AAM000041`; com os dois, `AAM000042`. ::: ## Response STATUS 201 ```json title='Response Body' { "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642", "status": "pending_document", "amendment_type": "all_contract", "amendment_configuration": { "amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22", "fund_class": { "fund_class_key": "", "document_number": "11.222.333/0001-81", "name": "FUNDO EXEMPLO FIDC", "manager": { "manager_key": "", "document_number": "22.333.444/0001-81", "manager_name": "GESTORA EXEMPLO LTDA" }, "accounting_date": "2024-04-01" }, "requires_document": true }, "asset_type": "ccb", "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10", "amendment_date": "2024-04-01", "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "source": "api_integration", "status_history": [ { "status": "pending_document", "event_datetime": "2024-04-01T13:02:45Z" } ] } ``` O status inicial depende da configuração da esteira de aditamento, definida pela QI Tech: - **`pending_document`** — a esteira exige o termo de aditamento (`amendment_configuration.requires_document: true`, o padrão). O aditamento só avança depois do [envio do documento](/documentation/iaas/aditamento_recebiveis/envio_documento). - **`pending_processing`** — a esteira não exige documento (`requires_document: false`). O aditamento segue direto para processamento. :::caution Gestora e esteira que exige documento O envio do termo de aditamento não está disponível na `manager-api`. Se a gestora cria o aditamento numa esteira que exige documento, ele fica parado em `pending_document`. Para resolver, o termo precisa ser enviado pela consultoria ou pelo cedente vinculados à esteira, ou a gestora pode pedir à QI Tech, em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), uma esteira de aditamento sem exigência de documento. ::: ## Enumerador Tipo de Aditamento | Enumerador | Descrição | |--------------|---------------| | **payment_flow** | Aditamento apenas do fluxo de pagamento | | **nominal_rate** | Aditamento apenas da taxa nominal do contrato | | **all_contract** | Aditamento do fluxo de pagamento e da taxa nominal do contrato | :::caution Atenção Os campos `installments` e `pre_fixed` devem ou não ser enviados de acordo com o tipo de aditamento, conforme a tabela abaixo. Combinação diferente devolve `AAM000008`. ::: | Tipo de aditamento | installments | pre_fixed | |------------------- | ------------ | --------- | | all_contract | Obrigatório | Obrigatório | | nominal_rate | Não deve ser enviado | Obrigatório | | payment_flow | Obrigatório | Não deve ser enviado | ## Status do aditamento | Status | Significado | |-|-| | `pending_document` | Aguardando o termo de aditamento | | `pending_approval` | Termo recebido, aguardando aprovação | | `pending_processing` | Em processamento | | `pending_conciliation` | Aguardando o crédito da entrada (`down_payment_value`) na conta do fundo | | `pending_wallet_update` | Atualizando o contrato na carteira do fundo | | `completed` | Aditamento aplicado ao contrato | | `denied` | Aditamento negado; o motivo vem em `denial_reason` | ## Webhook Quando o aditamento chega a `completed` ou `denied`, a QI Tech envia o webhook `asset_amendment.status_change` à gestora do fundo e ao cedente e à consultoria vinculados à esteira, para quem tiver o webhook configurado. A configuração é feita pela QI Tech: solicite em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). Para validar a assinatura, veja [Autenticação de webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ```json title='Webhook Body' { "webhook_type": "asset_amendment.status_change", "webhook_datetime": "2024-04-02T10:15:00Z", "data": { "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642", "amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22", "fund_class_key": "", "fund_class_document_number": "11.222.333/0001-81", "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10", "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "asset_type": "ccb", "amendment_type": "all_contract", "amendment_date": "2024-04-01", "status": "completed", "down_payment_value": 400.23 } } ``` `down_payment_value` só vem quando o aditamento tem entrada; `denial_reason` só vem quando o status é `denied`. ## Erros | Status | Código | Quando acontece | |-|-|-| | 400 | `QIT000001` | Corpo fora do contrato: campo obrigatório ausente, campo desconhecido, data inválida, valor fora do enum | | 400 | `AAM000041` | Nem `asset_external_id` nem `contract_number` foram enviados | | 400 | `AAM000042` | `asset_external_id` e `contract_number` foram enviados juntos | | 400 | `AAM000008` | `installments`/`pre_fixed` incompatíveis com o `amendment_type` | | 404 | `AAM000003` | Não existe fundo com essa `fund_class_key` | | 404 | `AAM000024` | `amendment_configuration_key` não encontrada para o fundo | | 404 | `AAM000006` | `asset_type` não existe | | 404 | `AAM000007` | Nenhum ativo ativo com esse `asset_external_id` e `asset_type` na carteira do fundo | | 404 | `AAM000043` | Nenhum ativo ativo com esse `contract_number` e `asset_type` | | 409 | `AAM000044` | Mais de um ativo ativo com o mesmo `contract_number`: use `asset_external_id` | | 4xx | `WLT...` ou `AAM000030` | A carteira do fundo recusou o aditamento na validação. O código e a descrição vêm da carteira; sem código da carteira, volta `AAM000030` | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Boletador de Títulos Públicos URL: /documentation/iaas/boletador/boletador_titulos_publicos Registra uma boleta de compra ou venda definitiva, ou de compra compromissada, de título público federal (LFT, LTN, NTN-B, NTN-F) para o fundo. A boleta é registrada no SELIC depois que a gestora a aprova. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::caution A aprovação é feita no portal Toda boleta nasce em `pending_manager_approval`, e a API de integração **não expõe** a aprovação. Para aprovar, acesse o portal da gestora em **Ativos › Negociações › Títulos Públicos**, abra a operação e clique em **Aprovar operação**. Na mesma tela é possível cancelar a operação ou, depois do horário de corte, pedir a liberação de horário. Acompanhe o andamento pela [consulta da operação](/documentation/iaas/boletador/consulta_titulo_publico) ou pela [listagem](/documentation/iaas/boletador/listagem_titulos_publicos). ::: :::info Horário de corte: 16:55 (horário de Brasília) A partir das 16:55 (America/Sao_Paulo, inclusive), nada entra no SELIC no mesmo dia: - o POST só é aceito com `time_exception_reason` preenchido (sem ele, `TTR000054`); - a aprovação no portal também é recusada depois do corte. A gestora pode, então, pedir a liberação de horário, e a boleta fica em `pending_time_exception_approval` até a equipe QI Tech analisar a justificativa e liberar (ou cancelar). Antes das 16:55, `time_exception_reason` é ignorado. ::: ## 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": "33444555", "selic_account_number": "123456789", "document_number": "33.444.555/0001-81" }, "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 | Seu identificador da boleta, único por fundo. Se não informado, será gerado automaticamente (UUID). Máximo de 36 caracteres. Veja [Reenvio e duplicidade](#reenvio-e-duplicidade). | | `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). Em `assignor`, `units` não pode passar das unidades deste título na carteira do fundo. | | `operation_type` | string | obrigatório | Tipo de operação: `outright_operation` (definitiva) ou `buyback_operation` (compromissada). `buyback_operation` exige `operation_part == "assignee"` e que o fundo esteja habilitado para compromissadas. `term_outright_operation` ainda não está disponível (`TTR000042`). | | `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, em forma decimal (`0.144` = 14,4% a.a.). **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`. | | `time_exception_reason` | string | condicional | Justificativa para boletar fora do horário. **Obrigatório a partir das 16:55** (horário de Brasília); ignorado antes disso. Máximo de 500 caracteres. | #### 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`), com dígito verificador válido. | ## 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": "11.222.333/0001-81", "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": "33444555", "document_number": "33.444.555/0001-81", "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: sempre `pending_manager_approval`. Veja os [status da operação](/documentation/iaas/boletador/listagem_titulos_publicos#status-da-operacao). | | `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. | | `yearly_negotiated_rate`, `return_date`, `return_unit_price`, `total_return_value` | number / string | Dados do retorno. Presentes em `buyback_operation`. | | `time_exception_reason` | string | Justificativa de horário. Presente quando a boleta foi enviada depois do corte. | ## Reenvio e duplicidade Em caso de erro, reenvie a requisição. Duplicidade (`TTR000044`) significa que a boleta já existe: localize-a na [listagem](/documentation/iaas/boletador/listagem_titulos_publicos) filtrando por `operation_date` e procurando o seu `external_id` nos itens de `data`. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ## Erros | Status | Código | Quando acontece | |---|---|---| | 409 | `TTR000044` | Já existe boleta com este `external_id` no fundo. | | 400 | `TTR000054` | Envio a partir das 16:55 (horário de Brasília) sem `time_exception_reason`. | | 400 | `TTR000058` | Data inexistente em `operation_date`, `payment_date`, `maturity_date` ou `return_date` (por exemplo, `2025-02-30`). | | 400 | `TTR000016` | `operation_date` diferente da data contábil do fundo. | | 400 | `TTR000011` | `operation_date` não é dia útil. | | 400 | `TTR000021` | `payment_date` diferente de `operation_date` numa operação que não é a termo. | | 400 | `TTR000017` | `payment_date` anterior a `operation_date`. | | 400 | `TTR000010` | `maturity_date` igual ou anterior a `operation_date`. | | 400 | `TTR000057` | Venda (`operation_part: assignor`) com `units` acima das unidades deste título na carteira do fundo. | | 400 | `TTR000037` | Não há título na ANBIMA com este `treasury_type` e `maturity_date`. | | 400 | `TTR000018` / `TTR000019` / `TTR000020` | Compromissada sem `yearly_negotiated_rate`, sem `return_date`, ou com `return_date` igual ou anterior a `operation_date`. | | 400 | `TTR000042` | `operation_type` não implementado, compromissada com `operation_part: assignor`, ou fundo sem compromissada habilitada. | | 400 | `TTR000035` | CNPJ da contraparte inválido. | | 400 | `TTR000027` / `TTR000028` / `TTR000029` / `TTR000038` / `TTR000048` | O cadastro do fundo para títulos públicos está incompleto (conta destino, custodiante, conta SELIC ou carteira). Fale com o time de integração. | | 404 | `TTR000004` | A `fund_class_key` não existe. | | 403 | `TTR000040` | O fundo não pertence à sua gestora. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta de Título Público URL: /documentation/iaas/boletador/consulta_titulo_publico Retorna uma boleta de título público pelo `operation_key`, com o histórico de status. Use para acompanhar a aprovação, o registro no SELIC e a liquidação da operação. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operation/{operation_key} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | | :---- | :---- | :---- | | `fund_class_key` | string | Identificador único do fundo. | | `operation_key` | string | Identificador da operação devolvido na [criação da boleta](/documentation/iaas/boletador/boletador_titulos_publicos). | ## Response STATUS 200 ```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": "11.222.333/0001-81", "accounting_date": "2025-12-04", "internal_transfer_for_main_account": false }, "status": "pending_registration", "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": "33444555", "document_number": "33.444.555/0001-81", "selic_account_number": "123456789" }, "isin_code": "BRSTNCNTB633", "issue_date": "2025-11-04", "operation_data": {}, "status_events": [ { "status": "pending_manager_approval", "metadata": {}, "datetime": "2025-12-04 13:10:00.000000" }, { "status": "pending_registration", "metadata": {}, "datetime": "2025-12-04 13:25:00.000000" } ] } ``` ### Atributos da resposta Os mesmos campos da [criação da boleta](/documentation/iaas/boletador/boletador_titulos_publicos#atributos-da-resposta), mais: | Campo | Tipo | Descrição | | :---- | :---- | :---- | | `status` | string | Status atual. Veja os [status da operação](/documentation/iaas/boletador/listagem_titulos_publicos#status-da-operacao). | | `status_events` | array | Histórico de status, com `status`, `metadata` e `datetime` de cada mudança. | | `selic_operation_id`, `selic_specification_id`, `selic_command_number` | string | Identificadores no SELIC. Presentes depois do registro. | | `yearly_negotiated_rate`, `return_date`, `return_unit_price`, `total_return_value` | number / string | Dados do retorno. Presentes em `buyback_operation`. | | `time_exception_reason` | string | Justificativa de horário, quando houver. | | `time_exception_released_at` | string | Data e hora em que a QI Tech liberou a boleta fora do horário. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `TTR000013` | Não existe operação com este `operation_key` no fundo. | | 404 | `TTR000004` | A `fund_class_key` não existe. | | 403 | `TTR000040` | O fundo não pertence à sua gestora. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Listagem de Títulos Públicos URL: /documentation/iaas/boletador/listagem_titulos_publicos Lista, de forma paginada, as boletas de títulos públicos do fundo, das mais recentes para as mais antigas (por `operation_date`). Para uma operação específica, use a [consulta da operação](/documentation/iaas/boletador/consulta_titulo_publico). :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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. Veja [status da operação](#status-da-operacao). | | `not_status` | string | — | — | Exclui operações com determinado status. | | `status_list` | string | — | — | Lista de status separados por vírgula (ex.: `pending_manager_approval,pending_time_exception_approval`). | | `operation_part` | string | — | — | Filtra pelo papel do fundo (`assignee` ou `assignor`). | | `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": "11.222.333/0001-81", "accounting_date": "2025-04-14", "internal_transfer_for_main_account": false, "custodian": { "name": "CUSTODIANTE EXEMPLO", "document_number": "44.555.666/0001-81", "iselic_number": "44555666" }, "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": "33444555", "document_number": "33.444.555/0001-81", "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. | Cada operação pode trazer ainda, quando já existirem, `selic_operation_id`, `selic_specification_id`, `selic_command_number`, os dados de retorno da compromissada (`yearly_negotiated_rate`, `return_date`, `return_unit_price`, `total_return_value`), `time_exception_reason` e `time_exception_released_at`. ## Status da operação | Etapa | Status | Significado | |---|---|---| | Aprovação | `pending_manager_approval` | Aguardando a aprovação da gestora no portal. Status inicial de toda boleta. | | Aprovação | `pending_time_exception_approval` | A gestora pediu liberação de horário depois das 16:55; aguarda a equipe QI Tech. | | Aprovação | `pending_administrator_approval` | Aguardando o administrador (status legado). | | Pré-matching | `pending_registration`, `pending_counterparty_registration`, `pending_specification`, `pending_counterparty_specification`, `pending_specification_confirmation`, `pending_counterparty_specification_confirmation` | Registro e especificação no SELIC, do lado do fundo e da contraparte. | | Pré-matching | `specification_mismatched` | Os dados lançados pela contraparte no SELIC não batem com os da boleta; a QI Tech trata a divergência. | | Pré-matching | `registration_failed` | O SELIC recusou o registro da boleta. O motivo fica no `metadata` do evento em `status_events`. A QI Tech reenvia ao SELIC, ou a gestora cancela a operação no portal. | | Liquidação | `pending_payment`, `pending_payment_confirmation`, `pending_internal_transfer`, `pending_internal_transfer_confirmation`, `pending_order_creation`, `pending_order_confirmation`, `pending_order_expectation_creation`, `pending_order_expectation_confirmation`, `pending_expectation_confirmation`, `pending_spb_message`, `pending_spb_message_confirmation` | Liquidação financeira da operação. | | Liquidação | `pending_manual_order_validation` | Divergência na liquidação; a QI Tech confere a operação manualmente. | | Encarteiramento | `pending_wallet_inclusion` | Inclusão do título na carteira do fundo. | | Retorno | `pending_buyback_expectation_creation`, `pending_buyback_expectation_confirmation` | Retorno da compromissada (só `buyback_operation`). | | Final | `operation_finished` | Operação concluída. | | Final | `canceled` | Operação cancelada. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `TTR000041` | Valor inválido em `status`, `not_status`, `status_list`, `treasury_type`, `operation_type` ou `operation_part`. | | 400 | `QIT000010` | Parâmetro de query inválido: data fora de `YYYY-MM-DD`, `limit` acima de 500 ou `page` negativo. | | 404 | `TTR000004` | A `fund_class_key` não existe. | | 403 | `TTR000040` | O fundo não pertence à sua gestora. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Do ativo ao boleto URL: /documentation/iaas/boletos/campos_do_boleto Quando a configuração de cessão tem **cobrança por boleto**, a QI Tech registra automaticamente um boleto na QI SCD para cada direito creditório cedido. Os dados do boleto vêm do que você enviou na inserção do ativo. Esta página mostra de onde vem cada campo e quais deles você usa para identificar e conciliar o boleto no seu sistema. Vale para os direitos creditórios **duplicata mercantil**, **duplicata de serviços**, **CT-e** e **contrato descontado**. Cada ativo gera **um** boleto. No contrato descontado, como cada ativo é uma parcela, cada parcela tem o seu boleto. O [contrato parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract) também gera um boleto por parcela, com os dados de cada parcela da lista `installments`. Nele, o número de controle do participante de cada boleto é o `external_id` da parcela, que precisa ser único e ter até 25 caracteres. O restante desta página trata dos direitos creditórios. ## Quando o boleto é registrado O boleto não é registrado na inserção do ativo. Ele é registrado depois que a cessão é paga, quando o ativo entra na carteira do fundo. A confirmação do registro chega no processamento do retorno bancário do dia útil seguinte. O fluxo completo está em [Boletos — Início](/documentation/iaas/boletos/inicio). Por isso, os campos do boleto precisam estar certos **já na inserção**. Depois que o ativo é cedido, alterações no boleto (vencimento, juros, multa, abatimento) são feitas pelas [instruções de boleto](/documentation/iaas/boletos/instrucoes_boleto), não reenviando o ativo. :::caution Vencimento do boleto não é vencimento do ativo A instrução de alteração de vencimento muda só o boleto. O ativo continua com o vencimento original na carteira do fundo, no relatório de estoque e na contagem de atraso. Para mudar também o vencimento do ativo, informe uma prorrogação (`asset_extension`, com `new_maturity_date`) na [liquidação de ativos](/documentation/iaas/liquidacao_ativos/ativos/ativos). A prorrogação vale para direitos creditórios, inclusive o contrato descontado, e não existe para o contrato parcelado. ::: ## De onde vem cada campo Os caminhos abaixo são relativos ao objeto `discounted_credit_right` do corpo da requisição de inserção. ### Campos de controle do cliente São os campos que você escolhe livremente e que voltam na consulta do boleto. Use-os para ligar o boleto ao registro do seu sistema. | Campo do ativo | Campo do boleto | Regra | |---|---|---| | `participant_control_number` | Número de controle do participante | Até 25 caracteres. Só letras, números e `_` são mantidos; os demais caracteres são removidos. Precisa ser único na carteira de cobrança. | | `order_number` | Número do documento (seu número) | O boleto recebe apenas os **10 últimos caracteres**. O valor completo continua no ativo. | | `bankslip.our_number.number` | Nosso número | Opcional. Envie só quando a sua carteira de cobrança prevê nosso número emitido pelo cliente. Sem ele, o nosso número é gerado no registro. | :::caution Envie sempre o `participant_control_number` em cessão com boleto Na inserção do ativo o campo é opcional, mas na cobrança ele é a chave do boleto: a carteira de cobrança não aceita dois boletos com o mesmo número de controle, e ativos **sem** o campo contam como repetidos entre si. Na prática, só o primeiro ativo sem número de controle tem boleto registrado. Gere um valor único por ativo, com até 25 caracteres alfanuméricos — por exemplo, derivado do seu `external_id`. ::: ### Valor, vencimento e encargos | Campo do ativo | Campo do boleto | Regra | |---|---|---| | `face_value` | Valor do boleto | | | `maturity_date` | Vencimento | | | `delay.fine` | Multa | Precisa ser percentual (`fine_type: percentage`). Multa com `percentage_value` igual a zero não entra no boleto. | | `delay.interest.pre_fixed` | Juros de mora | Cobrados por dia de atraso, em valor: `face_value` × taxa diária. Se você enviar `monthly_rate`, ela é convertida em taxa diária simples na `calendar_base` informada. Taxa igual a zero não entra no boleto. | Se o ativo não trouxer `delay`, o boleto usa a multa e os juros cadastrados na configuração de cobrança do fundo. ### Pagador e sacador | Origem | Campo do boleto | Regra | |---|---|---| | `borrower.name`, `borrower.document_number`, `borrower.person_type` | Pagador | O documento vai sem pontuação. | | `borrower.address` | Endereço do pagador | Só vai para o boleto se estiverem preenchidos `street`, `number`, `neighborhood`, `postal_code`, `city` e `uf`. Faltando qualquer um, o boleto é registrado sem endereço. `complement` é opcional. | | Cedente da configuração de cessão | Sacador/avalista | Vem do cadastro do cedente, não do corpo da requisição. Aparece quando a carteira de cobrança prevê o cedente como sacador. | ### Campos que não vão para o boleto Estes campos ficam no ativo e voltam na consulta do ativo, mas não aparecem no boleto: - `external_id` — use o `participant_control_number` como ponte entre o boleto e o ativo; - `installment_number`; - o objeto `contract` do contrato descontado (`number`, `issue_date`, `total_face_value`, `number_of_installments`); - o objeto `invoice` das duplicatas e do CT-e. ## Exemplo Trecho de um contrato descontado inserido numa cessão com boleto: ```json { "discounted_credit_right": { "external_id": "parcela-958431587-01", "face_value": 1231.21, "maturity_date": "2025-12-10", "installment_number": 1, "participant_control_number": "CT958431587P01", "order_number": "2023000958431587", "delay": { "fine": { "fine_type": "percentage", "percentage_value": 0.02 }, "interest": { "method": "pre_fixed", "pre_fixed": { "monthly_rate": 0.01, "calendar_base": "calendar_360" } } } } } ``` O boleto registrado na QI SCD fica assim: | Campo do boleto | Valor | Por quê | |---|---|---| | Valor | R$ 1.231,21 | `face_value` | | Vencimento | 10/12/2025 | `maturity_date` | | Número de controle do participante | `CT958431587P01` | `participant_control_number`, como enviado (só tem letras e números) | | Número do documento | `0958431587` | os 10 últimos caracteres de `order_number` | | Multa | 2% | `fine.percentage_value` de 0,02 | | Juros de mora | R$ 0,41 por dia de atraso | 1% ao mês × 12 ÷ 360 dias × R$ 1.231,21 | Nem `external_id`, nem `installment_number`, nem o objeto `contract` aparecem no boleto. Para achar o ativo a partir do boleto, use o número de controle do participante. ## Conferindo o boleto Consulte o boleto registrado em [Recuperando Boleto e Segunda Via](/documentation/iaas/boletos/recuperar_boleto). A resposta traz os dois números de controle: - `external_participant_control_number` — o valor exatamente como você enviou; - `participant_control_number` — o valor depois da limpeza de caracteres, que é o que está no boleto. Para avisos de registro, pagamento e baixa, veja os [webhooks de boleto](/documentation/iaas/boletos/webhook). --- # 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 da conta de 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, um boleto por ativo (ou por parcela, nos ativos parcelados). - Os dados do boleto vêm do que foi enviado na inserção do ativo: pagador, valor, vencimento, encargos e os seus números de controle. - Veja de onde vem cada campo em [Do ativo ao boleto](/documentation/iaas/boletos/campos_do_boleto). 3. **Confirmação do Registro** - A confirmação do registro do boleto é feita no próximo 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 título seja feito por uma baixa cedente ou substituição, o boleto é baixado automaticamente :::caution 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 sejam feitas as devidas liberações, tanto em sandbox quanto em produção. --- # 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------- | | Gestora | `manager-api` | Leitura e escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::caution Quais boletos aceitam instrução Só boletos em `pending_registration` ou `registered`, emitidos pela QI Tech (configuração com tipo de emissor `internal`; veja [configurações de boleto](/documentation/iaas/boletos/recuperar_configuracoes_boleto#tipo-de-emissor)), aceitam instrução. Para os demais, a API devolve `BSC000009` (boleto fora desses status) ou `BSC000106` (outro emissor). ::: ## 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": 0.015, "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 em decimal (`0.015` = 1,5% ao mês). | | `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 que `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": "11.222.333/0001-81", "name": "Sample Fund Class", "manager": { "name": "Sample Manager", "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153", "document_number": "11.222.333/0001-81" } } } }, "due_date": "2026-12-31", "face_value": 629.33, "status": "registered", "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG", "borrower": { "document_number": "969.698.790-03", "name": "Tomador Exemplo", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Cedente LTDA", "document_number": "33.444.555/0001-81", "person_type": "legal_person" }, "bankslip_type": "simple_collection", "collection_type": "standard", "delay": null, "our_number": 12345, "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", "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: `simple_collection` ou `non_vinculated`. | | `collection_type` | string | Modalidade de cobrança: `standard` ou `qr_code_allowed`. | | `delay` | object | Dados de mora do boleto, quando aplicável. | | `order_number` | string | Número do pedido, quando disponível. | | `our_number` | number | 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. | | `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. | --- ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `BSC000009` | O boleto não existe nesta configuração, ou não está em `pending_registration` ou `registered`. | | 400 | `BSC000106` | O boleto não foi emitido pela QI Tech; instruções não são aceitas. | | 400 | `BSC000115` / `BSC000116` | `due_date_extension` com nova data no passado ou não posterior ao vencimento atual. | | 400 | `BSC000123` | Instrução com valor zerado (por exemplo, `monthly_rate` ou `percentage_value` igual a `0`). | | 404 | `BSC000006` | A `fund_class_key` não existe. | | 403 | `BSC000036` | O fundo não pertence ao seu perfil. | | 400 | `QIT000001` | Corpo inválido para o `occurrence_type` informado. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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` (`BSC000006`) caso não exista. | | `bankslip_profile_key` | Chave do perfil de boleto, que deve pertencer à classe de fundo. Retorna `404` (`BSC000008`) 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://URL_DO_ARQUIVO_CNAB", "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://URL_DO_ARQUIVO_CNAB", "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 | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `BSC000008` | A carteira de cobrança não existe neste fundo. | | 404 | `BSC000006` | A `fund_class_key` não existe. | | 403 | `BSC000036` | O fundo não pertence ao seu perfil. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Recuperação de Boleto e Segunda via URL: /documentation/iaas/boletos/recuperar_boleto ## Consultar boleto ### Request :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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", "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": "11.222.333/0001-81", "name": "Sample_Name", "manager": { "name": "Sample name", "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153", "document_number": "11.222.333/0001-81" } } } }, "due_date": "2026-04-21", "face_value": 629.33, "status": "pending_registration", "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG", "borrower": { "document_number": "969.698.790-03", "name": "Tomador", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Assignor LTDA", "document_number": "33.444.555/0001-81", "person_type": "legal_person" }, "bankslip_type": "simple_collection", "collection_type": "standard", "delay": null, "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", "issue_date": "2025-01-17", "maturity_date": "2026-09-17", "face_value": 629.33, "order_number": "49761-1" } ], "bankslip_url": "https://URL_DO_PDF_DO_BOLETO" } ``` ### Bankslip | Campo | Tipo | Descrição | |---------------------------------------|----------|----------------------------------------------------------------------| | `bankslip_key` | string | Identificador único do boleto. | | `external_participant_control_number` | string | Número de controle externo do participante. | | `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. | | `bankslip_type` | string | Tipo do boleto: `simple_collection` ou `non_vinculated`. | | `collection_type` | string | Modalidade de cobrança: `standard` ou `qr_code_allowed`. | | `delay` | object | Dados de mora do boleto (juros e multa), quando configurados. | | `order_number` | string | Número do pedido. Presente quando houver. | | `our_number` | number | Nosso número. Presente quando houver. | | `our_number_digit` | string | Dígito verificador do nosso número. Presente quando houver. | | `digitable_line` | string | Linha digitável. Presente quando houver. | | `barcode` | string | Código de barras. Presente quando houver. | | `qr_code` | object | Dados do QR Code do boleto. Presente quando houver. | | `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` | string | Link do PDF do boleto (segunda via). Ausente quando o PDF ainda não está disponível no banco. | ### 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. | | `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. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `BSC000009` | Não existe boleto com este `bankslip_key` na carteira informada. | | 404 | `BSC000006` | A `fund_class_key` não existe. | | 403 | `BSC000036` | O fundo não pertence ao seu perfil. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Recuperação de Boletos URL: /documentation/iaas/boletos/recuperar_boletos ## Lista de Boletos ### Request :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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. Padrão: `10`. | | `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. | | `status` | Status do boleto: `created`, `pending_registration`, `registered`, `waiting_payment_confirmation`, `paid`, `paid_via_qr_code`, `rejected`, `written_off` ou `registration_failed`. | | `from_due_date` | Vencimento a partir desta data (`YYYY-MM-DD`). | | `to_due_date` | Vencimento até esta data (`YYYY-MM-DD`). | | `bankslip_type` | Tipo do boleto: `simple_collection` ou `non_vinculated`. | | `asset_key` | Chave do ativo vinculado ao boleto. | ### Response Response Body ```json title='Response Body' { "data": [ { "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": "11.222.333/0001-81", "name": "Sample_Name", "manager": { "name": "Sample name", "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153", "document_number": "11.222.333/0001-81" } } } }, "due_date": "2024-02-17", "face_value": 629.33, "status": "pending_registration", "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG", "borrower": { "document_number": "969.698.790-03", "name": "Tomador", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Assignor LTDA", "document_number": "33.444.555/0001-81", "person_type": "legal_person" }, "bankslip_type": "simple_collection", "collection_type": "standard", "delay": null, "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", "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", "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": "11.222.333/0001-81", "name": "Sample_Name", "manager": { "name": "Sample name", "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153", "document_number": "11.222.333/0001-81" } } } }, "due_date": "2024-02-17", "face_value": 629.33, "status": "pending_registration", "participant_control_number": "TBFBDWKTEWJ7UTR6CPL4BAE4P", "borrower": { "document_number": "969.698.790-03", "name": "mgkstsdibe", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Assignor LTDA", "document_number": "33.444.555/0001-81", "person_type": "legal_person" }, "bankslip_type": "simple_collection", "collection_type": "standard", "delay": null, "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", "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. | | `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. | | `bankslip_type` | string | Tipo do boleto: `simple_collection` ou `non_vinculated`. | | `collection_type` | string | Modalidade de cobrança: `standard` ou `qr_code_allowed`. | | `delay` | object | Dados de mora do boleto (juros e multa), quando configurados. | | `order_number` | string | Número do pedido. Presente quando houver. | | `our_number` | number | Nosso número. Presente quando houver. | | `our_number_digit` | string | Dígito verificador do nosso número. Presente quando houver. | | `digitable_line` | string | Linha digitável. Presente quando houver. | | `barcode` | string | Código de barras. Presente quando houver. | | `qr_code` | object | Dados do QR Code do boleto. Presente quando houver. | | `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. | | `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. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `BSC000002` | `borrower_document_number` ou `assignor_document_number` não é um CPF/CNPJ válido. | | 404 | `BSC000006` | A `fund_class_key` não existe. | | 403 | `BSC000036` | O fundo não pertence ao seu perfil. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 fundo precisa ser da gestora autenticada ou estar vinculado à consultoria autenticada. ### Request :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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` (`BSC000006`) 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. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `BSC000006` | A `fund_class_key` não existe. | | 403 | `BSC000036` | O fundo não pertence ao seu perfil. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 fundo precisa ser da gestora autenticada ou estar vinculado à consultoria autenticada. ### Request :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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` (`BSC000006`) caso não exista. | | `bankslip_profile_key` | Chave da carteira de cobrança, que deve pertencer à classe de fundo. Retorna `404` (`BSC000007`) 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 `BSC000023`. | | `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 | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `BSC000007` | A carteira de cobrança não existe neste fundo. | | 400 | `BSC000023` | `issuer_type` com valor desconhecido. | | 404 | `BSC000006` | A `fund_class_key` não existe. | | 403 | `BSC000036` | O fundo não pertence ao seu perfil. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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.dtvm@qitech.com.br](mailto:integracao.dtvm@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": "11.222.333/0001-81", "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": "969.698.790-03", "name": "Nome do Sacado", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Nome do Cedente", "document_number": "33.444.555/0001-81", "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": "11.222.333/0001-81", "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": "969.698.790-03", "name": "Nome do Sacado", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Nome do Cedente", "document_number": "33.444.555/0001-81", "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": "11.222.333/0001-81", "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": "969.698.790-03", "name": "Nome do Sacado", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Nome do Cedente", "document_number": "33.444.555/0001-81", "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": "11.222.333/0001-81", "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": "969.698.790-03", "name": "Nome do Sacado", "person_type": "natural_person", "address": { "postal_code": "05425-020" } }, "assignor": { "name": "Nome do Cedente", "document_number": "33.444.555/0001-81", "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 Aprova ou reprova a carteira de validação. Só é aceito para carteiras no status `pending_confirmation` — o status em que a carteira fica quando está pronta para a sua análise e em que a gestora recebe o [webhook de mudança de status](/documentation/iaas/composicao_carteira/webhooks). :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/composition/COMPOSITION_KEY MÉTODO PUT ```json title='Request Body — aprovar' { "new_status": "confirmed" } ``` ```json title='Request Body — reprovar' { "new_status": "reproved_by_agent", "reproved_reason": "Cota divergente do controle interno da gestora." } ``` | Campo | Tipo | Obrigatório | Descrição | | ----------------- | ------ | --------------------------------------------- | ----------------------------------------------------- | | `new_status` | string | Sim | Novo status da carteira. Ver enumeradores abaixo. | | `reproved_reason` | string | Sim, quando `new_status` é `reproved_by_agent` | Motivo da reprovação, de 1 a 255 caracteres. | ## Enumeradores do "new_status" | Enumerador | Descrição | | ------------------- | ------------------------------------------------------------------------- | | `confirmed` | Aprova a carteira. | | `reproved_by_agent` | Reprova a carteira, registrando o motivo informado em `reproved_reason`. | | `reproved` | Reprova a carteira sem exigir motivo. Prefira `reproved_by_agent`. | O motivo da reprovação fica registrado no histórico da carteira: o campo `status_events` da [consulta da carteira](/documentation/iaas/composicao_carteira/recuperar_carteira#informacoes-da-carteira) traz cada mudança de status com o seu `metadata`. ## Response Em caso de sucesso, a API devolve **204 No Content**, sem corpo. Consulte a carteira para ver o novo status. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | --------------------------------------------------------------------------------------------------- | | 404 | `CMP000013` | A carteira não está em `pending_confirmation` (já foi aprovada, reprovada ou ainda está em processamento). | | 404 | `CMP000010` | `new_status` diferente de `confirmed`, `reproved_by_agent` ou `reproved`. | | 404 | `CMP000025` | `new_status` é `reproved_by_agent` e `reproved_reason` não foi enviado. | | 404 | `CMP000012` | Não existe carteira com essa `composition_key` na classe informada. | | 404 | `CMP000001` | Não existe classe com essa `fund_class_key`. | | 409 | `CMP000022` | Já existe outra carteira da mesma classe, data e tipo no status pedido. | | 400 | `QIT000001` | Corpo fora do contrato: `new_status` ausente ou fora dos valores aceitos, ou campo não previsto. | | 400 | `QIT000004` | A `fund_class_key` é de uma classe de outra gestora. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Carteira - Baixar a Carteira URL: /documentation/iaas/composicao_carteira/baixar_carteira ## Introdução Este recurso gera, de forma síncrona, um relatório da classe de fundo e o devolve em base64. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------------------------ | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Carteiras | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /composition/fund_class/FUND_CLASS_KEY/report MÉTODO POST STATUS 201 ```json title='Request Body' { "report_type": "wallet_composition_by_composition", "composition_type": "final_quota", "reference_date": "2025-01-20" } ``` | Campo | Tipo | Obrigatório | Descrição | | ------------------ | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `report_type` | string | Sim | Relatório a gerar. Ver tabela abaixo. | | `reference_date` | string | Sim | Data de referência, no formato `YYYY-MM-DD`. | | `composition_type` | string | Para relatórios da carteira, este ou `composition_key` | `pre_quota`, `final_quota` ou `opening_quota`. Usa a carteira desse tipo na `reference_date`. | | `composition_key` | string | Para relatórios da carteira, este ou `composition_type` | Chave de uma carteira específica. | ### Relatórios disponíveis | `report_type` | Conteúdo | Precisa identificar a carteira | | --------------------------------------- | ------------------------------------------ | ------------------------------ | | `wallet_composition_by_composition` | Carteira em planilha (`.xlsx`) | Sim | | `wallet_composition_by_composition_pdf` | Carteira em PDF | Sim | | `xml_401_by_composition` | XML 4.01 da carteira — não aceita `pre_quota` | Sim | | `xml_5_by_composition` | XML 5.0 da carteira — não aceita `pre_quota` | Sim | | `cash_account_demonstrative` | Demonstrativo da conta caixa | Não (só `reference_date`) | | `pmts_reconciliation` | Conciliação de PMTs | Não (só `reference_date`) | Os demais valores aceitos pelo contrato (`wallet_composition_a_pagar`, `assets_wallet_composition_legacy`, `wallet_asset_installments_settlement_legacy`, `settlements_status_by_reference_date`, `discarded_settlements_on_payment_batch`) não são gerados por este endpoint e devolvem `CMP000027`. ### Response ```json title='Response Body' { "document_b64": "UEsDBBQABgAIAAAAIQ..." } ``` `document_b64` é o arquivo do relatório codificado em base64. :::caution Atenção Para os relatórios da carteira, ela precisa estar em **`confirmed`**, **`pending_confirmation`** ou **`reproved_by_agent`**. Em outro status, a resposta é **400** (`CMP000015`). ::: ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ----------------------------------------------------------------------------------------------------- | | 400 | `CMP000015` | A carteira não está em `confirmed`, `pending_confirmation` ou `reproved_by_agent`. | | 400 | `CMP000044` | Relatório da carteira sem `composition_key` nem `composition_type`. | | 400 | `CMP000027` | `report_type` não é gerado por este endpoint. | | 404 | `CMP000026` | `xml_401_by_composition` ou `xml_5_by_composition` pedido para uma carteira `pre_quota`. | | 404 | `CMP000012` | Não existe carteira com a `composition_key` informada, ou do `composition_type` na `reference_date`. | | 400 | `CMP000014` | O gerador de relatórios recusou o pedido; a `description` traz o motivo. | | 400 | `QIT000001` | Corpo fora do contrato: campo obrigatório ausente, data fora do formato ou campo não previsto. | | 400 | `QIT000004` | A `fund_class_key` é de uma classe de outra gestora. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 DTVM 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** (`composition_type` = `pre_quota`), e uma vez que esta é aprovada, seguimos para a disponibilização da **Carteira Final** (`composition_type` = `final_quota`). 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. :::caution É 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. ::: Quando a carteira fica pronta para a sua análise, ela entra no status `pending_confirmation` e a gestora recebe o [webhook de mudança de status](/documentation/iaas/composicao_carteira/webhooks). A aprovação ou reprovação é feita em [Aprovação de carteira](/documentation/iaas/composicao_carteira/aprovar_carteira). 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 sandbox quanto em produção. --- # Carteira - Recuperação da Carteira URL: /documentation/iaas/composicao_carteira/recuperar_carteira --- ## Lista de Carteiras Lista as carteiras de uma classe de fundo, paginadas, da data mais recente para a mais antiga. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Carteiras | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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 carteira: `pre_quota`, `final_quota` ou `opening_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`. | | `page` | Página a recuperar, começando em `0`. Padrão: `0`. | | `limit` | Itens por página. Padrão: `20`; máximo: `100`. | `status` e `not_status` aceitam mais de um valor (`?status=pending_confirmation&status=confirmed`). Os status possíveis de uma carteira são `created`, `pending_processing`, `pending_validation`, `pending_variation_reason`, `pending_quota_performance`, `pending_confirmation`, `confirmed`, `reproved`, `reproved_by_agent` e `reprocessed`. A carteira que espera a sua aprovação está em `pending_confirmation`. :::caution Atenção Existem duas formas de filtrar por data: - Uma **data específica**, enviando o query param `reference_date`. - Um **período**, enviando os query params `start_date` e `end_date` (os dois juntos). ::: ```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": "11.222.333/0001-81" } }, { "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": "11.222.333/0001-81" } } ], "limit": 20, "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 Retorna a carteira completa: séries de emissão, ativos, a receber, a pagar, contas e o histórico de status. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Carteiras | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "11.222.333/0001-81" }, "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](#assets)** | | `consolidated_assets` | array | Lista de objetos de **[Consolidated Assets](#consolidated-assets)** | | `receivables` | array | Lista de objetos de **[Receivables](#receivables)** | | `payables` | array | Lista de objetos de **[Payables](#payables)** | | `cash_accounts` | array | Lista de objetos de **[Cash Accounts](#cash-accounts)** | | `status_events` | array | Histórico de status da carteira. Ver **[Status Events](#status-events)** | ### 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 | ### Status Events | Campo | Tipo | Descrição | |------------------|--------|---------------------------------------------------------------------------------------------------------| | `status` | string | Status assumido pela carteira | | `event_datetime` | string | Data e hora da mudança de status | | `metadata` | object | Dados da mudança, quando houver. Numa reprovação pela gestora, traz o `reproved_reason` informado | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------------------------- | | 400 | `CMP000016` | Listagem com só um de `start_date` e `end_date`. | | 400 | `CMP000017` | Listagem com `end_date` anterior a `start_date`. | | 400 | `QIT000004` | A `fund_class_key` é de uma classe de outra gestora. | | 400 | `QIT000010` | Parâmetro de query inválido: `limit` acima de 100, `page` negativo ou `reference_date` fora de `YYYY-MM-DD`. | | 404 | `CMP000001` | Não existe classe com essa `fund_class_key`. | | 404 | `CMP000012` | Consulta de uma `composition_key` que não existe na classe informada. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Webhooks da carteira URL: /documentation/iaas/composicao_carteira/webhooks A carteira emite o webhook `composition.status_change` quando muda para alguns status. Ele é enviado **só para a gestora** da classe de fundo. Assinatura, headers e política de reenvio são os mesmos de todos os webhooks: veja [Autenticação de webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ## Quando é enviado | `status` | Quando | O que fazer | | ---------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `pending_confirmation` | A carteira está pronta e aguarda a aprovação da gestora. | Analise a carteira e [aprove ou reprove](/documentation/iaas/composicao_carteira/aprovar_carteira). | | `confirmed` | A carteira foi confirmada: a de validação, ao ser aprovada pela gestora (ou automaticamente, se a classe tem aprovação automática); a final, ao fim do processamento. | Consulte ou [baixe](/documentation/iaas/composicao_carteira/baixar_carteira) a carteira. | | `reprocessed` | Uma carteira já confirmada foi reprocessada pela QI DTVM. | A carteira confirmada deixa de valer. Liste as carteiras da mesma data para obter a versão vigente. | Reprovações (`reproved`, `reproved_by_agent`) e os status intermediários de processamento não emitem webhook. ## Payload ```json title='Webhook Body' { "webhook_type": "composition.status_change", "webhook_datetime": "2025-01-22T20:30:23.459123+00:00", "data": { "composition_key": "f2208257-1489-4937-8862-031bca34016f", "composition_date": "2025-01-21", "composition_type": "pre_quota", "status": "pending_confirmation", "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860" } } ``` | Campo | Tipo | Descrição | | ----------------------- | ------ | ---------------------------------------------------------------------- | | `webhook_type` | string | Sempre `composition.status_change`. | | `webhook_datetime` | string | Data e hora do envio, em UTC (ISO 8601). | | `data.composition_key` | string | Chave da carteira. Use-a para consultar a carteira completa. | | `data.composition_date` | string | Data de referência da carteira (`YYYY-MM-DD`). | | `data.composition_type` | string | `pre_quota`, `final_quota` ou `opening_quota`. | | `data.status` | string | Novo status da carteira. | | `data.fund_class_key` | string | Chave da classe de fundo. | ## Configuração A URL do webhook e os tipos de carteira que geram notificação (por exemplo, só `pre_quota`) são configurados pela QI DTVM — não há endpoint para isso na sua integração. Solicite ao time de integração em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). --- # Consulta de Aplicações Financeiras por Classe de Fundo URL: /documentation/iaas/cotas_de_fundo/consulta_paginada_aplicacoes_financeiras Retorna, paginadas, as aplicações financeiras que a sua classe de fundo fez em cotas de outros fundos. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Aplicações, Resgates e Séries | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_applications MÉTODO GET ### Query Params | Parâmetro | Tipo | Descrição | | ---------------------------------- | ----- | -------------------------------------------------------------------------------------------------- | | `page` | int | Número da página, a partir de `0`. Padrão: `0`. | | `limit` | int | Registros por página. Padrão: `10`. Máximo: `50`. | | `quotation_date` | data | Data de cotização exata (`YYYY-MM-DD`). | | `quotation_date_from` | data | Data de cotização inicial (`YYYY-MM-DD`). | | `quotation_date_to` | data | Data de cotização final (`YYYY-MM-DD`). Não pode ser anterior a `quotation_date_from`. | | `financial_application_status` | lista | Status a incluir, separados por vírgula (ex.: `pending_manager_approval,pending_payment`). | | `not_financial_application_status` | lista | Status a excluir, separados por vírgula. | | `document_number` | string | CNPJ da classe do fundo investido, com pontuação. Correspondência exata. | | `internal_codes` | lista | Códigos internos das séries investidas, separados por vírgula. | | `asset_type` | string | Tipo do ativo (ex.: `fidc_fund_quota`, `multi_market_fund_quota`). | | `sub_class_name` | lista | Nomes de subclasse da série investida, separados por vírgula (sem diferenciar acento e maiúscula). | | `search` | string | Busca parcial no nome curto do fundo investido, no nome da série, no código interno ou no CNPJ. | Os status possíveis estão em [Criar Aplicação Financeira](/documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras#response). ## 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) | | payment_date | string | Data de pagamento (YYYY-MM-DD) | | payment_method | string | `wire_transfer` ou `pix` | | payment_type | string | `transfer` ou `automatic_debit` | | status | string | Status da aplicação | | external_financial_application_key | string | Identificador externo da aplicação financeira | | iof_amount | float | IOF da aplicação; presente quando calculado | | number_of_quotas | float | Quantidade de cotas; presente após a cotização | | 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 | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------ | | 400 | `TFQ000218` | `quotation_date_from` posterior a `quotation_date_to`. | | 403 | `TFQ000054` | A classe de fundo não pertence à sua gestora. | | 404 | `TFQ000005` | Classe de fundo não encontrada. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta de Resgates por Classe de Fundo URL: /documentation/iaas/cotas_de_fundo/consulta_paginada_resgates Retorna, paginadas, os pedidos de resgate que a sua classe de fundo fez em cotas de outros fundos. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Aplicações, Resgates e Séries | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_requests MÉTODO GET ### Query Params | Parâmetro | Tipo | Descrição | | ------------------------------- | ------ | -------------------------------------------------------------------------------------------------- | | `page` | int | Número da página, a partir de `0`. Padrão: `0`. | | `limit` | int | Registros por página. Padrão: `10`. Máximo: `50`. | | `quotation_date` | data | Data de cotização exata (`YYYY-MM-DD`). | | `quotation_date_from` | data | Data de cotização inicial (`YYYY-MM-DD`). | | `quotation_date_to` | data | Data de cotização final (`YYYY-MM-DD`). | | `redemption_request_status` | lista | Status a incluir, separados por vírgula. | | `not_redemption_request_status` | lista | Status a excluir, separados por vírgula. | | `document_number` | string | CNPJ da classe do fundo investido, com pontuação. Correspondência exata. | | `internal_codes` | lista | Códigos internos das séries investidas, separados por vírgula. | | `asset_type` | string | Tipo do ativo (ex.: `fidc_fund_quota`, `multi_market_fund_quota`). | | `sub_class_name` | lista | Nomes de subclasse da série investida, separados por vírgula (sem diferenciar acento e maiúscula). | | `search` | string | Busca parcial no nome curto do fundo investido, no nome da série, no código interno ou no CNPJ. | Os status possíveis estão em [Criar Pedido de Resgate](/documentation/iaas/cotas_de_fundo/operacao_resgates#response). ## 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" } } } }, "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 pedido de resgate (ex: confirmed) | | quotation_date | string | Data da cotização do resgate | | payment_date | string | Data do pagamento do resgate | | amount | float | Valor resgatado | | redeem_all | boolean | `true` quando o pedido é de resgate total; omitido nos demais | | cash_expectation | JSON | Expectativa de caixa do resgate; presente quando criada | | 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 | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------ | | 400 | `TFQ000218` | `quotation_date_from` posterior a `quotation_date_to`. | | 403 | `TFQ000054` | A classe de fundo não pertence à sua gestora. | | 404 | `TFQ000005` | Classe de fundo não encontrada. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta de Séries de Emissão URL: /documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao Retorna, paginadas, as séries de emissão de fundos cadastradas para aplicação em cotas. Use o `issuance_serie_key` devolvido para [criar uma aplicação](/documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras) ou [um pedido de resgate](/documentation/iaas/cotas_de_fundo/operacao_resgates). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Aplicações, Resgates e Séries | Na consultoria, a lista traz só as séries das classes de fundo vinculadas à consultoria; sem vínculo, `data` vem vazio. URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_fund_quota/issuance_series MÉTODO GET ### Query Params | Parâmetro | Tipo | Descrição | | ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | | `page` | int | Número da página, a partir de `0`. Padrão: `0`. | | `limit` | int | Registros por página. Padrão: `10`. Máximo: `100`. | | `fund_class_document_number` | string | CNPJ do fundo da série, com pontuação (ex.: `11.222.333/0001-81`). Correspondência parcial. | | `fund_class_name` | string | Nome do fundo da série. Correspondência parcial. | | `internal_code` | string | Código interno da série. Correspondência parcial. | | `internal_codes` | lista | Códigos internos, separados por vírgula. Correspondência exata. | | `status` | lista | Status a incluir: `created`, `active`, `inactive`, `pre_operational`. Sem este filtro, séries `inactive` não são retornadas. | | `not_status` | lista | Status a excluir, separados por vírgula. | | `sub_class_name` | lista | Nomes de subclasse, separados por vírgula (sem diferenciar acento e maiúscula). | | `search` | string | Busca parcial no nome curto do fundo, no nome da série, no código interno ou no CNPJ. | ## 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", "condominium_type": "open_ended", "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", "asset_type": "multi_market_fund_quota", "payment_type": "transfer", "status": "active", "financial_institution_code": "329", "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", "status": "active" }, "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 | | condominium_type | string | `open_ended` (aberto) ou `close_ended` (fechado). Só séries `open_ended` aceitam resgate. | | asset_type | string | Tipo do ativo (ex.: `multi_market_fund_quota`) | | status | string | `created`, `active`, `inactive` ou `pre_operational` | | financial_institution_code | string | Código da instituição financeira usada no débito automático | ### Administrator | Campo | Tipo | Descrição | | ------------------ | ------ | ---------------------------- | | administrator_key | string | Chave única do administrador | | name | string | Nome do administrador | | document_number | string | CNPJ do administrador | | status | string | `active` ou `blocked` | ### 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) | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------ | | 404 | `TFQ000002` | A gestora da integração não está cadastrada na plataforma. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta de Posições em Cotas de Fundo URL: /documentation/iaas/cotas_de_fundo/consulta_posicoes_cotas_de_fundo 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). :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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=11.222.333/0001-81 ``` :::info 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 (substitua `11.222.333/0001-81` pelo CNPJ do fundo de zeragem): ```python title="Posição em um fundo de zeragem" GET /wallet/fund_class/{fund_class_key}/fund_quota_positions?document_number=11.222.333/0001-81 ``` O `total_current_value` da resposta é o saldo aplicado, em reais, na data indicada por `last_mtm_date`. :::info 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). ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ----------------------------------------------------- | | 403 | `WLT000098` | A classe de fundo não pertence à gestora da integração. | | 404 | `WLT000001` | Classe de fundo não encontrada. | | 404 | `WLT000066` | Gestora não encontrada. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 Cria uma aplicação da sua classe de fundo em cotas de outro fundo (série de emissão investida) e permite aprovar ou cancelar a aplicação enquanto ela não foi processada. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Aplicações e Resgates | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_application MÉTODO POST STATUS 201 `FUND_CLASS_KEY` é a chave da **sua** classe de fundo, a que vai aplicar. ```json title='Request Body' { "issuance_serie_key": "", "amount": 100000.00, "quotation_date": "2026-10-08", "payment_method": "wire_transfer" } ``` ### Body params | Campo | Tipo | Descrição | Obrigatório | | -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `issuance_serie_key` | string | Chave da série de emissão investida (36 caracteres). Veja [Consulta paginada de séries de emissão](/documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao). | Sim | | `amount` | number | Valor da aplicação, maior que zero e maior ou igual ao `minimum_share_capital` da série. | Sim | | `quotation_date` | string | Data de cotização (`YYYY-MM-DD`). Obrigatória quando a série tem `quota_calculation_method` = `quota_value`; não pode ser anterior à data contábil da sua classe. Em séries `internal`, é ignorada; a data de cotização é definida pela plataforma e volta na resposta. | Condicional | | `source_account_key` | string | `account_key` da conta da sua classe que será debitada. Obrigatória quando a série tem `payment_type` = `automatic_debit`; não envie nos demais casos. | Condicional | | `payment_method` | string | `wire_transfer` (padrão) ou `pix`. | Não | :::info Débito automático Quando a série tem `payment_type` = `automatic_debit` (normalmente fundos de zeragem), envie `source_account_key`: a conta precisa estar aberta e ser da mesma instituição financeira da série (`financial_institution_code`). Recupere a chave em [Recuperando informações da conta](/documentation/iaas/visibildade_de_caixa/get_accounts). ::: Em séries `quota_value`, a aplicação nasce em `pending_manager_approval` e precisa ser aprovada (seção abaixo). Em séries `internal`, ela é aprovada na criação e segue para `pending_payment`. ## Response O mesmo objeto é devolvido pela criação, aprovação e cancelamento. Response Body ```json { "amount": 100000.0, "financial_application_key": "", "asset_key": null, "status": "pending_manager_approval", "quotation_date": "2026-10-08", "payment_date": "2026-10-08", "external_financial_application_key": null, "payment_method": "wire_transfer", "payment_type": "transfer", "issuance_serie": { "issuance_serie_key": "", "name": "Invested Issuance Serie Name", "subclass_name": "Invested Sub Class Name", "serie": 1, "quota_calculation_method": "quota_value", "condominium_type": "open_ended", "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", "asset_type": "multi_market_fund_quota", "payment_type": "transfer", "status": "active", "financial_institution_code": "329", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "2026-10-07", "administrator": { "administrator_key": "", "name": "Administrator Name", "document_number": "00.000.000/0000-00", "status": "active" }, "operation_periods": { "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } }, "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } } }, "isin_code": "BR000000000" }, "fund_class": { "fund_class_key": "", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "2026-10-07", "investor_key": "", "distributor": { "name": "Distributor Name", "distributor_key": "", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ``` `asset_key` é preenchido na cotização; `iof_amount` e `number_of_quotas` aparecem quando já calculados. A descrição de cada campo está em [Consulta paginada de aplicações](/documentation/iaas/cotas_de_fundo/consulta_paginada_aplicacoes_financeiras#financial_application). Status possíveis: `created`, `pending_manager_approval`, `pending_distributor_approval`, `pending_external_approval`, `pending_payment`, `pending_payment_confirmation`, `pending_notify_distributor`, `pending_quotation`, `mismatched_external_data`, `canceled`, `confirmed`. ## Aprovar aplicação financeira Aprova uma aplicação em `pending_manager_approval`. A resposta traz `pending_payment` ou, quando a série depende de aprovação do distribuidor, `pending_distributor_approval`. 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" } ``` | Campo | Tipo | Descrição | Obrigatório | | -------- | ------ | ------------------------------------------------------------------------------------------------ | ----------- | | `status` | string | Envie `pending_payment`. Outro valor, ou aplicação fora de `pending_manager_approval`, devolve `TFQ000052`. | Sim | A resposta é o objeto de aplicação financeira (veja [Response](#response)). ## Cancelar aplicação financeira ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_application/FINANCIAL_APPLICATION_KEY/cancel MÉTODO PUT STATUS 202 Sem corpo. A aplicação pode ser cancelada nos status `pending_manager_approval`, `pending_payment`, `pending_payment_confirmation` e `mismatched_external_data`. Em `pending_distributor_approval` e `pending_external_approval`, só o administrador cancela (`TFQ000053`); nos demais status, a API devolve `TFQ000073`. A resposta é o objeto de aplicação financeira, com `status` = `canceled`. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------------------------------------------------------------- | | 400 | `TFQ000023` | `amount` menor que o mínimo de aplicação da série (`minimum_share_capital`). | | 400 | `TFQ000033` | A série investida é da própria classe de fundo. | | 400 | `TFQ000039` | `quotation_date` não enviada numa série `quota_value`. | | 400 | `TFQ000050` | `quotation_date` anterior à data contábil da sua classe. | | 400 | `TFQ000055` | Falta um dado exigido pela série (por exemplo, `source_account_key` em débito automático). | | 400 | `TFQ000056` | `source_account_key` enviado para uma série que não usa débito automático. | | 400 | `TFQ000058` | A conta de `source_account_key` não é da instituição financeira da série. | | 400 | `TFQ000061` | A conta de `source_account_key` não está aberta. | | 400 | `TFQ000108` | Aplicação enviada depois do horário-limite da série. | | 400 | `TFQ000148` | A série de emissão está inativa. | | 400 | `TFQ000187` | A data de pagamento calculada para a `quotation_date` já passou. | | 400 | `TFQ000207` | A grade de movimentação da série já fechou. | | 422 | `TFQ000198` | A série está bloqueada para aplicações porque o administrador está bloqueado. | | 422 | `TFQ000220` | O fundo investido foi liquidado e não aceita novas aplicações nessa série. | | 400 | `TFQ000052` | Aprovação com `status` diferente de `pending_payment` ou aplicação fora de `pending_manager_approval`. | | 400 | `TFQ000053` | Cancelamento de aplicação que aguarda o distribuidor ou o administrador. | | 400 | `TFQ000073` | Cancelamento não permitido no status atual. | | 403 | `TFQ000054` | A classe de fundo não pertence à sua gestora, ou aprovação de aplicação em `pending_external_approval` (só o administrador aprova). | | 404 | `TFQ000005` | Classe de fundo não encontrada. | | 404 | `TFQ000011` | Série de emissão não encontrada. | | 404 | `TFQ000013` | Aplicação financeira não encontrada (cancelamento). | | 404 | `TFQ000059` | Aplicação financeira não encontrada (aprovação). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Criar Pedido de Resgate URL: /documentation/iaas/cotas_de_fundo/operacao_resgates Cria um pedido de resgate das cotas que a sua classe de fundo tem em outro fundo (série de emissão investida) e permite aprovar ou cancelar o pedido. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Aplicações e Resgates | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request MÉTODO POST STATUS 201 `FUND_CLASS_KEY` é a chave da **sua** classe de fundo, a que detém as cotas. ```json title='Request Body' { "issuance_serie_key": "", "external_id": "3f1c2a9e-8b7d-4c6e-9a5f-1d2e3c4b5a60", "amount": 50000.00, "quotation_date": "2026-10-08" } ``` ### Body params | Campo | Tipo | Descrição | Obrigatório | | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `issuance_serie_key` | string | Chave da série de emissão investida (36 caracteres). A série precisa ser de condomínio aberto (`open_ended`). | Sim | | `external_id` | string | Seu identificador do pedido, com exatamente 36 caracteres (um UUID). Único: um segundo pedido com o mesmo valor é recusado com `TFQ000048`. | Sim | | `amount` | number | Valor do resgate, maior que zero. Em séries `internal`, é tratado como valor líquido. Obrigatório quando `redeem_all` não é `true`. | Condicional | | `redeem_all` | boolean | `true` para resgatar a posição inteira; nesse caso `amount` é dispensado. | Não | | `quotation_date` | string | Data de cotização (`YYYY-MM-DD`). Obrigatória quando a série tem `quota_calculation_method` = `quota_value`; não pode ser anterior à data contábil da sua classe. Em séries `internal`, é ignorada. | Condicional | | `payment_date` | string | Data de pagamento (`YYYY-MM-DD`), igual ou posterior a `quotation_date`. Se omitida, vale `quotation_date`. Só é usada em séries `quota_value`. | Não | | `source_account_key` | string | `account_key` da conta da sua classe na instituição financeira da série. Obrigatória quando o `payment_type` da série é `automatic_debit`; não envie quando é `transfer`. | Condicional | :::info Débito automático Quando o `payment_type` da série é `automatic_debit` (normalmente fundos de zeragem), envie `source_account_key`: a conta precisa estar aberta e ser da mesma instituição financeira da série. Recupere a chave em [Recuperando informações da conta](/documentation/iaas/visibildade_de_caixa/get_accounts). ::: :::tip Reenvio Em caso de erro, reenvie a requisição: se o pedido já existir, a API devolve `TFQ000048` (409) e não cria outro. Nesse caso, confira-o na [Consulta paginada de resgates](/documentation/iaas/cotas_de_fundo/consulta_paginada_resgates) em vez de recriar. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ::: Em séries `quota_value`, o pedido nasce em `pending_manager_approval` e precisa ser aprovado (seção abaixo). Em séries `internal`, ele é aprovado na criação. ## Response O mesmo objeto é devolvido pela criação, aprovação e cancelamento. Response Body ```json { "redemption_request_key": "", "external_redemption_request_key": null, "status": "pending_manager_approval", "quotation_date": "2026-10-08", "payment_date": "2026-10-08", "amount": 50000.0, "issuance_serie": { "issuance_serie_key": "", "name": "Issuance Serie Name", "subclass_name": "SUBORDINADA", "serie": 1, "quota_calculation_method": "quota_value", "condominium_type": "open_ended", "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", "asset_type": "fixed_income_fund_quota", "payment_type": "automatic_debit", "status": "active", "financial_institution_code": "329", "account_data": { "account_digit": "0", "account_branch": "0001", "account_number": "12345", "financial_institution_code": "329", "financial_institution_ispb": "00000000" }, "last_updated_date": "2026-10-07", "administrator": { "administrator_key": "", "name": "Administrator Name", "document_number": "00.000.000/0000-00", "status": "active" }, "operation_periods": { "redemption_request": { "payment": { "days": 1, "type": "until", "calendar_base": "calendar_365" }, "quotation": { "days": 1, "type": "fixed", "calendar_base": "calendar_365" } }, "financial_application": { "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" }, "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" } } } }, "fund_class": { "fund_class_key": "", "name": "Fund Class Name", "short_name": "Fund Class Short Name", "document_number": "00.000.000/0000-00", "accounting_date": "2026-10-07", "investor_key": "", "distributor": { "name": "Distributor Name", "distributor_key": "", "document_number": "00.000.000/0000-00" }, "manager": { "manager_key": "", "manager_name": "Manager Name", "document_number": "00.000.000/0000-00" } } } ``` `redeem_all` aparece (com `true`) quando o pedido é de resgate total; `cash_expectation` aparece quando a expectativa de caixa já foi criada. O `external_id` enviado não é devolvido. A descrição de cada campo está em [Consulta paginada de resgates](/documentation/iaas/cotas_de_fundo/consulta_paginada_resgates#redemption-request). Status possíveis: `created`, `pending_manager_approval`, `pending_distributor_approval`, `pending_external_approval`, `pending_quotation`, `quoted`, `mismatched_external_data`, `canceled`, `confirmed`, `quotation_reversed`. ## Aprovar pedido de resgate Aprova um pedido em `pending_manager_approval`. Sem corpo. ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request/REDEMPTION_REQUEST_KEY/approval MÉTODO PUT STATUS 202 A rota `PUT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request/REDEMPTION_REQUEST_KEY`, com o corpo `{"status": "pending_external_approval"}`, faz a mesma aprovação e continua disponível nos mesmos perfis. A resposta é o objeto de pedido de resgate (veja [Response](#response)). ## Cancelar pedido de resgate ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request/REDEMPTION_REQUEST_KEY/cancel MÉTODO PUT STATUS 202 Sem corpo. Você pode cancelar o pedido enquanto ele está em `pending_manager_approval`. Depois da aprovação, o cancelamento é feito pelo administrador, e a API devolve `TFQ000053`. A resposta é o objeto de pedido de resgate, com `status` = `canceled`. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | --------------------------------------------------------------------------------------- | | 409 | `TFQ000048` | Já existe um pedido de resgate com esse `external_id`. | | 400 | `TFQ000039` | `quotation_date` não enviada numa série `quota_value`. | | 400 | `TFQ000041` | A sua classe não tem cotas ativas dessa série para resgatar. | | 400 | `TFQ000046` | `payment_date` anterior a `quotation_date`. | | 400 | `TFQ000049` | A série ainda não tem cota calculada (séries `internal`). | | 400 | `TFQ000050` | `quotation_date` anterior à data contábil da sua classe. | | 400 | `TFQ000055` | `source_account_key` não enviado numa série com débito automático. | | 400 | `TFQ000056` | `source_account_key` enviado numa série com `payment_type` = `transfer`. | | 400 | `TFQ000058` | A conta de `source_account_key` não é da instituição financeira da série. | | 400 | `TFQ000061` | A conta de `source_account_key` não está aberta. | | 400 | `TFQ000067` | `amount` não enviado e `redeem_all` diferente de `true`. | | 400 | `TFQ000177` | A série não aceita resgate (condomínio fechado). | | 400 | `TFQ000207` | A grade de movimentação da série já fechou (aprovação). | | 400 | `TFQ000052` | Aprovação de pedido fora de `pending_manager_approval`. | | 400 | `TFQ000053` | Cancelamento de pedido fora de `pending_manager_approval`. | | 403 | `TFQ000054` | A classe de fundo não pertence à sua gestora. | | 404 | `TFQ000005` | Classe de fundo não encontrada. | | 404 | `TFQ000011` | Série de emissão não encontrada. | | 404 | `TFQ000045` | Pedido de resgate não encontrado (cancelamento). | | 404 | `TFQ000060` | Pedido de resgate não encontrado (aprovação). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. Para anexar comprovantes a uma despesa, veja [Documentos de despesas consolidadas](/documentation/iaas/despesas/despesa_consolidada/documentos). ::: ## Listagem de despesas Retorna a lista paginada de todas as despesas de uma classe de fundo, com suporte a diversos filtros. ### Request :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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`. Valores fora desse intervalo devolvem `400`. | | `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 (um único valor). | | `expense_type_to_ignore` | string | opcional | Exclui da listagem despesas com o tipo informado (um único valor). | | `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 EXEMPLO LTDA", "manager_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "document_number": "22.333.444/0001-81" }, "fund_class_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "document_number": "33.444.555/0001-81", "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": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_ispb": "60701190" } }, "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 de pagamento da despesa (favorecido em `target`; conforme o meio de pagamento, `target_account`, `target_pix_key`, `transfer_type` ou `bank_slip`). Nunca é `null`; pode vir como objeto vazio (`{}`) quando a despesa não tem dados de pagamento. | | `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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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 EXEMPLO LTDA", "manager_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "document_number": "22.333.444/0001-81" }, "fund_class_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "document_number": "33.444.555/0001-81", "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": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_ispb": "60701190" } }, "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). --- ## 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. | ## Erros | Status | Código | Quando acontece | | ------ | ------ | --------------- | | 400 | `EXP000069` | A classe de fundo (`fund_class_key`) não pertence à gestora da sua chave de API. Vale para os dois endpoints. | | 400 | — | `limit` fora do intervalo de 0 a 100, ou data em formato diferente de `YYYY-MM-DD`. | | 404 | `EXP000010` | O `expense_key` não existe nessa classe de fundo (consulta de despesa específica). | ```json { "title": "Manager Not Associated with Fund Class", "description": "Manager with key {manager_key} is not associated with Fund Class with key {fund_class_key}.", "translation": "Gestor com chave {manager_key} nao esta associado com Fundo com chave {fund_class_key}.", "code": "EXP000069" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Documentos de despesas consolidadas URL: /documentation/iaas/despesas/despesa_consolidada/documentos Anexe comprovantes (nota fiscal, memória de cálculo, contrato, boleto) a uma despesa da classe de fundo e consulte os documentos já anexados. A `expense_key` vem da [consulta de despesas consolidadas](/documentation/iaas/despesas/despesa_consolidada/consulta_despesas). O envio do arquivo acontece em duas etapas: a API registra o documento e devolve uma URL de upload; em seguida, você envia o arquivo diretamente para essa URL. ## Anexar documento :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ENDPOINT /expense/fund_class/{fund_class_key}/expense/{expense_key}/document MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave da classe de fundo (UUID). | | `expense_key` | string | Chave da despesa (UUID). | ### 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 | `invoice` (nota fiscal), `calculation_memory` (memória de cálculo), `contract` (contrato) ou `bank_slip` (boleto). | Nenhum outro campo é aceito. ```json title="Request Body" { "name": "NF-e 001234 - Auditoria jun/2026", "document_type": "invoice" } ``` ### Response STATUS 201 ```json title="Response Body" { "name": "NF-e 001234 - Auditoria jun/2026", "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "expense_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_type": "invoice", "upload_url": { "url": "https://", "fields": { "key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "policy": "", "x-amz-algorithm": "AWS4-HMAC-SHA256", "x-amz-credential": "", "x-amz-date": "20260701T120000Z", "x-amz-signature": "" } } } ``` | Campo | Tipo | Descrição | |---|---|---| | `document_key` | string | Chave do documento (UUID). Use-a para consultar o documento depois. | | `expense_key` | string | Chave da despesa à qual o documento pertence. | | `upload_url.url` | string | Endereço para onde o arquivo deve ser enviado. | | `upload_url.fields` | object | Campos que precisam acompanhar o arquivo. Envie todos, sem alterar nomes nem valores; o conjunto exato de campos pode variar. | ### Envio do arquivo Faça um `POST` `multipart/form-data` para `upload_url.url`, com todos os campos de `upload_url.fields` e o arquivo no campo `file` (o último do formulário). A URL expira em **10 minutos** e aceita arquivos de até **50 MB**. Essa chamada vai direto para o armazenamento: não leva cabeçalhos de autenticação da QI Tech. ```python import requests upload = response_body["upload_url"] with open("nfe_001234.pdf", "rb") as arquivo: resposta = requests.post( upload["url"], data=upload["fields"], files={"file": arquivo}, ) resposta.raise_for_status() # 204 indica upload concluído ``` Se a URL expirar antes do envio, anexe o documento de novo para receber outra URL. ## Listar documentos de uma despesa Um `expense_key` que não existe na classe de fundo devolve `data` vazio, não 404. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ENDPOINT /expense/fund_class/{fund_class_key}/expense/{expense_key}/documents MÉTODO GET A listagem não é paginada e não traz a URL de download; para baixar um arquivo, consulte o documento pela chave. ```json title="Response Body" { "data": [ { "name": "NF-e 001234 - Auditoria jun/2026", "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "expense_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_type": "invoice" } ] } ``` ## Consultar documento por chave :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ENDPOINT /expense/fund_class/{fund_class_key}/expense/{expense_key}/document/{document_key} MÉTODO GET ```json title="Response Body" { "name": "NF-e 001234 - Auditoria jun/2026", "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef", "expense_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_type": "invoice", "document_url": "https://" } ``` | Campo | Tipo | Descrição | |---|---|---| | `document_url` | string | URL pré-assinada para baixar o arquivo, válida por 24 horas. Consulte o documento de novo para obter outra. | ## Erros | Status | Código | Quando acontece | | ------ | ------ | --------------- | | 400 | `EXP000069` | A classe de fundo não pertence à gestora da sua chave de API. | | 400 | `QIT000001` | Body inválido: falta `name` ou `document_type`, `document_type` fora da lista ou campo não previsto. | | 404 | `EXP000072` | A despesa está cancelada (`canceled`) e não aceita novos documentos. | | 404 | `EXP000071` | O `document_key` não existe para essa despesa. | | 500 | `QIT000500` | Anexar documento: o `expense_key` não existe nessa classe de fundo. Confira a chave na [consulta de despesas](/documentation/iaas/despesas/despesa_consolidada/consulta_despesas). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81", "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). ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81", "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"`). | ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## 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. --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81", "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. | ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta de Contrato URL: /documentation/iaas/despesas/submissao_despesa/contrato/recuperacao Recupere os dados e o status atual de um contrato específico. ## Request :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81", "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. | ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 O contrato não pode ser editado pela API. Confira os dados antes de submeter; para corrigir, cancele o contrato e crie outro. ::: ## Request :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81", "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). ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## 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`). --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "11.222.333/0001-81" }, "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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" } } ``` ### 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). ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "11.222.333/0001-81" }, "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": "44.555.666/0001-81" }, "bank_slip": { "digitable_line": "34191090086352151004791020150008110010000035000" }, "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 quando `payment_method = transfer` e `transfer_type` é omitido ou `wire_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, só dígitos (47 ou 48 caracteres, sem pontos nem espaços). | | `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": "11.222.333/0001-81" }, "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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" } } ``` ### 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. | ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## 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, com filtros opcionais. ## Listar por contrato :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "11.222.333/0001-81" }, "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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" } } ], "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. | ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "11.222.333/0001-81" }, "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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" } } ``` ### 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. | ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "11.222.333/0001-81" }, "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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "33.444.555/0001-81" } } ``` ### 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). ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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`. | ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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). :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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?..." } ``` | 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`. | ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## 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 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. 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. 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 (em qualquer status, exceto rejected ), 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 Despesa encerrada sem pagamento. Para lançar o valor, crie uma nova despesa com os dados corrigidos. 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 → --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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`. | --- ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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. **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) ::: --- ## Request :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ENDPOINT /vendor_registry/analysis MÉTODO POST ```json title="Request Body" { "vendor_document_number": "11.222.333/0001-81", "vendor_name": "AUDITORES EXEMPLO S.A.", "requires_invoice": true, "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81" }, "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": "22.333.444/0001-81" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81", "requires_invoice": true, "status": "pending_analysis" }, "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81" }, "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. | --- ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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?..." } ``` #### Atributos adicionais | Campo | Tipo | Descrição | |---|---|---| | `document_url` | string | URL pré-assinada para download do arquivo. Válida por 24 horas. | --- ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "11.222.333/0001-81", "requires_invoice": true, "status": "active", "payment_method": "transfer" }, { "vendor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "CVM", "document_number": "44.555.666/0001-81", "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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "11.222.333/0001-81", "requires_invoice": true, "status": "active", "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341", "financial_institution_ispb": "60701190" } } } ``` ### 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## Listar análises :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "22.333.444/0001-81" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81", "requires_invoice": true, "status": "pending_analysis" } } ], "limit": 10, "page": 0, "is_last_page": true } ``` --- ## Consultar análise por chave :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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": "22.333.444/0001-81" }, "vendor": { "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef", "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81", "requires_invoice": true, "status": "pending_analysis" }, "payment_method": "transfer", "payment": { "target": { "name": "AUDITORES EXEMPLO S.A.", "document_number": "11.222.333/0001-81" }, "target_account": { "account_number": "123456", "account_branch": "0001", "account_digit": "0", "financial_institution_code": "341", "financial_institution_ispb": "60701190" } } } ``` ### 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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 retirar a análise da fila de revisão (por exemplo, para anexar outro documento antes de reenviar). | ## 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; o agente pode voltar a ele retirando a análise da revisã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 ```text pending_submission ──→ pending_adm_approval (submissão para revisão) pending_submission ──→ canceled (cancelamento) pending_adm_approval ──→ pending_submission (retirada da revisão) pending_adm_approval ──→ canceled (cancelamento) ``` --- ## 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" } ``` Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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-analise-por-chave)** — verifique o progresso da 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 DTVM. 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, cadastre o fornecedor que prestará serviços ao fundo: crie uma análise de cadastro, anexe os documentos e submeta para aprovação da QI Tech. Após a aprovação, a `vendor_key` fica disponível 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 criado (e não rejeitado), 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", "pricing_type": "yield_curve", "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` | number | Valor unitário na integralização | Sim | | `number_of_units` | number | 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 | | `pricing_type` | string | Precificação do ativo na carteira: `yield_curve` ou `mark_to_market`. | Sim | | `payment` | dict | Objeto de [pagamento](#pagamento) para liquidação| Sim | :::info 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` | object | Objeto de [conta bancária](#conta-bancaria) 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 | Não | ### 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" } ``` ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `QIT000001` | Corpo da requisição inválido: o campo que falhou vem em `description`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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", "distribution_type": "private", "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 | | `distribution_type` | string | Tipo de distribuição: `public` ou `private`. | 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 | | `amortization_type` | string | Enumerador de [Tipo de Amortização](#enumerador-tipo-de-amortizacao) | 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-pre-fixado) | Sim | | `post_fixed` | dict | Objeto de [pós fixado](#objeto-pos-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 | | **custom** | Amortização customizada | #### 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 (também com `fixed`) | | `amount` | number | Valor da Multa, se tipo de multa for `fixed`. | Não | ##### 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-metodo-do-juros-de-mora)**. | Sim | | `pre_fixed` * | object | Ver **[Objeto de Pré Fixado](#objeto-pre-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`, `selic`, `ipca`) | Sim | | calendar_base | string | Tipo de calendário considerado | Sim | | lag | object | Ver [Objeto de Lag](#objeto-de-lag) | 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 Referência do Lag | Enumerador | Descrição | |--------------|---------------| | **daily** | Defasagem contada em dias | | **monthly** | Defasagem contada em meses | #### Enumerador Base de Cálculo | 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" } ``` ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `QIT000001` | Corpo da requisição inválido: o campo que falhou vem em `description`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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/approve 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 | ### Response STATUS 202 ```json title='Response Body' { "security_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "active" } ``` ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `QIT000001` | Corpo da requisição inválido: o campo que falhou vem em `description`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 emissões. --- # 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. ::: Quem faz o quê: | Ação | Gestora | Consultoria | Cedente | |------|---------|-------------|---------| | Listar apontamentos da análise | Sim | Sim | Não (use o webhook e a consulta por chave) | | Consultar apontamento e documento | Sim | Sim | Sim | | Responder | `PUT .../annotation/{annotation_key}` | `PUT .../annotation/{annotation_key}` | `PUT .../annotation/{annotation_key}/response` | --- ## Consulta Paginada de Apontamentos Recupera a lista de apontamentos de uma análise, permitindo ao agente identificar o que precisa ser respondido. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cedentes | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: O cedente não tem esta listagem: ele recebe o [webhook de apontamento](/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise#webhooks-de-apontamento), que traz a `annotation_key`, e consulta o apontamento por chave. ### Request ENDPOINT /assignor_registry/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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000026` | O agente autenticado não está habilitado no cadastro de cedentes. | | 400 | — | `limit` acima de `50` ou `page` negativo. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## Consulta de Apontamento por Chave :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cedentes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /assignor_registry/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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | `assignor_registry_key` não encontrado ou o agente não tem acesso a esse cedente. | | 404 | `ASR000033` | `analysis_key` não encontrado. | | 404 | `ASR000043` | `annotation_key` não pertence à análise indicada. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## Resposta ao Apontamento Envia a resposta a um apontamento `open`. Opcionalmente, é possível anexar um documento em PDF (até 20 MB) que comprove ou complemente a resposta. Respondido, o apontamento passa para `closed` e o webhook de apontamento é disparado. A gestora e a consultoria respondem pelo `PUT` no próprio apontamento; o cedente responde pelo `PUT` em `/response`. O corpo e a resposta são os mesmos. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request (gestora e consultoria) ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY MÉTODO PUT :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request (cedente) ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/response MÉTODO PUT ### Request Body ```json title='Request Body' { "response": "Segue autos do processo.", "document_b64": "JVBERi0xLjQK..." } ``` ### Objeto de Resposta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `response` * | string | Texto de resposta ao apontamento. | 1 - 3000 | | `document_b64` | string | Arquivo PDF codificado em Base64. Até 20 MB. | - | \*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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | `assignor_registry_key` não encontrado ou o agente não tem acesso a esse cedente. | | 404 | `ASR000033` | `analysis_key` não encontrado. | | 404 | `ASR000043` | `annotation_key` não pertence à análise indicada. | | 400 | `ASR000045` | O apontamento não está `open`. | | 400 | `ASR000044` | O apontamento já foi respondido. Cada apontamento aceita uma única resposta. | | 400 | `ASR000005` | `document_b64` não é Base64 válido. | | 400 | `ASR000060` | O conteúdo de `document_b64` não é um PDF. | | 400 | `ASR000059` | O PDF passa de 20 MB. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## Consulta de Documento do Apontamento Recupera uma URL temporária para download do documento anexado a um apontamento. A `DOCUMENT_KEY` é o `attached_document_key` do apontamento. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cedentes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /assignor_registry/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://URL_TEMPORARIA_DO_DOCUMENTO" } ``` :::info A `document_url` retornada é uma URL pré-assinada com validade de 24 horas. ::: ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | `assignor_registry_key` não encontrado ou o agente não tem acesso a esse cedente. | | 404 | `ASR000033` | `analysis_key` não encontrado. | | 404 | `ASR000043` | `annotation_key` não pertence à análise indicada. | | 404 | `ASR000006` | `DOCUMENT_KEY` não é o documento anexado ao apontamento. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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 | | ---------- | --------- | | **open** | Aberto e aguardando resposta do agente. | | **closed** | Respondido e encerrado. A QI DTVM pode reabri-lo (volta a `open`). | ### 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 importância, 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. :::caution 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 realizadas. 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 Se houver uma análise em andamento quando a atualização cadastral for enviada, ela é cancelada automaticamente (`analysis_status: canceled`, com `reproval_details` indicando a atualização cadastral) e uma nova análise é gerada. ::: --- ## Atualização de Cadastro de Cedente Pessoa Jurídica :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY MÉTODO PUT ```json title='Request Body' { "email": "financeiro@cedente-exemplo.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": "123.456.789-09", "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": "969.698.790-03", "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": "222.333.444-05", "person_type": "natural_person", "email": "email@avalista.com" }, { "name": "Avalista PJ", "document_number": "22.333.444/0001-81", "person_type": "legal_person", "email": "email@avalista.com", "guarantor_representatives": [ { "name": "Assinante do Avalista", "document_number": "111.444.777-35", "email": "emailrepresentante@avalista.com" } ] } ] } ``` --- ### Definição do Cedente | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` | string | Nome/razão social do cedente. | 1 a 255 | | `annual_revenues` | integer | 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 | | `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)**. | | `minimum_required_signers` | integer | Quantidade mínima de representantes que precisam assinar pelo cedente. | Mínimo de 1 | | `guarantors` | array | Lista de avalistas do cedente.| Ver **[Definição de Avalista](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-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": "registered", "name": "Cedente Exemplo LTDA", "document_number": "55.666.777/0001-81", "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": "969.698.790-03", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "123.456.789-09", "name": "Natália Nascimento", "documents": [] }, { "analysis_related_party_key": "8a3e2f61-0c4b-4d7e-9f15-2b6c7d8e9a01", "passport_number": "C01X00T47", "name": "Maria Vitoria", "documents": [] } ], "documents": [ { "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017", "document_type": "social_contract", "status": "valid" } ] } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](/documentation/iaas/homologacao_cedente/cadastro/envio_de_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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. | :::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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` existe (ou, para gestora e consultoria, se o cadastro pertence à sua integração). | | 400 | `ASR000100` | Campo enviado não pode ser atualizado em uma filial: `name`, `related_parties` e `guarantors` são sempre os da matriz. Para alterá-los, atualize o cadastro da matriz. | | 400 | `ASR000128` | Uma filial vinculada a esta matriz está com análise em andamento. Aguarde a conclusão da análise da filial e reenvie a atualização da matriz. | | 400 | `ASR000056` | 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. | | 400 | `ASR000054` | 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. | | 400 | `ASR000057` | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. Garantir que ao menos uma parte relacionada tenha `is_representative=true`. | | 400 | `ASR000011` | Número de documento de parte relacionada duplicado. Cada `document_number` em `related_parties` deve ser único. | | 400 | `ASR000041` | Email obrigatório para representante. Para partes relacionadas com `is_representative=true`, informar `email`. | | 400 | `ASR000058` | Pessoa estrangeira sem CPF não pode ser assinante. Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. | | 400 | `ASR000078` | Número de documento de avalista duplicado. Cada avalista em `guarantors` deve ter `document_number` único. | | 400 | `ASR000079` | Avalista pessoa física não aceita representante. Para `person_type=natural_person`, só é aceito o cônjuge: `related_party_type: spouse`. | | 400 | `ASR000080` | Documento de representante de avalista duplicado. Cada representante em `guarantor_representatives` deve ter `document_number` único. | | 400 | `ASR000091` | Avalista pessoa jurídica deve ter pelo menos um representante. Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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`), um **avalista** (`guarantor`) ou o **cônjuge** de um avalista pessoa física (`spouse`). A definição customizada permite, por exemplo, exigir múltiplos assinantes, ou restringir quem pode assinar determinado produto. ::: :::caution 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "123.456.789-09", "is_required_signer": true }, { "document_number": "969.698.790-03", "is_required_signer": false } ], "expiration": "2026-12-31" } ] }, { "product": "commercial_paper", "signer_groups": [ { "minimum_required_signers": 1, "signers": [ { "document_number": "123.456.789-09", "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. ::: :::caution 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. ::: :::caution Atenção Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**. ::: ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto. | | 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. | | 400 | `ASR000066` | Status da análise não permite definição de grupos customizados. A análise deve estar em `pending_documents` para receber grupos customizados. | | 404 | `ASR000109` | Tipo de produto inválido. Usar um valor válido para `product` (ver enum [Product Type](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes#product-type)). | | 400 | `ASR000118` | Signatário inválido. O `document_number` enviado em `signers` deve corresponder a um representante já cadastrado para o cedente, com `is_representative=true`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## Definição de Conjunto Customizado para Parte Relacionada Permite definir conjuntos customizados para um **avalista** ou para o **cônjuge** de um avalista pessoa física, utilizando a `analysis_related_party_key` retornada na criação da análise. :::info Informação Este endpoint customiza os assinantes de um **avalista** ou do **cônjuge** de um avalista pessoa física, identificado pela `analysis_related_party_key`. Para os representantes do próprio cedente, use o endpoint de conjunto customizado do cedente acima. Para outras partes relacionadas, a chamada não cria conjunto. ::: :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "111.444.777-35", "is_required_signer": true } ], "expiration": "2026-12-31" } ] } ] } ``` ### Response STATUS 204 Sem conteúdo no corpo de resposta. :::caution 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. ::: :::caution Atenção Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**. ::: ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto. | | 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. | | 404 | `ASR000035` | 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 cônjuge de avalista da análise. | | 400 | `ASR000066` | Status da análise não permite definição de grupos customizados. A análise deve estar em `pending_documents` para receber grupos customizados. | | 404 | `ASR000109` | Tipo de produto inválido. Usar um valor válido para `product` (ver enum [Product Type](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes#product-type)). | | 400 | `ASR000118` | 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). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## Consulta de Conjuntos de Assinantes Para consultar os conjuntos vigentes (padrão e customizados) e obter a `signer_group_set_key`, use a [Consulta de Assinantes](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes). Os enumeradores de `owner_type`, `product_type`, `signer_group_set_type` e `status` estão documentados nessa página. --- ## Definições ### 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](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes#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`. Aceito no envio; na consulta, grupos expirados não aparecem. | 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. ::: --- # 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á também montada 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. --- :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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 202 O corpo é a análise completa, no formato da [Consulta de Análise](/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise). Trecho: ```json title='Response Body' { "analysis_key": "2b1fa466-4d36-48e9-b6e3-776a1b700b9f", "analysis_number": 1, "assignor_registry_key": "d0a93900-457d-496a-8326-480ecaf946c3", "assignor_registry_status": "pending_registry", "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. ::: :::caution Não deixe a análise parada Uma análise que fica **1 mês sem movimentação** e ainda não foi concluída é **cancelada automaticamente** (`canceled`). O caso mais comum é a análise parada em `pending_documents`. Depois de cancelada, ela 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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto (ou, para gestora e consultoria, se o cadastro pertence à sua integração). | | 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. | | 400 | `ASR000040` | A análise não pertence ao cedente informado. Garantir que `analysis_key` e `assignor_registry_key` correspondam à mesma análise. | | 400 | `ASR000034` | 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. | | 400 | `ASR000038` | Status enviado é inválido. O campo `analysis_status` deve ser exatamente `sent_to_analysis`. | | 400 | `ASR000009` | 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). | | 400 | `ASR000015` | 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. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 Sandbox Em sandbox, o resultado da análise depende do primeiro dígito do documento do **cedente** (`document_number`): começando com 1, reprovação automática; começando com 8, a análise vai para validação manual (`pending_internal_validation`); os demais são aprovados automaticamente. ::: --- ## Cadastro de Cedente :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /assignor_registry/assignor_registry MÉTODO POST ```json title='Request Body' { "name": "Cedente Exemplo LTDA", "document_number": "55.666.777/0001-81", "person_type": "legal_person", "email": "financeiro@cedente-exemplo.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": "123.456.789-09", "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": "969.698.790-03", "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": "222.333.444-05", "person_type": "natural_person", "email": "email@avalista.com" }, { "name": "Avalista PJ", "document_number": "22.333.444/0001-81", "person_type": "legal_person", "email": "email@avalista.com", "guarantor_representatives": [ { "name": "Assinante do Avalista", "document_number": "111.444.777-35", "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 | CPF ou CNPJ do cedente, formatado (`000.000.000-00` ou `00.000.000/0000-00`). | 14 a 18 | | `annual_revenues` * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 | | `person_type` * | string | `natural_person` (física) ou `legal_person` (jurídica). | - | | `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](#definicao-de-telefone)**. | | `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definicao-de-endereco)**. | | `related_parties` ** | array | Lista de partes relacionadas da empresa.| Ver **[Definição de Parte Relacionada](#definicao-de-parte-relacionada)**. | | `accounts` | array | Lista de contas de desembolso do cedente. Sem conta, não é possível propor um contrato de cessão.| Ver **[Definição de Conta](#definicao-de-conta)**. | | `guarantors` | array | Lista de avalistas do cedente.| Ver **[Definição de Avalista](#definicao-de-avalista)**. | | `minimum_required_signers` | integer | Quantidade mínima de representantes que precisam assinar pelo cedente. | Mínimo de 1 | \*Campos obrigatórios. \*\*Obrigatório para pessoa jurídica, com ao menos um representante assinante (`is_representative: true`). ### Response STATUS 201 ```json title='Response Body' { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_registry", "name": "Cedente Exemplo LTDA", "document_number": "55.666.777/0001-81", "related_parties": [ { "related_party_key": "0b6f6a52-6c1e-4f4e-9d2a-1f3c5e7a9b10", "name": "Natália Nascimento", "document_number": "123.456.789-09", "direct_beneficiary": true, "is_representative": true, "related_party_type": "attorney" }, { "related_party_key": "3e9d1c7b-2a4f-4b8e-8c6d-5f7a9b1c3d20", "name": "Maria Vitoria", "document_number": null, "direct_beneficiary": true, "is_representative": false, "related_party_type": "president", "passport_number": "C01X00T47" }, { "related_party_key": "7a2c4e6f-8b0d-4f1a-9c3e-5d7f9a1b3c30", "name": "Roberto Carlos", "document_number": "969.698.790-03", "direct_beneficiary": false, "is_representative": false, "related_party_type": "director" } ], "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "status": "pending_documents", "analysis_datetime": "2026-01-15T14:32:10Z", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "name": "Roberto Carlos", "document_number": "969.698.790-03", "analysis_roles": [{ "related_party_type": "director" }], "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "name": "Natália Nascimento", "document_number": "123.456.789-09", "analysis_roles": [{ "related_party_type": "attorney" }], "documents": [] }, { "analysis_related_party_key": "8a3e2f61-0c4b-4d7e-9f15-2b6c7d8e9a01", "name": "Maria Vitoria", "document_number": null, "analysis_roles": [{ "related_party_type": "president" }], "documents": [], "passport_number": "C01X00T47" }, { "analysis_related_party_key": "1f4b6d8a-3c5e-4a7b-9d1f-2e4a6c8b0d40", "name": "Avalista PF", "document_number": "222.333.444-05", "analysis_roles": [{ "related_party_type": "guarantor" }], "documents": [] }, { "analysis_related_party_key": "9c1e3a5b-7d9f-4b2c-8e4a-6f8b0c2d4e50", "name": "Avalista PJ", "document_number": "22.333.444/0001-81", "analysis_roles": [{ "related_party_type": "guarantor" }], "documents": [] }, { "analysis_related_party_key": "4d6f8b0c-2e4a-4c6d-8f0b-1a3c5e7d9f60", "name": "Assinante do Avalista", "document_number": "111.444.777-35", "analysis_roles": [{ "related_party_type": "guarantor_representative" }], "documents": [] } ], "documents": [], "annotations": [], "last_updated": "2026-01-15T14:32:10Z", "analysis_origin_type": "assignor_registry", "reproval_reason": null, "reproval_details": null } } ``` | 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 | | `related_parties` | array | Partes relacionadas do cedente, com `related_party_key`, `name`, `document_number`, `direct_beneficiary`, `is_representative`, `related_party_type` e, para estrangeiros, `passport_number`. | - | | `last_analysis` | object | Objeto de análise. | Ver **[Definição de Análise](#definicao-de-analise)**. | :::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. ::: --- ## 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](#definicao-de-endereco)**. | | `email` **** | string | Endereço de e-mail do representante. | 1 a 255 | | `phone` | object | Objeto referenciando as informações do telefone do representante. Recomendado para representantes assinantes. | Ver **[Definição de Telefone](#definicao-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. \*\*\*\*Campo exigido 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](#definicao-de-partes-relacionadas-de-analise)**. | | `documents` * | array | Documentos da análise. | Ver **[Definição de Documentos de análise](#definicao-de-documentos)**. | | `analysis_datetime` * | string | Data e hora de criação da análise (ISO 8601, UTC). | - | | `annotations` * | array | Apontamentos da análise. | - | | `last_updated` * | string | Data e hora da última alteração da análise (ISO 8601, UTC). | - | | `analysis_origin_type` * | string | Origem da análise. Para cadastros enviados pela API, `assignor_registry`. | - | | `analysis_data` | object | Request body que originou a análise. Só vem na [consulta da análise](/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise); não vem no retorno do cadastro. | - | | `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 | | `passport_number` | string | Passaporte, só para estrangeiros que o informaram. | - | | `analysis_roles` * | array | Papéis da pessoa na análise, cada um com `related_party_type` (por exemplo, `director`, `guarantor` ou `guarantor_representative`). | - | | `documents` * | array | Documentos da análise da parte relacionada. | Ver **[Definição de Documentos de análise](#definicao-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. Só dígitos. | 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. | - | | `description` | string | Descrição livre da conta. | Até 255 | \*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. :::caution 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](#definicao-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definicao-de-endereco)**. | | `guarantor_representatives` | array | Representantes do avalista PJ ou cônjuge do avalista PF. | Ver **[Definição de Representante do Avalista](#definicao-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. :::caution Atenção Tanto o avalista quanto os representantes também serão adicionados à análise 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](#definicao-de-endereco)**. | | `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. | Ver **[Definição de Telefone](#definicao-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. | | `related_party_type` | string | `guarantor_representative` (padrão) para representante de avalista PJ; `spouse` para o cônjuge de avalista PF (outorga uxória). | - | --- ## Enumeradores ### Assignor Registry Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **created** | Criado (transitório) | | **pending_registry** | Pendente Registro | | **pending_manual_approval** | Pendente aprovação manual da QI DTVM | | **registered** | Registrado | | **rejected** | Rejeitado | | **blocked** | Bloqueado | --- ### Analysis Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **created** | Criada (transitório) | | **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 | | **in_risk_analysis** | Em Análise de Risco | | **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 | | **spouse** | Cônjuge | | **legal_representative** | Representante legal | --- ### Document Status | Enumerador | Descrição | | ----------------------- | ------------- | | **created** | Criado | | **valid** | Válido | | **invalid** | Inválido | | **canceled** | Cancelado | | **accepted** | Aceito, porém não validado | | **inconclusive** | Validação inconclusiva | --- ### 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. | | **national_registry_of_foreigners** | Registro Nacional de Estrangeiros. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplificada 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 | | **saving_account** | Conta Poupança | | **escrow_account** | Conta Vinculada (escrow) | --- ### 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 | | **risk_analysis_reproval** | Reprovação na análise de risco | --- ### 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 | ## Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 409 | `ASR000032` | 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). | | 400 | `ASR000054` | Cedente pessoa jurídica deve ter pelo menos 1 parte relacionada. Incluir ao menos uma parte relacionada em `related_parties`. | | 400 | `ASR000056` | Pessoa física não pode ser participante do Sistema Financeiro Nacional. Para `person_type=natural_person`, enviar `is_in_national_financial_system=false`. | | 400 | `ASR000057` | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. Garantir que ao menos uma parte relacionada possua `is_representative=true`. | | 400 | `ASR000011` | Número de documento de parte relacionada duplicado. Cada `document_number` em `related_parties` deve ser único. | | 400 | `ASR000041` | Parte relacionada com `is_representative=true` sem `email`. Informe o e-mail do representante. | | 400 | `ASR000058` | Pessoa estrangeira sem CPF não pode ser assinante. Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. | | 404 | `ASR000071` | Instituição financeira não encontrada. Validar o `financial_institution_code` (código bancário) informado para a conta. | | 400 | `ASR000087` | Informação de conta deve conter apenas números. Enviar `account_branch`, `account_number` e `account_digit` apenas com dígitos. | | 400 | `ASR000081` | Mais de uma conta padrão foi enviada. Apenas uma conta deve ter `default_account=true`. | | 400 | `ASR000078` | Número de documento de avalista duplicado. Cada avalista em `guarantors` deve ter `document_number` único. | | 400 | `ASR000079` | Avalista pessoa física não aceita representante. Para `person_type=natural_person`, só é aceito o cônjuge: `related_party_type: spouse`. | | 400 | `ASR000080` | Documento de representante de avalista duplicado. Cada representante em `guarantor_representatives` deve ter `document_number` único. | | 400 | `ASR000091` | Avalista pessoa jurídica deve ter pelo menos um representante. Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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á operar 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 só são aceitos enquanto a análise estiver em `pending_documents`. Pela gestora e pela consultoria, o envio é restrito ao agente dono do cadastro (quem o criou); para outro agente, a API responde `ASR000004`. ## Enviou o documento errado? Reenvie o documento correto com o mesmo `document_type`, enquanto a análise ainda estiver em `pending_documents`. O documento anterior daquele tipo (`valid` ou `accepted`) passa automaticamente para `canceled` e o novo o substitui. Não existe chamada de cancelamento. A exceção é `additional_document`: documentos adicionais se acumulam e não são substituídos. Se um documento adicional foi enviado por engano, fale com o time de integração em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) antes de disparar a análise. Depois do [Envio para Análise](/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise), a análise não aceita mais documentos (`ASR000039`). Para corrigir, gere uma nova análise pela [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). --- ## Documentos do Cedente :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "JVBERi0xLjQK...", "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 | Arquivo 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", "status": "valid", "observation": "CONTRATO SOCIAL ATUALIZADO", "reference_date": null } ``` :::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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado (ou, para gestora e consultoria, o cadastro não pertence à sua integração). Verificar se o `assignor_registry_key` está correto. | | 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. | | 400 | `ASR000039` | 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). | | 400 | `ASR000005` | Formato de arquivo inválido. Enviar `document_b64` como string em base64 válida. | | 400 | `ASR000060` | O arquivo enviado não é um PDF válido. O conteúdo decodificado de `document_b64` deve ser um PDF. | | 400 | `ASR000059` | Tamanho do arquivo excede o limite. Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). | | 400 | `ASR000061` | 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-padrao-do-cedenteavalista)). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Documentos das partes relacionadas :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Ler Cedentes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "JVBERi0xLjQK...", "observation":"CNH Válida" } ``` ### Response STATUS 201 ```json title='Response Body' { "document_key": "afe8532a-4b0b-4e63-8d16-5084b2681752", "status": "valid", "document_type": "cnh", "observation": "CNH Válida" } ``` :::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 — veja [Enviou o documento errado?](#enviou-o-documento-errado). ::: ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado (ou, para gestora e consultoria, o cadastro não pertence à sua integração). Verificar se o `assignor_registry_key` está correto. | | 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. | | 404 | `ASR000035` | 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. | | 400 | `ASR000039` | O status atual da análise não aceita novos documentos. Documentos só podem ser anexados quando a análise estiver em `pending_documents`; depois disso, gere uma nova análise via [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). | | 400 | `ASR000005` | Formato de arquivo inválido. Enviar `document_b64` como string em base64 válida. | | 400 | `ASR000060` | O arquivo enviado não é um PDF válido. O conteúdo decodificado de `document_b64` deve ser um PDF. | | 400 | `ASR000059` | Tamanho do arquivo excede o limite. Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). | | 400 | `ASR000062` | 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-padrao-das-partes-relacionadasrepresentantes)). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ### 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 | Certidã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. :::caution 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 retorna de forma síncrona 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. | | **national_registry_of_foreigners** | Registro Nacional de Estrangeiros. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplificada 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 (substituído por um novo envio do mesmo tipo) | | **accepted** | Aceito, porém não validado | | **inconclusive** | Validação inconclusiva | --- # 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 [listagem de configurações de cessão](/documentation/iaas/negociacao_recebiveis/listagem), com parâmetros como `assignment_contract_key`, `asset_type` e `assignor_document_number`, utilizando o contrato formalizado pela matriz como referência. :::caution 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 webhook de aprovação ou reprovação da análise gerada, que é enviada automaticamente. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "55.666.777/0002-62", "email": "filial@cedente-exemplo.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](/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)**. | | `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)**. | *Campos obrigatórios. ### Response STATUS 201 ```json title='Response Body' { "assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947", "status": "pending_registry", "name": "Cedente Exemplo LTDA", "document_number": "55.666.777/0002-62", "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": "969.698.790-03", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4", "document_number": "123.456.789-09", "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" } ] } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](/documentation/iaas/homologacao_cedente/cadastro/envio_de_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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. | :::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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente matriz não encontrado para o `assignor_registry_key` informado. Garantir que `assignor_registry_key` na URL corresponda ao cadastro da matriz. | | 400 | `ASR000099` | Cedente pessoa física não pode ter filiais. Apenas matrizes pessoa jurídica (`person_type=legal_person`) podem ter filiais. | | 400 | `ASR000096` | Status da matriz não permite ativação de filial. A matriz deve estar com `status=registered` para criar uma filial. | | 400 | `ASR000097` | O cadastro referido não é uma matriz. O `assignor_registry_key` na URL deve ser de um cadastro com `organization_level=headquarters`. | | 400 | `ASR000098` | 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. | | 409 | `ASR000032` | 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-ja-existente-a-matriz). | | 404 | `ASR000071` | Instituição financeira não encontrada para a conta da filial. Validar o `financial_institution_code` informado em `accounts`. | | 400 | `ASR000087` | Informação de conta deve conter apenas números. Enviar `account_branch`, `account_number` e `account_digit` apenas com dígitos. | | 400 | `ASR000081` | Mais de uma conta padrão foi enviada. Apenas uma conta deve ter `default_account=true`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "Cedente Exemplo LTDA", "document_number": "55.666.777/0002-62", "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": "969.698.790-03", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4", "document_number": "123.456.789-09", "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" } ] } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](/documentation/iaas/homologacao_cedente/cadastro/envio_de_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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. | ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | 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. | | 400 | `ASR000099` | Cedente pessoa física não pode ter filiais. Apenas matrizes pessoa jurídica podem vincular filiais. | | 400 | `ASR000096` | Status da matriz não permite vínculo de filial. A matriz deve estar com `status=registered`. | | 400 | `ASR000097` | O cadastro referido não é uma matriz. O `assignor_registry_key` na URL deve ser de um cadastro com `organization_level=headquarters`. | | 400 | `ASR000098` | 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. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Cadastrar Cedente | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY MÉTODO PUT ```json title='Request Body' { "email": "financeiro@cedente-exemplo.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](/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)**. | 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": "registered", "name": "Cedente Exemplo LTDA", "document_number": "55.666.777/0002-62", "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": "969.698.790-03", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "7ea3193b-8e53-40b7-94cf-2d3cc62942e0", "document_number": "123.456.789-09", "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" } ] } } ``` | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](/documentation/iaas/homologacao_cedente/cadastro/envio_de_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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. | :::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 a mesma lógica da matriz: veja [Contas do cedente](/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas). ::: ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | 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. | | 400 | `ASR000100` | Campo enviado não pode ser atualizado em uma filial: `name`, `related_parties` e `guarantors` são sempre os da matriz. Para alterá-los, atualize o cadastro da matriz (ver [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro)). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Contas do cedente URL: /documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas As contas de desembolso podem ser enviadas já no [cadastro do cedente](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro) (`accounts`) ou adicionadas depois por esta página. O cedente precisa ter ao menos uma conta para que um [contrato de cessão](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato) seja proposto. 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. 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, obrigatoriamente 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. :::caution 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. ::: :::info A gestora não mantém contas por API As rotas de conta não estão disponíveis em `manager-api`. A manutenção das contas do cedente é feita pela consultoria (`consultant-api`) ou pelo próprio cedente (`assignor-api`). Uma gestora que precise incluir ou desativar uma conta deve enviá-la já no cadastro inicial do cedente (`accounts`), pedir à consultoria ou ao cedente, ou falar com o time de integração em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). ::: --- ## Adição de conta alternativa :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Consultoria | `consultant-api` | Cadastrar Cedente | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto. | | 409 | `ASR000072` | 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. | | 400 | `ASR000087` | Informação de conta deve conter apenas números. Enviar `account_branch`, `account_number`, `account_digit` e `financial_institution_code` apenas com dígitos. | | 404 | `ASR000071` | Instituição financeira não encontrada. Validar o `financial_institution_code` (código bancário) informado. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Consultoria | `consultant-api` | Cadastrar Cedente | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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 | Só aceita `true`: torna esta a conta padrão de desembolso. | - | Envie ao menos um dos dois campos. ### 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 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. Não é possível desativar uma conta padrão, ou definir como padrão uma conta inativa. ::: ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto. | | 404 | `ASR000073` | Conta não encontrada para o `account_key` informado. Verificar se o `account_key` pertence ao cedente. | | 400 | `ASR000074` | 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. | | 400 | `ASR000075` | Nenhuma informação foi enviada para atualização. Informar `status` ou `default_account` no corpo da requisição. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Enumeradores ### Account Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **active** | Conta ativa e disponível como opção de desembolso. | | **inactive** | Conta inativa e indisponível para desembolso. | --- # Webhooks URL: /documentation/iaas/homologacao_cedente/cadastro/webhooks_analise --- Os webhooks do cadastro são enviados a todos os agentes com acesso ao cadastro do cedente (gestora, consultoria e cedente) que tenham webhook configurado. Cadastros originados por carga da Fromtis (`fromtis_load`) não disparam webhook. Assinatura, reenvio e configuração: veja [Autenticação de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ## Webhooks de Análise `webhook_type`: `assignor_registry.analysis_status_change` ### Derivaçã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:23Z" } ``` ### 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:23Z" } ``` ### Aprovado STATUS approved ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "analysis_status": "approved", "reproval_reason": null, "reproval_details": null }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23Z" } ``` ### Reprovado STATUS reproved ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "analysis_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:23Z" } ``` ### 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:23Z" } ``` ## Webhooks de Apontamento `webhook_type`: `assignor_registry.annotation_status_change` 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 `webhook_type`: `assignor_registry.assignor_registry_status_change`. Enviado uma única vez, quando o cedente é efetivado (`registered`). ### 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:23Z" } ``` --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cedentes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "969.698.790-03", "name": "Roberto Carlos", "documents": [ { "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba", "document_type": "cnh", "status": "valid" } ] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "123.456.789-09", "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": "Cedente Exemplo LTDA", "document_number": "33.344.455/0001-83", "person_type": "legal_person", "email": "financeiro@cedente-exemplo.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": "123.456.789-09", "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": "969.698.790-03", "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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto (ou, para gestora e consultoria, se o cadastro pertence à sua integração). | | 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## Consulta Paginada de Análises :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cedentes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analyses MÉTODO GET ### Query params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `limit` | integer | Itens por página. Padrão `10`, máximo `50`. Acima do máximo, a API devolve 400 | - | | `page` | integer | Página, começando em `0`. Use `is_last_page` da resposta para saber quando parar | - | ### 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": "969.698.790-03", "name": "Roberto Carlos", "documents": [ { "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba", "document_type": "cnh", "status": "valid" } ] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "123.456.789-09", "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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto (ou, para gestora e consultoria, se o cadastro pertence à sua integração). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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`), um **avalista** (`guarantor`) ou o **cônjuge** de um avalista pessoa física (`spouse`), 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cedentes | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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, avalista ou cônjuge). Ver **[Owner Type](#owner-type)**. | | `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": "123.456.789-09", "is_required_signer": true }, { "document_number": "969.698.790-03", "is_required_signer": false } ] } ] } ], "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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 400 | `ASR000121` | `owner_document_number` enviado sem `owner_type`. Ao filtrar por `owner_document_number`, sempre informar também `owner_type`. | | 400 | `ASR000120` | 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)). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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, conforme o `owner_type`. Ver **[Owner Type](#owner-type)**. | 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)**. | A consulta não devolve `expiration`, e grupos já expirados não aparecem. --- ### 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 do cedente. `owner_key` = `assignor_registry_key`. | | **guarantor** | Conjunto de um avalista. `owner_key` = chave do avalista (`guarantor_key`). | | **spouse** | Conjunto do cônjuge de um avalista pessoa física. `owner_key` = chave do cônjuge (`representative_key` em `guarantor_representatives`). | --- ### 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. | | **invalid** | Conjunto substituído por um envio mais recente, ou descartado. Não é utilizado nas assinaturas. | --- # Consulta de cedente URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente --- ## Consulta de Cedente Por Chave :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cedentes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "registered", "name": "Cedente Exemplo LTDA", "document_number": "33.344.455/0001-83", "person_type": "legal_person", "email": "financeiro@cedente-exemplo.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": "123.456.789-09", "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": "969.698.790-03", "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" } } ], "accounts": [ { "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c", "account_branch": "0001", "account_number": "7912584", "account_digit": "1", "account_type": "checking_account", "status": "active", "financial_institution_code": "329", "financial_institution_ispb": "32402502", "default_account": true, "owner": { "document_number": "33.344.455/0001-83" }, "description": null } ], "guarantors": [], "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "status": "pending_documents", "analysis_datetime": "2026-01-15T14:32:10Z", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "name": "Roberto Carlos", "document_number": "969.698.790-03", "analysis_roles": [{ "related_party_type": "director" }], "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "name": "Natália Nascimento", "document_number": "123.456.789-09", "analysis_roles": [{ "related_party_type": "attorney" }], "documents": [] } ], "documents": [], "annotations": [], "last_updated": "2026-01-15T14:32:10Z", "analysis_origin_type": "assignor_registry", "reproval_reason": null, "reproval_details": null } } ``` ### 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` | string | Status do cadastro. | Ver [Assignor Registry Status](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#assignor-registry-status) | | `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)**. | | `last_analysis` | object | Última análise do cadastro. | Ver **[Definição de Análise](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. | | `signer_groups` | array | Grupos de assinantes vigentes do cedente. | Ver **[Definição de Grupo de Assinantes](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes#definicao-de-grupo-de-assinantes-signer-group)**. | | `organization_level` | string | `headquarters` (matriz), `branch` (filial) ou `not_applicable`. Só vem quando definido. | - | | `headquarters_bond` | boolean | `true` quando o cadastro é uma filial vinculada a uma matriz. | - | ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto (ou, para gestora e consultoria, se o cadastro pertence à sua integração). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## Consulta Paginada de Cedentes :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cedentes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /assignor_registry/assignor_registries MÉTODO GET ### Query 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 | Itens por página. Padrão `25` (`10` na `assignor-api`), máximo `50`. Acima do máximo, a API devolve 400 | - | | `page` | integer | Página, começando em `0`. Use `is_last_page` da resposta para saber quando parar | - | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "registered", "name": "Cedente Exemplo LTDA", "document_number": "33.344.455/0001-83", "person_type": "legal_person", "email": "financeiro@cedente-exemplo.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": "123.456.789-09", "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": "969.698.790-03", "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" } } ], "accounts": [ { "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c", "account_branch": "0001", "account_number": "7912584", "account_digit": "1", "account_type": "checking_account", "status": "active", "financial_institution_code": "329", "financial_institution_ispb": "32402502", "default_account": true, "owner": { "document_number": "33.344.455/0001-83" }, "description": null } ], "guarantors": [], "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "status": "pending_documents", "analysis_datetime": "2026-01-15T14:32:10Z", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "name": "Roberto Carlos", "document_number": "969.698.790-03", "analysis_roles": [{ "related_party_type": "director" }], "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "name": "Natália Nascimento", "document_number": "123.456.789-09", "analysis_roles": [{ "related_party_type": "attorney" }], "documents": [] } ], "documents": [], "annotations": [], "last_updated": "2026-01-15T14:32:10Z", "analysis_origin_type": "assignor_registry", "reproval_reason": null, "reproval_details": null } } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 400 | — | `limit` acima de `50` ou `page` negativo. | | 404 | `ASR000026` | O agente autenticado não está habilitado no cadastro de cedentes. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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). --- --- # Consultar documentos URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos --- Retorna um documento anexo do contrato de cessão (o contrato ou a declaração da gestora) com a URL para download da versão mais recente. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler contratos de cessão | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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 title='Response Body' { "document_key": "8f1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "document_type": "assignment_contract", "status": "signed", "generation_method": "internal", "signature_validation_method": "internal", "document_template_key": "2a7c9e1b-3d5f-4b8a-9c0e-6f1a2b3c4d5e", "required_parties": ["manager", "assignor"], "upload_document_analyses": [], "download_url": "url para download do documento" } ``` :::info Observação O campo `download_url` traz a URL assinada para download do documento em sua versão mais atual: se o documento já estiver assinado, é a versão assinada. A URL expira e não deve ser guardada para consulta posterior. ::: ### 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 **[Attached Document Status](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#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. | -- | | `generation_method` | string | Como o documento é gerado: `internal` (pela plataforma) ou `external` (enviado por upload). | -- | | `signature_validation_method` | string | Como a assinatura é validada (por exemplo, `internal` ou `external`). | -- | | `upload_document_analyses` | array | Análises dos documentos enviados por upload. Vazio quando não há upload. | -- | | `download_url` | string | URL de download do PDF. | -- | ## Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ACT000023` | `assignment_contract_key` não encontrado. | | 404 | `ACT000087` | `document_key` não encontrado ou não pertence ao contrato indicado. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 seja enviado para assinatura. Só a gestora aprova ou recusa: a consultoria acessa a mesma rota, mas apenas para [cancelar](#cancelamento-de-contrato). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura e escrita | | Consultoria | `consultant-api` | Criar contratos de cessão | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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: `approved` ou `denied`. | -- | | `denial_reason` | string | Descritivo com o motivo da recusa. Volta no webhook do status `denied`. | Até 500 | *Campos obrigatórios ### Response STATUS 202 ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ACT000023` | `assignment_contract_key` não encontrado. | | 400 | `ACT000025` | Aprovação ou recusa enviada por quem não é a gestora. | | 400 | `ACT000077` | O status atual não permite a decisão. `approved` exige `pending_manager_approval`; `denied` aceita `pending_manager_approval` ou `pending_document`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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. Todos os contratos do lote precisam estar em `pending_signature_submission`. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /assignment_contract/signature_batch MÉTODO POST ```json title='Request Body' { "assignment_contract_keys": [ "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "41d6ff41-1dac-4df7-9e50-d15210ec57f3" ] } ``` #### 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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ACT000023` | Uma das chaves de `assignment_contract_keys` não foi encontrada. | | 400 | `ACT000088` | Um dos contratos não está em `pending_signature_submission`. | | 404 | `ACT000089` | Os contratos do lote não têm as mesmas partes relacionadas (gestor, cedente, avalistas). Agrupe só contratos com as mesmas partes. | | 400 | `ACT000165` | Todos os contratos do lote são de templates que proíbem assinatura isolada. Inclua ao menos um contrato que a permita. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura e escrita | | Consultoria | `consultant-api` | Criar contratos de cessão | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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 | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ACT000023` | `assignment_contract_key` não encontrado. | | 400 | `ACT000077` | O contrato está `signed` ou `denied` e não pode ser cancelado. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 DTVM, 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 e os **produtos** do contrato. Os produtos identificam, por exemplo, uma configuração de cessão de um tipo de ativo, de recompra, e assim por diante. Eles vêm do template: não é preciso enviá-los no pedido. 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. 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. As contas de desembolso são definidas no cadastro do cedente; quando o template exige uma conta específica para o contrato, ela é indicada em `disbursement_account_key`. Todo o fluxo de assinatura do contrato é realizado pela nossa certificadora, CertifiQI. O acompanhamento das assinaturas e a ativação dos produtos acontecem de forma automática — veja [Ativação dos produtos](#ativacao-dos-produtos). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------------------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar contratos de cessão | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /assignment_contract/assignment_contract MÉTODO POST ```json title='Request Body' { "fund_class_key": "813ce253-bae5-4448-8d15-04c48d9991b7", "assignor_document_number": "55.666.777/0001-81", "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": "969.698.790-03" } ] } ``` ### 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 DTVM. | Chave uuid | | `assignment_contract_template_key` * | string | Chave única de identificação do Template de Contrato. Também fornecida pelo time da QI DTVM. | Chave uuid | | `assignor_document_number` ** | string | Número do documento do cedente. | CPF ou CNPJ, até 18 | | `assignor_registry_key` ** | string | Chave do cadastro do cedente, alternativa ao `assignor_document_number`. | Chave uuid | | `credit_limit` | number | Valor do limite de crédito do contrato. | 1 a 1.000.000.000 | | `disbursement_account_key` | string | Conta de desembolso do contrato. Obrigatória quando a política de conta de desembolso do template é `locked_on_assignment_contract`, e recusada nas demais. Deve ser uma conta `active` do cedente. | Chave uuid | | `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato. | Até 50 | | `case_number` | string | Número de caso. Único por fundo; se omitido, é gerado automaticamente. | Até 17 | | `observation` | string | Observação. Campo livre para quaisquer anotações. | Até 1000 | | `delay` | object | Multa (`fine`) e juros (`interest`) por atraso. Só é aceito quando o template permite customizar esses valores. | -- | | `guarantors` | array | Avalistas da operação. | Ver **[Definição de Avalista](#definicao-de-avalista)**. | \*Campos obrigatórios \*\*Envie exatamente um dos dois: `assignor_document_number` ou `assignor_registry_key`. :::caution 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 O corpo da resposta é o contrato completo, no mesmo formato da [Consulta de Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato). Trecho: ```json title='Response Body' { "assignment_contract_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "pending_document", "external_id": "Contrato 550", "case_number": "17375775230001234", "disbursement_account_key": null, "products": [ { "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "assignment_configuration_key": null, "fund_class_configuration_key": "0b6f3a8e-2f7d-4c11-9a52-6a1d1c0e9f10", "product_type": "assignment_term", "asset_type": "ccb", "has_coobligation": true, "status": "pending_contract_signature" } ] } ``` :::info É de extrema importância salvar a `assignment_contract_key`: ela identifica o contrato nas consultas e nos webhooks, e as configurações de cessão geradas pelo contrato (inclusive as originadas pelo fluxo de [Filiais](/documentation/iaas/homologacao_cedente/cadastro/filiais)) ficam vinculadas a ele. Para recuperar os produtos e as configurações geradas, use a [Consulta de Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato). ::: ## Ativação dos produtos Não existe chamada de ativação: os produtos são ativados automaticamente quando o contrato é assinado. 1. Todos os documentos assinados → o contrato passa para `signed` e é enviado o webhook `assignment_contract.assignment_contract_status_change` com `assignment_contract_new_status: contract_signed`. 2. Cada produto passa de `pending_contract_signature` para `pending_create_assignment_configuration` enquanto a esteira de cessão é configurada. Isso pode levar alguns minutos. 3. Configurada a esteira, o produto passa para `active` e é enviado o webhook `assignment_contract.product_status_change`, que traz a `assignment_configuration_key` — a chave usada para ceder ativos entre o fundo e o cedente. Os payloads estão em [Webhooks do Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato). Se preferir não depender do webhook, consulte o contrato e leia `products[].status` e `products[].assignment_configuration_key`. ### Definição de Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` | string | Nome do avalista. | Até 255 | | `document_number` | string | CPF ou CNPJ, formatado. | 14 a 18 | :::caution Aviso Como já indicado, o avalista deve ser previamente cadastrado, junto com o cedente em específico. ::: ## Enumeradores ### Assignment Contract Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **created** | Contrato criado (estado inicial e transitório) | | **pending_document** | Pendente geração dos documentos | | **pending_manager_approval** | Pendente aprovação do gestor | | **pending_assignor_registry_release** | Pendente liberação do cadastro de cedente vinculado (Em fase de cadastro ou atualização) | | **pending_signature_submission** | Pendente envio manual para assinatura | | **sending_to_signature** | Em envio para assinatura | | **pending_signature** | Disponível para assinatura das partes | | **waiting_escrow_data** | Aguardando dados da conta escrow (só em templates com conta escrow) | | **pending_escrow_activation** | Aguardando ativação da conta escrow (só em templates com conta escrow) | | **signed** | Assinado | | **suspended** | Suspenso; os produtos ficam `inactive` até a reativação | | **denied** | Reprovado na análise do gestor | | **canceled** | Cancelado | ### Product Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_contract_signature** | Aguardando a assinatura do contrato | | **pending_create_assignment_configuration** | Contrato assinado; esteira de cessão em configuração | | **active** | Ativo; `assignment_configuration_key` disponível | | **inactive** | Inativo (contrato cancelado ou suspenso) | ### Attached Document Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_generate** | Pendente geração do documento | | **approved** | Documento gerado | | **pending_upload** | Aguardando o upload do documento | | **uploaded** | Documento enviado | | **pending_validation** | Documento enviado, em validação | | **pending_signed_upload** | Aguardando o upload do documento assinado | | **signed** | Documento assinado | | **reproved** | Documento invalidado (contrato cancelado ou recusado) | ## Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ACT000001` | `fund_class_key` não encontrado ou não pertence à gestora autenticada. | | 404 | `ACT000016` | `assignment_contract_template_key` não encontrado para o fundo. | | 400 | `ACT000126` | O template está inativo. Use um template ativo. | | 404 | `ACT000065` | O cedente do `assignor_document_number` não está cadastrado para o agente proponente. | | 404 | `ACT000134` | `assignor_registry_key` não encontrado, ou o agente não é dono do cadastro. | | 400 | `ACT000142` | O cedente tem só cadastro de análise básica e não pode receber contrato. | | 400 | `ACT000096` | O cedente não tem conta cadastrada. Cadastre uma em [Manutenção de Contas](/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas). | | 400 | `ACT000155` | O template exige `disbursement_account_key` e ele não foi enviado. | | 400 | `ACT000156` | `disbursement_account_key` enviado, mas o template não aceita conta por contrato. | | 400 | `ACT000154` | `disbursement_account_key` não é uma conta `active` do cedente. | | 400 | `ACT000081` | Um item de `guarantors` não está cadastrado como avalista do cedente. | | 400 | `ACT000102` | `delay` enviado, mas o template não permite customizar multa e juros. | | 409 | `ACT000095` | `case_number` já usado neste fundo. Use outro ou omita o campo. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Recuperação do contrato URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato --- ## Recuperação do Contrato Retorna um contrato de cessão, com seus documentos e produtos. É a forma de consultar o status de cada produto e a `assignment_configuration_key` gerada após a assinatura. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler contratos de cessão | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "22.233.344/0001-83", "manager": { "manager_key": "UUID", "document_number": "33.344.455/0001-83", "manager_name": "SAMPLE MANAGER NAME" } }, "assignor": { "assignor_key": "UUID", "document_number": "55.666.777/0001-81", "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": 1000000.0, "external_id": "ID EXTERNO", "case_number": "NÚMERO DO PROCESSO", "denial_reason": null, "observation": "OBSERVAÇÃO", "disbursement_account_key": null, "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ", "products": [ { "product_key": "UUID", "assignment_configuration_key": null, "fund_class_configuration_key": "UUID", "product_type": "assignment_term", "asset_type": "ccb", "status": "pending_contract_signature", "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 Documento Anexo](#definicao-de-documento-anexo)**. | | `products` * | array | Lista de produtos sob o contrato. | Ver **[Definição de Produto](#definicao-de-produto)**. | | `proposal_agent` * | string | Tipo do agente proponente do contrato. | -- | | `status` * | string | Status do contrato. | Ver **[Enumeradores de status do contrato de cessão](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#assignment-contract-status)**. | | `credit_limit` | number | Limite de crédito enviado. | -- | | `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato | Até 50 | | `case_number` | string | Número de caso. Único por fundo | -- | | `denial_reason` | string | Detalhes da recusa do gestor. | Até 500 | | `observation` | string | Observações enviadas. | Até 1000 | | `disbursement_account_key` | string | Conta de desembolso fixada no contrato, quando o template exige uma. | 36 | | `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](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#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. Necessária na esteira de compra de ativos. `null` até o produto ficar `active`. | 36 | | `fund_class_configuration_key` * | string | Configuração do fundo que originou o produto. | 36 | | `product_type` * | string | Tipo do produto (por exemplo, `assignment_term`, `assignment_repurchase`). | -- | | `asset_type` * | string | Tipo do ativo. | -- | | `has_coobligation` * | boolean | Se há coobrigação do cedente. | -- | | `status` * | string | Status do produto. Ver **[Product Status](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#product-status)**. | -- | ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 404 | `ACT000023` | `assignment_contract_key` não encontrado. | | 403 | `ACT000024` | O contrato existe, mas o agente autenticado não é parte dele. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- ## Listagem de Contratos de Cessão Lista os contratos de cessão visíveis para o agente autenticado, com paginação. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler contratos de cessão | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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 do contrato. Aceita vários, separados por vírgula | | `proposal_agent_type` | Quem propôs o contrato: `manager` ou `consultant` | | `case_number` | Número do caso | | `start_date` | Data de início (`YYYY-MM-DD`) | | `end_date` | Data de fim (`YYYY-MM-DD`) | | `page` | Página, começando em `0`. Padrão `0` | | `limit` | Itens por página. Padrão `20`, máximo `100` | Use `is_last_page` da resposta para saber quando parar de paginar. ### Response STATUS 200 ```json title='Response Body' { "data": [ { "assignment_contract_key": "UUID", "fund_class": { "fund_class_key": "UUID", "name": "SAMPLE FUND NAME", "document_number": "22.233.344/0001-83", "manager": { "manager_key": "UUID", "document_number": "33.344.455/0001-83", "manager_name": "SAMPLE MANAGER NAME" } }, "assignor": { "assignor_key": "UUID", "document_number": "55.666.777/0001-81", "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": 1000000.0, "external_id": "ID EXTERNO", "case_number": "NÚMERO DO PROCESSO", "denial_reason": null, "observation": "OBSERVAÇÃO", "disbursement_account_key": null, "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ", "products": [ { "product_key": "UUID", "assignment_configuration_key": null, "fund_class_configuration_key": "UUID", "product_type": "assignment_term", "asset_type": "ccb", "status": "pending_contract_signature", "has_coobligation": true } ], "signature_batch_key": "UUID" } ], "limit": 20, "page": 0, "is_last_page": true } ``` ### Erros | Status | Código | Quando acontece | |--------|--------|-----------------| | 400 | — | `limit` acima de `100` ou `page` negativo. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Enumeradores Os status do contrato, dos produtos e dos documentos estão em [Criação do Contrato › Enumeradores](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#enumeradores). --- # Webhooks do contrato URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato --- O contrato de cessão envia dois tipos de webhook: um a cada mudança de status do contrato e um quando um produto do contrato é ativado. Os dois são enviados para a gestora, para o cedente e, se houver, para a consultoria do contrato — para cada um que tenha webhook configurado. Assinatura, reenvio e configuração: veja [Autenticação de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ## Mudança de status do contrato `webhook_type`: `assignment_contract.assignment_contract_status_change` ```json title='Webhook Body' { "data": { "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "status": "denied", "external_id": "Contrato número 550", "denial_reason": "Documentação do cedente insuficiente" }, "webhook_type": "assignment_contract.assignment_contract_status_change", "webhook_datetime": "2025-01-22T20:30:23Z" } ``` | Campo | Descrição | |-------|-----------| | `data.assignment_contract_key` | Chave do contrato. | | `data.status` | Novo status do contrato. Ver [Enumeradores](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#assignment-contract-status). | | `data.external_id` | `external_id` enviado no pedido do contrato, ou `null`. | | `data.denial_reason` | Motivo da recusa informado pela gestora. `null` fora do status `denied`. | | `data.assignment_contract_new_status` | Só presente quando `status` é `signed`, com o valor `contract_signed`. | Exemplo do contrato assinado: ```json title='Webhook Body' { "data": { "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "status": "signed", "external_id": "Contrato número 550", "denial_reason": null, "assignment_contract_new_status": "contract_signed" }, "webhook_type": "assignment_contract.assignment_contract_status_change", "webhook_datetime": "2025-01-22T20:30:23Z" } ``` Status que disparam o webhook: | Status | Quando | |--------|--------| | `pending_manager_approval` | Contrato proposto pela consultoria aguarda a decisão da gestora. | | `pending_assignor_registry_release` | O cadastro do cedente ainda está em análise. | | `pending_signature_submission` | O template exige envio manual para assinatura. | | `sending_to_signature` | O contrato está sendo enviado à CertifiQI. | | `pending_signature` | Disponível para assinatura das partes. | | `waiting_escrow_data` / `pending_escrow_activation` | Etapas de conta escrow (só em templates com conta escrow). | | `signed` | Todos os documentos foram assinados. Os produtos começam a ser ativados. | | `suspended` | Contrato suspenso; os produtos ficam `inactive`. Volta a `signed` na reativação. | | `denied` | A gestora recusou o contrato. | | `canceled` | O contrato foi cancelado. | ## Produto ativado `webhook_type`: `assignment_contract.product_status_change` Enviado quando a esteira de cessão de um produto termina de ser configurada, depois da assinatura do contrato. É aqui que chega a `assignment_configuration_key`, usada para ceder ativos entre o fundo e o cedente. Contratos com mais de um produto geram um webhook por produto. ```json title='Webhook Body' { "data": { "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "assignment_configuration_key": "372f0449-4043-4523-9f0f-dff70c65b9c9", "status": "active", "product_new_status": "active" }, "webhook_type": "assignment_contract.product_status_change", "webhook_datetime": "2025-01-22T20:30:23Z" } ``` | Campo | Descrição | |-------|-----------| | `data.product_key` | Chave do produto. Para saber a qual contrato ele pertence, consulte o contrato em [Consulta de Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato). | | `data.assignment_configuration_key` | Chave da configuração de cessão criada para o produto. | | `data.status` / `data.product_new_status` | Sempre `active` neste webhook. | --- # 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 seções, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que sejam feitas as devidas liberações, tanto em sandbox quanto em 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 ANBIMA. 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. :::caution 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, o caso mais comum é a análise que permanece 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](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato), a partir de um template, que irá disparar internamente a criação do contrato e envio para assinatura. Os produtos do contrato (por exemplo, cessão de um tipo de ativo ou recompra) são definidos pelo template. Uma vez com o contrato assinado, cada produto é ativado automaticamente — não há chamada de ativação. Ao final, enviamos o webhook `assignment_contract.product_status_change` com a chave da Configuração de Cessão gerada (`assignment_configuration_key`), identificador que será utilizado posteriormente no processo de compra e venda de ativos. Veja [Webhooks do Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato). --- # Integração via SFTP URL: /documentation/iaas/integracao_sftp/inicio O SFTP (Secure File Transfer Protocol) é o canal pelo qual a QI DTVM 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 em 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 DTVM** | `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: ```text 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 DTVM 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 DTVM | | `PORT` | 22 | | `USERNAME` | Usuário, informado pela QI DTVM | | **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 DTVM PORT = 22 USERNAME = "usuario" # informado pela QI DTVM PRIVATE_KEY = "/caminho/para/sftp_qitech" # a chave privada que você gerou KNOWN_HOSTS = "/caminho/para/known_hosts" # com o host key da QI DTVM 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 QI DTVM envia cada webhook como um `POST` com body JSON para a URL que você configurou. A requisição leva o header `SIGNATURE`, um JWT assinado com HS256 usando a _Signature Key_ da sua configuração de webhook: uma chave simétrica, que só a QI e você conhecem. ## Validar a assinatura ```python import json from hashlib import md5 from jose import jwt signature_key = "SUA_SIGNATURE_KEY" webhook_url = "https://sua-empresa.com.br/webhooks/qi" # a URL cadastrada na configuração def validate_webhook(headers: dict, raw_body: bytes) -> dict: # jwt.decode recusa o token se a assinatura não bater com a sua Signature Key. claims = jwt.decode(headers["SIGNATURE"], key=signature_key, algorithms=["HS256"]) if claims["uri"] != webhook_url: raise ValueError("uri diferente da URL configurada") if claims.get("payload_md5") != md5(raw_body).hexdigest(): raise ValueError("payload_md5 não corresponde ao body recebido") return json.loads(raw_body) ``` O JWT decodificado traz: | Campo | Descrição | | ------------- | --------------------------------------------------------------------------------------- | | `timestamp` | Data e hora da assinatura, em UTC, no formato `AAAA-MM-DDTHH:MM:SS`. Muda a cada envio. | | `method` | Método HTTP da requisição: `POST`. | | `uri` | A URL de destino configurada para o seu webhook, completa. | | `payload_md5` | Hash MD5 do body enviado. | Calcule o MD5 sobre os **bytes recebidos**, antes de fazer o parse do JSON. Um _re-encode_ do JSON depois do parse muda espaçamento e ordem dos campos, e o hash deixa de bater. ## Formato do body Todo webhook tem o mesmo envelope. O conteúdo de `data` depende do evento e está na página de webhooks de cada produto. ```json { "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2026-10-07T14:32:10Z", "data": {} } ``` | Campo | Descrição | | ------------------ | ------------------------------------------------------------------------- | | `webhook_type` | Evento, no formato `.`. | | `webhook_datetime` | Data e hora em que o evento foi gerado. É a mesma em todas as tentativas. | | `data` | Dados do evento: um objeto ou uma lista, conforme o evento. | :::danger Atenção! Não mapeie os webhooks de forma restrita: campos novos podem ser incluídos no envelope e em `data` a qualquer momento. ::: ## Header `AGENT-KEY` O header `AGENT-KEY` traz a chave do **agente dono da configuração de webhook**, ou seja, a sua chave: o `manager_key` da gestora, o `consultant_key` da consultoria ou o `assignor_key` do cedente. Ele não identifica o fundo. Para saber de qual fundo é o evento, use os campos de `data`, como `fund_class_key`. ## Entrega e tentativas - A entrega conta como bem-sucedida quando a sua URL responde com status HTTP **menor que 300** em até **30 segundos**. Qualquer outro status, timeout ou erro de rede conta como falha. - Cada evento é enviado **até 4 vezes**. Depois da 4ª falha, ele é marcado como falho e não é mais reenviado automaticamente. - Responda rápido: grave o webhook e processe depois. O tempo que a sua aplicação leva para processar conta para os 30 segundos. :::info Webhook que não chegou Um webhook que esgotou as tentativas pode ser reenviado pela QI DTVM. Fale com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) informando o período e o tipo de evento. O reenvio não é uma operação disponível na sua integração. ::: ## Duplicatas Você pode receber o mesmo webhook mais de uma vez, por dois motivos: 1. A sua aplicação recebeu o webhook, mas a resposta não chegou à QI dentro do prazo. O envio é repetido. 2. O mesmo evento pode ter de ser entregue a mais de um agente: por exemplo, à gestora, à consultoria e ao cedente do fundo. Esses envios são tentados juntos e em sequência. Se a URL de **qualquer** um deles falhar, a tentativa inteira é repetida, e quem já tinha recebido recebe de novo. O segundo caso significa que uma falha na URL de outro agente gera duplicatas na sua. Trate o recebimento como idempotente: a repetição chega com o **mesmo body, byte a byte** (o mesmo `webhook_type`, `webhook_datetime` e `data`), então o mesmo `payload_md5`. Guarde o `payload_md5` dos webhooks já processados e descarte o que repetir. Não use o JWT do header para isso: o `timestamp` muda a cada envio. ## Validação de origem Além de validar a assinatura, você pode restringir a sua URL aos IPs de saída da QI: | Ambiente | IP | | -------- | -------------- | | Produção | 54.205.166.229 | | Sandbox | 52.72.221.4 | --- # Erros da API URL: /documentation/iaas/introducao/erros Toda resposta de erro das APIs do IaaS tem o mesmo corpo. O status HTTP e o `code` dizem o que aconteceu; o prefixo do `code` diz em que área. ## Formato do corpo de erro | Campo | Tipo | Descrição | | ------------- | ------ | ------------------------------------------------------------------------------------------------------ | | `title` | string | Nome curto do erro, em inglês. | | `description` | string | Descrição em inglês. Em erros de validação, traz o campo que falhou. | | `translation` | string | Descrição em português. | | `code` | string | Três letras que indicam a área, seguidas de seis dígitos. Use este campo no seu tratamento de erro. | Exemplo: uma integração de gestora sem a permissão de escrita chamando um `POST`. ```json { "title": "Manager does not have permission to access this endpoint", "description": "Manager does not have permission to access this endpoint", "translation": "Gestor nao tem permissão para acessar esse endpoint", "code": "MIT000017" } ``` Trate o erro pelo status HTTP e pelo `code`. Os textos de `title`, `description` e `translation` podem mudar. ## Prefixo do `code` | Prefixo | Onde o erro aconteceu | | ------- | ------------------------------------------------------------------------------------------------------------- | | `MIT` | Host da gestora (`manager-api`): autenticação, permissão e roteamento. | | `CIT` | Host da consultoria (`consultant-api`): autenticação, permissão e roteamento. | | `AIT` | Host do cedente (`assignor-api`): autenticação, permissão e roteamento. | | `QIT` | Erro genérico, em qualquer host ou serviço: rota inexistente, método não aceito, body inválido, erro interno. | | `SET` | Liquidação de ativos (`/settlement`). | | `TRC` | Cessão de recebíveis (`/trade_receivables`). | | `TRF` | Arquivos de cessão (`/trade_receivables_files`). | | `TRR` | Venda e recompra de ativos (`/trade_resolve`). | | `TTR` | Boletador de títulos públicos (`/trade_treasury`). | | `ASR` | Homologação de cedente (`/assignor_registry`). | | `ASS` | Cedentes (`/assignor`). | | `ACT` | Contrato de cessão (`/assignment_contract`). | | `AAM` | Aditamento de recebíveis (`/asset_amendment`). | | `ADF` | Documentos de ativos (`/asset_document_files`). | | `BSC` | Boletos (`/bankslip_collection`). | | `CSH` | Contas e extrato (`/cash_account`). | | `TSF` | Transferência interna (`/transfer`). | | `TRV` | Estorno de transação (`/transaction_reversal`). | | `CMP` | Composição de carteira (`/composition`). | | `WLT` | Carteira (`/wallet`). | | `EXP` | Despesas (`/expense`). | | `IVR` | Cadastro de investidor (`/investor_registry`). | | `IAD` | Termo de adesão (`/investor_adhesion`). | | `QTA` | Cotas (`/quota`). | | `QOF` | Controle de oferta (`/quota_offering_control`). | | `TFQ` | Cotas de fundo como ativo (`/trade_fund_quota`). | Um `400` com `code` `QIT000001` indica corpo da requisição inválido: o campo com problema vem em `description`. ## Autenticação Os erros de header, chave de API e assinatura (`*000007` a `*000016` e `*000020`) e como corrigir cada um estão em [Teste de autenticação](/documentation/iaas/introducao/teste_de_autenticacao#erros-de-autenticacao). ## Permissão e rota Depois de autenticar a requisição, o host confere se a sua integração pode chamar aquela rota. Falta de permissão volta como **401**, não 403: não procure erro de assinatura quando o `code` for um destes. | Status | `code` | Quando acontece | O que fazer | | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 401 | `MIT000017` | A integração da gestora não tem a permissão que a rota exige: **Leitura**, **Escrita** ou as duas. | Confira a permissão no bloco "Disponível em" da página do endpoint e o status em **Permissões**, na tela da integração. Veja [liberação das permissões](/documentation/iaas/introducao/integracao_via_portal#6-liberacao-das-permissoes-da-integracao). | | 401 | `CIT000018` | A consultoria não tem vínculo ativo com o fundo (`fund_class_key`) ou não tem, nesse fundo, a permissão que a rota exige. | Confira o `fund_class_key` e a permissão indicada em "Disponível em". As permissões da consultoria são dadas por fundo. Se a permissão aparece como **Liberada pelo time de integração**, ela não é configurável no portal: peça a liberação em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). | | 401 | `AIT000017` | A integração do cedente não tem a permissão de leitura ou escrita que a rota exige. | Fale com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). | | 400 | `*000009` | A integração está desativada. | Reative a integração ([como](/documentation/iaas/introducao/integracao_via_portal#desativar-e-reativar-a-integracao)) ou fale com o time de integração. | | 404 | `QIT000404` | O host não expõe esse caminho. | Numa rota documentada, quase sempre é a URL base de outro perfil: confira o bloco "Disponível em" da página e a [URL base do seu perfil](/documentation/iaas/introducao/inicio#ambientes-hosts). Confira também o caminho, sem a `base_url`. | | 405 | `QIT000405` | O caminho existe no host, mas não com esse método. | Confira o método na página do endpoint. | ## Reenvio e duplicidade Em caso de erro, reenvie a requisição. Se o recurso já existir, a criação devolve um erro de duplicidade em vez de criar outro: consulte o recurso existente. | Criação | `code` de duplicidade | Status | Como consultar o recurso existente | | ----------------------------------------- | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lote de pagamento (liquidação) | `SET000009` | 409 | [Recuperação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao), pelo `external_id` do lote. | | Liquidação dentro de um lote | `SET000013` | 400 | [Recuperação da liquidação](/documentation/iaas/liquidacao_ativos/ativos/recuperacao), pelo `external_id` da liquidação. | | Lote de venda ou recompra | `TRR000015` | 409 | `GET /trade_resolve/fund_class/{fund_class_key}/assignment/{assignment_external_id}`, exposto só no host do cedente. Gestora e consultoria não têm essa consulta. | | Operação do boletador de títulos públicos | `TTR000044` | 409 | `GET /trade_treasury/fund_class/{fund_class_key}/operations`, procurando o seu `external_id` na lista. | :::caution Boletador: sempre envie `external_id` No boletador o `external_id` é opcional. Envie-o sempre: sem ele, a API não reconhece uma operação já criada. ::: ## Erro interno `500` com `QIT000500` é erro do lado da QI. Se persistir, envie a requisição (sem a chave privada), o horário em UTC e o `code` para [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). --- # Introdução URL: /documentation/iaas/introducao/inicio A QI DTVM é 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 DTVM. Possuímos 6 perfis: 1. Gestores; 2. Consultores; 3. Originadores; 4. Cedentes; 5. Investidores; 6. Distribuidores. Cada perfil tem um host próprio, com as rotas liberadas para ele — veja [Ambientes (Hosts)](#ambientes-hosts). 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). ## Por onde começar 1. Crie a integração: [Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal) (gestoras e consultorias) ou [Troca de chaves](/documentation/iaas/introducao/troca_de_chaves) (demais perfis). 2. Faça a primeira chamada: [Teste de autenticação](/documentation/iaas/introducao/teste_de_autenticacao). 3. Saiba ler os erros e reenviar com segurança: [Erros da API](/documentation/iaas/introducao/erros). ## Ambientes (Hosts) A QI DTVM 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. Além dos hosts por perfil, há um host público em 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 criar novas integrações 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** - Consultoria: **Gerenciar integração com a API** 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. Elas ficam no bloco **Credenciais**, no fim da tela, e podem ser copiadas a qualquer momento pelo mesmo caminho: ![Bloco Credenciais da tela da integração no portal, com a API Key e a URL base da API em destaque](/img/iaas-portal-credenciais.webp) | Credencial | Para que serve | | ---------- | -------------- | | **API Key** | Vai no header `API-CLIENT-KEY` de todas as requisições. É o `api_key` do [Teste de autenticação](/documentation/iaas/introducao/teste_de_autenticacao). | | **URL base da API** | O host que recebe as chamadas desta integração, já no perfil e no ambiente do portal. É o `base_url` do [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. | A chave de API só é aceita nessa URL: o host do seu perfil (`manager-api` no Portal do Gestor, `consultant-api` no Portal do Consultor), no ambiente em que a integração foi criada. A lista completa de hosts está em [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). Uma mesma gestora ou consultoria pode manter **várias integrações ativas ao mesmo tempo**, cada uma com sua própria chave de API e 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. :::caution A chave pública não pode ser trocada Cada integração recebe uma única chave pública. Se precisar de outra chave — por rotação periódica, perda ou vazamento da chave privada —, crie uma nova integração. Veja [Substituir a chave de uma integração](#substituir-a-chave-de-uma-integracao). ::: 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. ::: ## 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. Como a chave não pode ser trocada, não reative a integração comprometida: substitua-a por uma nova. ## Substituir a chave de uma integração Para passar a usar outra chave sem interromper a operação: 1. Crie uma nova integração ([etapa 4](#4-criar-a-integracao)) e cadastre nela a nova chave pública ([etapa 5](#5-cadastrar-a-chave-publica)). 2. Para gestoras, aguarde a liberação das permissões da nova integração ([etapa 6](#6-liberacao-das-permissoes-da-integracao)). 3. Atualize a sua aplicação com a **nova chave de API** e a **nova chave privada** — as duas mudam juntas. 4. Rode o [Teste de autenticação](/documentation/iaas/introducao/teste_de_autenticacao) com as novas credenciais. 5. Desative a integração antiga. Os webhooks não precisam ser reconfigurados: a configuração vale para a gestora ou consultoria, não por integração. ## 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 O pacote de endpoints é um conjunto de scripts Python, um por chamada da API do IaaS, organizados nas mesmas seções desta documentação. Cada script monta os headers `API-CLIENT-KEY` e `AUTHORIZATION`, envia a requisição e imprime o status e a resposta. Serve para quem está integrando e quer testar uma chamada em sandbox sem escrever a assinatura do zero. **[Baixar o pacote (.zip)](/downloads/integracao_python_iaas.zip)** ## Configurar 1. Instale as dependências: `pip install -r requirements.txt`. 2. Copie `.env.example` para `.env`, na raiz do pacote, e preencha: | Variável | O que é | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `BASE_URL` | URL base do host do **seu perfil** e ambiente. Veja [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). | | `API_KEY` | Chave de API da sua integração. | | `PRIVATE_KEY_PATH` | Caminho do arquivo `.pem` da sua chave privada. | | `ALGORITHM` | O algoritmo da sua chave: `RS256` para RSA; `ES256`, `ES384` ou `ES512` para EC P-256, P-384 ou P-521. A chave EC P-521 da [troca de chaves](/documentation/iaas/introducao/troca_de_chaves) usa `ES512`. | 3. Abra o script, troque os valores marcados com ` ` e rode. Comece por `5.1 - Primeiros passos/5.1 - GET Teste de autenticação.py`. :::caution A chave de API só funciona no host do seu perfil Nem toda chamada existe em todos os hosts. O cabeçalho de cada script lista os hosts que expõem aquela chamada, e o `README.md` do pacote traz a tabela por pasta. Chamada para o host de outro perfil é recusada com `Invalid API Key`. ::: :::danger Aviso Importante! Os scripts usam CPFs e CNPJs fictícios. Não use dados reais de pessoas físicas ou jurídicas em sandbox. ::: --- # Endpoints de teste URL: /documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste `/authentication_test` responde `200` só quando o host, a chave de API e a assinatura estão corretos. Use o `GET` para testar uma requisição sem body e o `POST` para testar também o `payload_md5`. Como montar os headers: [Teste de autenticação](/documentation/iaas/introducao/teste_de_autenticacao). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | — | | Consultoria | `consultant-api` | — | | Cedente | `assignor-api` | — | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## GET ENDPOINT /authentication_test MÉTODO GET Sem body e sem `payload_md5` na assinatura. ### Response STATUS 200 ```json { "success": "Congrats!" } ``` ## POST ENDPOINT /authentication_test MÉTODO POST ### Atributos do body name string obrigatório Qualquer texto de 1 a 255 caracteres. A resposta devolve o mesmo valor. O body não aceita outros campos. ```json { "name": "QI Tech" } ``` ### Response STATUS 200 ```json { "name": "QI Tech", "success": "Congrats!" } ``` ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ----------------------------------------------------------------------------------------------- | | 400 | `QIT000001` | `POST` sem `name`, com `name` vazio, com outro campo além de `name` ou com body que não é JSON. | | 401 | `*000008` | Chave de API inválida. Quase sempre é a URL base de outro perfil. | | 401 | `*000016` | O `payload_md5` assinado não bate com os bytes enviados no `POST`. | Os demais erros de assinatura estão em [Erros de autenticação](/documentation/iaas/introducao/teste_de_autenticacao#erros-de-autenticacao). Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Teste de autenticação URL: /documentation/iaas/introducao/teste_de_autenticacao/ Toda requisição às APIs da QI DTVM leva dois headers: - `API-CLIENT-KEY`: a chave de API da sua integração. - `AUTHORIZATION`: um JWT assinado com a **sua** chave privada. A QI valida a assinatura com a chave pública que você cadastrou na [troca de chaves](/documentation/iaas/introducao/troca_de_chaves). Esta página monta os dois headers em Python e chama `/authentication_test`, que só responde `200` quando host, chave de API e assinatura estão corretos. Faça este teste antes de qualquer outra chamada. ## 1. Escolha a URL base do seu perfil Este é o erro mais comum na primeira chamada: copiar o exemplo com o host de outro perfil. :::tip Gestoras e consultorias Copie a URL base direto do portal: ela aparece no bloco **Credenciais** da integração, ao lado da API Key, já no perfil e no ambiente certos. Veja a imagem no passo 3. ::: ## 2. Instale e importe as bibliotecas ```bash pip install "python-jose[cryptography]" requests ``` ```python from datetime import datetime, timezone import json from hashlib import md5 from jose import jwt import requests ``` ## 3. Informe a chave de API, a chave privada e o algoritmo ```python title="Dados da criptografia" api_key = "SUA_API_KEY" client_private_key = """-----BEGIN PRIVATE KEY----- SUA_CHAVE_PRIVADA -----END PRIVATE KEY-----""" algorithm = "RS256" # o algoritmo da sua chave; veja a tabela abaixo ``` Onde encontrar cada valor depende de como a sua integração foi criada: | Valor | Gestoras e consultorias (portal) | Cedentes, originadores, investidores e distribuidores | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `api_key` | No portal, em **Gestão de Acesso > Integração API**: abra a integração e copie o campo **API Key** do bloco **Credenciais**. | Enviada pelo time de integração da QI depois da [troca de chaves](/documentation/iaas/introducao/troca_de_chaves). | | `client_private_key` | O arquivo `qi-integration-...-private-key.pem` baixado ao gerar o par no portal, ou a chave privada do par que você mesmo gerou. | A chave privada do par que você gerou na [troca de chaves](/documentation/iaas/introducao/troca_de_chaves). | | `algorithm` | O indicado no portal abaixo do algoritmo escolhido: `RS256` para RSA (padrão do portal), `ES256`, `ES384` ou `ES512` para EC P-256, P-384 ou P-521. | `ES512`, para a chave EC P-521 gerada na troca de chaves. | ![Bloco Credenciais da tela da integração no portal, com a API Key e a URL base da API em destaque](/img/iaas-portal-credenciais.webp) Cole o conteúdo inteiro do arquivo da chave privada, com as linhas `BEGIN` e `END` — o cabeçalho pode ser `PRIVATE KEY` ou `EC PRIVATE KEY`, conforme a ferramenta que gerou o par. A chave de API identifica a integração, e a assinatura com a chave privada prova que a requisição é sua: trate as duas como credenciais. A chave privada nunca é enviada à QI. Em produção, carregue a chave privada de um cofre de segredos ou variável de ambiente — nunca a deixe no código-fonte. O passo a passo do portal, da criação da integração ao cadastro da chave pública, está em [Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal). ## 4. Defina os dados da requisição ```python title="Dados da requisição" # Troque pela URL do seu perfil e ambiente (tabela do passo 1). base_url = "URL_BASE_DO_SEU_PERFIL" # ex.: "https://manager-api.sandbox.qidtvm.com.br" 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. Monte o conteúdo da assinatura ```python title="Dicionário base" timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S") dict_to_sign = {"timestamp": timestamp, "method": method, "uri": endpoint} ``` O `timestamp` segue o formato `AAAA-MM-DDTHH:MM:SS`, sem fuso e sem milissegundos, é sempre em **UTC** e é aceito com até **10 minutos** de diferença do horário da QI. Gere um novo a cada requisição e mantenha o relógio do servidor sincronizado. ### 5.1. Se houver body, adicione o MD5 Requisições com _body_ incluem o MD5 dos bytes exatos que serão enviados: ```python title="Dicionário base" body_bytes = json.dumps(body).encode() dict_to_sign["payload_md5"] = md5(body_bytes).hexdigest() ``` Envie exatamente esses `body_bytes` no passo 7. Se o JSON for serializado de novo — com outra ordem de campos, espaçamento ou acentuação —, o MD5 deixa de bater. ## 6. Assine o JWT ```python encoded_header_token = jwt.encode( claims=dict_to_sign, key=client_private_key, algorithm=algorithm, headers={"alg": algorithm, "typ": "JWT"}, ) ``` O `algorithm` precisa ser da família da chave: `RS*` para RSA e `ES*` para EC. Se não for, o `jwt.encode` falha antes de a requisição sair, com um `JWSError` pouco descritivo — confira o `algorithm` primeiro. ## 7. Envie a requisição ```python headers = { "API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token, "Content-Type": "application/json", } resp = requests.post(url=f"{base_url}{endpoint}", headers=headers, data=body_bytes) print(resp.status_code, resp.json()) ``` A resposta esperada é `200` com `{"name": "QI Tech", "success": "Congrats!"}`. O contrato de `GET` e `POST /authentication_test` está em [Endpoints de teste](/documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste). ## Erros de autenticação O `code` dos erros de autenticação termina com o mesmo número em todos os hosts. O **prefixo** indica qual host respondeu: `MIT` para `manager-api`, `CIT` para `consultant-api` e `AIT` para `assignor-api`. Se o prefixo não é o do seu perfil, a `base_url` está errada. | Final do `code` | Status | Erro | O que verificar | | --------------- | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------ | | `000007` | 401 | Header ausente | Os dois headers, `API-CLIENT-KEY` e `AUTHORIZATION`, foram enviados. | | `000008` | 401 | Chave de API inválida | A `base_url` é a do seu perfil e do ambiente certo, e a chave de API foi copiada sem espaços. | | `000009` | 400 | Integração inativa | A integração está ativa. Fale com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). | | `000010` | 401 | Chave pública pendente | A chave pública já foi cadastrada na integração. | | `000011` | 401 | Autenticação inválida | O JWT foi assinado com a chave privada que corresponde à chave pública cadastrada. | | `000012` | 401 | Assinatura incompleta | O JWT tem os campos `timestamp`, `method` e `uri`. | | `000013` | 401 | Método inválido | O `method` assinado é o mesmo da requisição, em maiúsculas. | | `000014` | 401 | Assinatura expirada | O `timestamp` está em UTC, foi gerado na hora da requisição e o relógio do servidor está sincronizado. | | `000015` | 401 | Endpoint inválido | O `uri` assinado é idêntico ao caminho enviado, incluindo a _query string_ e sem a `base_url`. | | `000016` | 401 | MD5 inválido | O `payload_md5` foi calculado sobre os mesmos bytes enviados no body. | | `000020` | 401 | Formato de timestamp | O `timestamp` está no formato `AAAA-MM-DDTHH:MM:SS`, sem fuso e sem milissegundos. Só `manager-api` e `consultant-api` devolvem este código: no `assignor-api`, timestamp fora do formato volta como erro `500`. | Erros de permissão, de rota e dos serviços estão em [Erros da API](/documentation/iaas/introducao/erros). ## 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 é invalido", "code": "MIT000015" } ``` ### Exemplo ```python title="GET com paginação" # base_url do passo 4. Este endpoint é da gestora (manager-api). 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" timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S") dict_to_sign = {"timestamp": timestamp, "method": method, "uri": uri} encoded_header_token = jwt.encode( claims=dict_to_sign, key=client_private_key, algorithm=algorithm, headers={"alg": algorithm, "typ": "JWT"}, ) 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 Esta página é para **cedentes, originadores, investidores e distribuidores**: você gera o par de chaves e envia a chave pública ao time de integração da QI Tech. :::info Gestoras e consultorias Gestoras e consultorias cadastram a chave pública e recebem a chave de API pelo próprio portal, sem enviar chaves por e-mail. Siga [Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal). ::: ## 1. Requisição assinada Todas as requisições às APIs da QI DTVM usam **HTTPS**, com **TLS 1.2 ou 1.3**, e levam dois headers: 1. `API-CLIENT-KEY`: a chave de API que identifica a sua integração, enviada pelo time de integração. 2. `AUTHORIZATION`: um JWT assinado com a sua chave privada, montado como em [Teste de autenticação](/documentation/iaas/introducao/teste_de_autenticacao). A QI DTVM usa chaves assimétricas: a **chave privada** assina as requisições e a **chave pública** permite à QI validar a assinatura. Você gera o par e entrega à QI só a chave pública. :::caution Atenção A chave privada é de uso exclusivo da sua empresa e deve ser armazenada com segurança. A QI DTVM nunca vai pedir que você a compartilhe. ::: ## 2. Gerar o par Em um terminal UNIX, gere a chave privada EC P-521: ```bash ssh-keygen -t ecdsa -b 521 -m PEM -f private.key ``` A partir dela, gere a 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`. Só esse arquivo é enviado à QI. Ao assinar as requisições com a `private.key`, use o algoritmo **`ES512`**, que corresponde à curva P-521. ## 3. Entregar a chave pública Envie o arquivo `public.key.pub` para [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) e aguarde a configuração da integração. O time de integração responde com a chave de API do seu perfil. A chave de API só funciona no host desse perfil: veja [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ## 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-api` Distribuição Externa investidores cadastrados por conta e ordem por meio de distribuidores parceiros `distributor-api` Cadastrar como Gestor / Consultor gestores (`manager-api`) e consultores (`consultant-api`) 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 a análise, a QI Tech pode pedir um esclarecimento ou complemento por meio de um feedback, que fica disponível na própria análise cadastral. O feedback é respondido por mensagem: a análise não muda de status, não volta para o preenchimento e não precisa ser reenviada. Veja [Ciclo de vida da análise cadastral](/documentation/iaas/investidor/cadastro/ciclo_de_vida_da_analise#feedback). - **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 ou recusa do cadastro, com eventuais pedidos de esclarecimento por feedback - **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. --- # atualizar_status_grupo_assinantes URL: /documentation/iaas/investidor/cadastro/atualizar_status_grupo_assinantes :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # busca_informacoes_de_uma_analise_cadastral_do_investidor URL: /documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # busca_informacoes_do_investidor URL: /documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # buscar_documentos_para_assinatura URL: /documentation/iaas/investidor/cadastro/buscar_documentos_para_assinatura :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # Listar investidores URL: /documentation/iaas/investidor/cadastro/buscar_investidores_paginado --- ### Introdução Este recurso lista os investidores vinculados à sua integração, com filtros opcionais e 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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 | — | Documento completo (busca exata) | | `status` | string | — | Status do investidor (ver [Investor Status](#investor-status)) | | `status_in` | string | — | Lista de status separados por vírgula | | `status_not_in` | string | — | Lista de status a excluir, separados por vírgula | | `last_analysis_status_in` | string | — | Status da análise cadastral mais recente, separados por vírgula | | `name` | string | — | Parte do nome (sem diferenciar maiúsculas) | | `expires_before` | date | — | Cadastros que vencem antes desta data (`YYYY-MM-DD`) | | `expires_after` | date | — | Cadastros que vencem depois desta data (`YYYY-MM-DD`) | | `order_by` | string | — | `created_at` ou `updated_at`. Sem este parâmetro, os mais recentes primeiro | | `order_direction` | string | `desc` | `asc` ou `desc` | | `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": "registered", "person_type": "natural_person", "investor_key": "UUID v4", "document_number": "969.698.790-03", "email": "investidor1@exemplo.com", "phone": { "international_dial_code": "55", "area_code": "11", "number": "999990001" }, "current_analysis": { "investor_analysis_key": "UUID v4", "status": "analysis_complete" }, "distributor": { "distributor_key": "UUID v4", "name": "Distribuidora XYZ", "document_number": "33444555000181", "registry_configuration": {} } }, { "name": "investidor 2", "status": "pending_analysis", "person_type": "natural_person", "investor_key": "UUID v4", "email": "investidor2@exemplo.com", "phone": { "international_dial_code": "55", "area_code": "11", "number": "999990002" }, "distributor": { "distributor_key": "UUID v4", "name": "Distribuidora XYZ", "document_number": "33444555000181", "registry_configuration": {} } } ], "limit": 100, "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` | object | Telefone de contato do investidor, no formato de **[Phone](/documentation/iaas/investidor/cadastro/criar_investidor#phone)** | | `document_number` | string | CPF ou CNPJ do investidor | | `current_analysis` | object | Resumo da análise cadastral atual: `investor_analysis_key`, `status` e, quando houver, `investor_category`, `suitability` e `investor_sub_type` | | `registry_expiration_date` | string | Data de vencimento do cadastro, quando houver | | `distributor` | object | Objeto de **Distributor** | :::info Consultoria Para a consultoria, cada item de `data` traz o objeto completo do investidor, no mesmo formato de [Busca informações do investidor](/documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor). Os campos acima descrevem a resposta para a gestora. ::: ### 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 | ### Investor Status {#investor-status} | Enumerador | Descrição | |------------------------|---------------------------------------------| | `created` | Criado | | `pending_analysis` | Investidor recém-criado, ainda sem nenhum cadastro aprovado. Uma nova análise sobre um investidor `registered` não o devolve a este status | | `incomplete` | Cadastro incompleto | | `registered` | Cadastro aprovado e concluído | | `registry_expired` | Cadastro vencido | | `non_operational` | Não operacional | | `inactive` | Inativo | ## Erros | Status | Código | Quando acontece | | ------ | ------ | --------------- | | 400 | — | `limit` acima de 500 ou `page` negativo | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # consultar_detalhes_assinatura URL: /documentation/iaas/investidor/cadastro/consultar_detalhes_assinatura :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). O consultor precisa estar vinculado ao investidor (vínculo não revogado). Sem o vínculo, a chamada é recusada com `QIT000011`. ::: --- # atualizar_status_conta_bancaria URL: /documentation/iaas/investidor/cadastro/contas_bancarias/atualizar_status_conta_bancaria :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # definir_conta_principal URL: /documentation/iaas/investidor/cadastro/contas_bancarias/definir_conta_principal :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_contas_bancarias URL: /documentation/iaas/investidor/cadastro/contas_bancarias/enviar_contas_bancarias :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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 Regra de aprovação em sandbox Em sandbox, o resultado da análise depende do primeiro dígito do CPF/CNPJ: início **1** → reprovação automática; início **8** → análise manual; os demais são aprovados automaticamente. ::: :::info Usuário de acesso do investidor Por padrão, a criação também cria o usuário de acesso do investidor na plataforma (query param `create_investor_user`, default `true`). Se o investidor não vai preencher o próprio cadastro, envie `?create_investor_user=false`. ::: ### 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). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "969.698.790-03", "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": "22.333.444/0001-81", "person_type": "legal_person", "investor_sub_type": "default", "registry_user": { "name": "José da Silva", "document_number": "969.698.790-03", "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": "22.333.444/0001-81", "person_type": "legal_person", "investor_sub_type": "fund_class" } ``` :::caution Campos obrigatórios 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`, **`email` e `phone`** - **`legal_person`**: `name`, `document_number`, `person_type`. Para `fund_class`, não envie `registry_user` — a representação é feita pelos *investor owners* (administrador e gestora) **`investor_sub_type` é opcional.** Se omitido, pessoa física fica `default` e, para pessoa jurídica residente, o subtipo é identificado pelo CNPJ: `financial_institution` se for uma instituição financeira registrada, `fund_class` se for uma classe registrada na CVM e `default` nos demais casos. Se você informar o subtipo, ele precisa bater com o CNPJ (veja [Erros](#erros)). ::: :::caution Classes de fundo: quem pode cadastrar Pela gestora (`manager-api`), a criação de um investidor `fund_class` só é aceita se o CNPJ da gestora constar na CVM como gestora ou administradora da classe; caso contrário, `IVR000260`. A administradora e a gestora da classe também precisam estar cadastradas como investidoras na QI Tech. Veja **[Introdução](/documentation/iaas/investidor/cadastro/introducao)** para o detalhamento. ::: :::caution 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](/documentation/iaas/investidor/cadastro/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)**. Se omitido, é inferido (veja acima) | - | Não | | `email` | string | E-mail do investidor. Obrigatório para `natural_person` | 1 - 255 | Condicional | | `phone` | object | Objeto de **[Phone](#phone)**. Obrigatório para `natural_person` | - | Condicional | | `registry_user` | object | Objeto de **[Registry User](#registry-user)** | - | Não | | `resident` | boolean | Se o investidor é residente no Brasil. Default `true` | - | Não | | `non_resident_type` | string | `self_representation` ou `third_party_representation`. Obrigatório quando `resident: false` | - | Condicional | ### 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)** | - | Não | ### 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` | Investidor regular, pessoa física ou jurídica | | `financial_institution` | Instituição financeira (somente `legal_person`) | | `fund_class` | Classe de fundo de investimento (somente `legal_person`) — dispara o enriquecimento automático com os dados públicos da CVM e segue regras próprias de etapas, partes relacionadas e investor owners | O valor `non_resident` é recusado com `IVR000255`: a residência é declarada pelos campos `resident` e `non_resident_type`, não pelo subtipo. ### Response ```json title='Response Body' { "investor_key": "UUID", "investor_analysis_key": "UUID", "resident": true } ``` A resposta também traz o objeto `distributor` e, para investidor não residente, `non_resident_type`. :::info Investidor que já existe Se outro agente já cadastrou um investidor com o mesmo documento, nenhum investidor novo é criado: ele passa a ser vinculado a você e a resposta traz **apenas** a `investor_key`. ::: ## Erros | Status | Código | Quando acontece | | ------ | ------ | --------------- | | 400 | `IVR000004` | CPF/CNPJ com dígito verificador inválido, ou CPF enviado com `legal_person` (e vice-versa) | | 400 | `IVR000009` | Falta um campo obrigatório do `person_type` — por exemplo, `email` ou `phone` em pessoa física | | 400 | `IVR000222` | `resident: false` sem `non_resident_type` | | 400 | `IVR000064` | `investor_sub_type` `fund_class` ou `financial_institution` enviado com `natural_person` | | 400 | `IVR000255` | `investor_sub_type: non_resident`. Use `resident: false` e `non_resident_type` | | 400 | `IVR000256` / `IVR000257` | Subtipo declarado não confere com o CNPJ: `financial_institution` sem instituição registrada, ou `fund_class` sem classe na CVM | | 400 | `IVR000258` / `IVR000259` | Subtipo `default` declarado para um CNPJ que é instituição financeira registrada ou classe na CVM | | 403 | `IVR000260` | Gestora tentando cadastrar uma classe de fundo da qual não é gestora nem administradora | | 409 | `IVR000007` | Você já cadastrou um investidor com este documento | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # definir_grupo_assinantes_padrao URL: /documentation/iaas/investidor/cadastro/definir_grupo_assinantes_padrao :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_cadastro_para_analise URL: /documentation/iaas/investidor/cadastro/enviar_cadastro_para_analise :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_dados_cadastrais URL: /documentation/iaas/investidor/cadastro/enviar_dados_cadastrais :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_endereco URL: /documentation/iaas/investidor/cadastro/enviar_endereco :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_grupos_assinantes URL: /documentation/iaas/investidor/cadastro/enviar_grupos_assinantes :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_investor_document URL: /documentation/iaas/investidor/cadastro/enviar_investor_document :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_patrimonio URL: /documentation/iaas/investidor/cadastro/enviar_patrimonio :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # consultar_feedback URL: /documentation/iaas/investidor/cadastro/feedback/consultar_feedback :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). O consultor precisa estar vinculado ao investidor (vínculo não revogado). Sem o vínculo, a chamada é recusada com `QIT000011`. Só são retornados feedbacks com `origin_type` `investor_analysis`. ::: --- # enviar_mensagem_feedback URL: /documentation/iaas/investidor/cadastro/feedback/enviar_mensagem_feedback :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). O consultor precisa estar vinculado ao investidor (vínculo não revogado). Sem o vínculo, a chamada é recusada com `QIT000011`. ::: --- # listar_feedbacks URL: /documentation/iaas/investidor/cadastro/feedback/listar_feedbacks :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # Introdução URL: /documentation/iaas/investidor/cadastro/introducao Esta seção reúne os cadastros feitos por uma gestora (`manager-api`) ou consultoria (`consultant-api`) 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. ## O que cada perfil executa {#etapas-por-perfil} A gestora (`manager-api`) e a consultoria (`consultant-api`) não expõem as mesmas rotas. Antes de planejar a integração, confira o que o seu perfil executa: | Etapa | Gestora | Consultoria | |-------|:-------:|:-----------:| | 1. Criar Investidor | ✅ | ✅ | | 2. Enviar Dados Cadastrais | ✅ | ✅ | | 3. Enviar Endereço | ✅ | ✅ | | 4. Enviar Patrimônio | ✅ | ✅ | | 5. Enviar Contas Bancárias (e definir principal, alterar status) | — | ✅ | | 6. Enviar Suitability | ✅ | ✅ | | 7. Enviar Grupos de Assinantes (e definir padrão, alterar status) | — | ✅ | | 8. Enviar Documentos do Investidor | ✅ | ✅ | | 9. Criar Partes Relacionadas (e alterar status) | ✅ | ✅ | | 10. Enviar Documentos das Partes Relacionadas | ✅ | ✅ | | Enviar Documentos do Investor Owner | — | ✅ | | 11. Enviar para Análise | ✅ | ✅ | | Listar investidores | ✅ | ✅ | | Consultar investidor, análise cadastral, análise em andamento, lotes de documentos e detalhes de assinatura | — | ✅ | | Listar, consultar e responder feedbacks | — | ✅ | :::caution Gestora: o que muda - **Só classes de fundo próprias.** Pela gestora, as etapas de preenchimento (dados cadastrais, endereço, patrimônio, suitability, documentos, partes relacionadas) e o envio para análise só são aceitos para classes de fundo das quais ela é a gestora vinculada ao cadastro. Para os demais investidores, a chamada é recusada com `QIT000011`. - **Sem contas bancárias e grupos de assinantes.** O `manager-api` não tem rota funcional para essas etapas. Como o envio para análise exige ao menos uma conta bancária ativa (`IVR000178`), a gestora não conclui sozinha o **primeiro** cadastro de uma classe de fundo: fale com o time de integração antes de começar. Na atualização de uma classe já cadastrada, as contas da análise anterior são aproveitadas. Se o seu fluxo como gestora depende de algo fora disso, fale com o time de integração em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) antes de planejar o cadastro. ::: :::caution Fundos: quem pode cadastrar Pela gestora (`manager-api`), a criação de uma classe de fundo só é aceita se o CNPJ da gestora constar na CVM como gestora ou administradora da classe; caso contrário, a chamada é recusada com `IVR000260`. Além disso, a administradora e a gestora da classe (conforme a CVM) precisam estar cadastradas como investidoras na QI Tech; sem isso, o cadastro da classe não avança. Se for o seu caso, fale com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). ::: :::caution 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 sandbox, 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. Assinatura dos Documentos feita pelo investidor ou representante legal, após a aprovação. A consultoria acompanha os lotes de documentos pela API ## 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. Assinatura dos 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. ::: :::caution 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](/documentation/iaas/investidor/cadastro/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. --- # enviar_documento_investor_owner URL: /documentation/iaas/investidor/cadastro/investor_owner/enviar_documento_investor_owner :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------- | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). O consultor precisa estar vinculado ao investidor (vínculo não revogado). Sem o vínculo, a chamada é recusada com `QIT000011`. ::: --- # atualizar_status_parte_relacionada URL: /documentation/iaas/investidor/cadastro/related_party/atualizar_status_parte_relacionada :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # criar_parte_relacionada URL: /documentation/iaas/investidor/cadastro/related_party/criar_parte_relacionada :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_documento_parte_relacionada URL: /documentation/iaas/investidor/cadastro/related_party/enviar_documento_parte_relacionada :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # consultar_formulario_suitability URL: /documentation/iaas/investidor/cadastro/suitability/consultar_formulario_suitability :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Consultoria | `consultant-api` | — | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_suitability URL: /documentation/iaas/investidor/cadastro/suitability/enviar_suitability :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizacao_cadastral URL: /documentation/iaas/investidor/carteira_administrada/atualizacao_cadastral :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizar_status_grupo_assinantes URL: /documentation/iaas/investidor/carteira_administrada/atualizar_status_grupo_assinantes :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # busca_informacoes_de_uma_analise_cadastral_do_investidor URL: /documentation/iaas/investidor/carteira_administrada/busca_informacoes_de_uma_analise_cadastral_do_investidor :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # busca_informacoes_do_investidor URL: /documentation/iaas/investidor/carteira_administrada/busca_informacoes_do_investidor :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # buscar_documentos_para_assinatura URL: /documentation/iaas/investidor/carteira_administrada/buscar_documentos_para_assinatura :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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 :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizar_status_conta_bancaria URL: /documentation/iaas/investidor/carteira_administrada/contas_bancarias/atualizar_status_conta_bancaria :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # definir_conta_principal URL: /documentation/iaas/investidor/carteira_administrada/contas_bancarias/definir_conta_principal :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_contas_bancarias URL: /documentation/iaas/investidor/carteira_administrada/contas_bancarias/enviar_contas_bancarias :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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 Regra de aprovação em sandbox Em sandbox, o resultado da análise depende do primeiro dígito do CPF/CNPJ: início **1** → reprovação automática; início **8** → análise manual; os demais são aprovados 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). :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "969.698.790-03", "person_type": "natural_person", "email": "joao.silva@example.com", "phone": { "international_dial_code": "55", "area_code": "11", "number": "987654321" }, "investor_owner_type": "wallet_manager" } ``` Caso 02: Pessoa Jurídica ```json title='Request Body' { "name": "Empresa XPTO Ltda", "document_number": "22.333.444/0001-81", "person_type": "legal_person", "investor_sub_type": "default", "investor_owner_type": "wallet_manager" } ``` :::caution Campos obrigatórios Os campos obrigatórios mudam de acordo com o **`person_type`**. A ausência de qualquer um deles é recusada com `IVR000009`. - **`natural_person`**: `name`, `document_number`, `person_type` e, quando `investor_owner_type` não é enviado, **`email` e `phone`** - **`legal_person`**: `name`, `document_number`, `person_type` **`investor_owner_type` é obrigatório** para a gestora de carteira: sem ele, a chamada é recusada com `IVR000153`. Com ele, `email` e `phone` são dispensados em `natural_person`. `investor_sub_type` é opcional; `non_resident` é recusado com `IVR000255`. ::: ### 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. Obrigatório para `natural_person` sem `investor_owner_type` | 1 - 255 | Condicional | | `phone` | object | Objeto de **[Phone](#phone)**. Obrigatório para `natural_person` sem `investor_owner_type` | - | Condicional | | `investor_owner_type` | string | Tipo de relação com o investidor criado - Enumerador de **[Investor Owner Type](#investor-owner-type)** | 1 - 255 | Sim | ### 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" } ``` ## Erros | Status | Código | Quando acontece | | ------ | ------ | --------------- | | 400 | `IVR000004` | CPF/CNPJ com dígito verificador inválido, ou CPF enviado com `legal_person` (e vice-versa) | | 400 | `IVR000009` | Falta um campo obrigatório do `person_type` | | 400 | `IVR000153` | `investor_owner_type` não enviado | | 400 | `IVR000255` | `investor_sub_type: non_resident`. Use `resident: false` e `non_resident_type` | | 400 | `IVR000258` / `IVR000259` | Subtipo `default` declarado para um CNPJ que é instituição financeira registrada ou classe na CVM | | 409 | `IVR000007` | Você já cadastrou um investidor com este documento | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # definir_grupo_assinantes_padrao URL: /documentation/iaas/investidor/carteira_administrada/definir_grupo_assinantes_padrao :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_cadastro_para_analise URL: /documentation/iaas/investidor/carteira_administrada/enviar_cadastro_para_analise :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_dados_cadastrais URL: /documentation/iaas/investidor/carteira_administrada/enviar_dados_cadastrais :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_endereco URL: /documentation/iaas/investidor/carteira_administrada/enviar_endereco :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_grupos_assinantes URL: /documentation/iaas/investidor/carteira_administrada/enviar_grupos_assinantes :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_investor_document URL: /documentation/iaas/investidor/carteira_administrada/enviar_investor_document :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_patrimonio URL: /documentation/iaas/investidor/carteira_administrada/enviar_patrimonio :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # consultar_feedback URL: /documentation/iaas/investidor/carteira_administrada/feedback/consultar_feedback :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_mensagem_feedback URL: /documentation/iaas/investidor/carteira_administrada/feedback/enviar_mensagem_feedback :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # listar_feedbacks URL: /documentation/iaas/investidor/carteira_administrada/feedback/listar_feedbacks :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # buscar_fundo_por_cnpj URL: /documentation/iaas/investidor/carteira_administrada/fundos/buscar_fundo_por_cnpj :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # remover_fundo URL: /documentation/iaas/investidor/carteira_administrada/fundos/remover_fundo :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # selecionar_fundo URL: /documentation/iaas/investidor/carteira_administrada/fundos/selecionar_fundo :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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-api`, 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. Selecionar Fundo(s) opcional — adere a séries de emissão ainda durante o cadastro ↓ 8. Enviar Grupos de Assinantes definição de quem deve assinar os documentos ↓ 9. Enviar Documentos do Investidor upload de documentos obrigatórios ↓ 10. Criar Partes Relacionadas sócios, diretores, beneficiários finais ↓ 11. Enviar Documentos das Partes Relacionadas documentos de cada parte relacionada ↓ 12. Enviar Contrato de Carteira Administrada documento que atesta representação legal ↓ 13. Enviar para Análise submissão da análise cadastral para validação ↓ 14. Assinar Documentos assinatura dos documentos gerados após aprovação — inclui os termos de adesão a fundo, quando houver 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 :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizar_parte_relacionada URL: /documentation/iaas/investidor/carteira_administrada/related_party/atualizar_parte_relacionada :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizar_status_parte_relacionada URL: /documentation/iaas/investidor/carteira_administrada/related_party/atualizar_status_parte_relacionada :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # criar_parte_relacionada URL: /documentation/iaas/investidor/carteira_administrada/related_party/criar_parte_relacionada :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_documento_parte_relacionada URL: /documentation/iaas/investidor/carteira_administrada/related_party/enviar_documento_parte_relacionada :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # consultar_formulario_suitability URL: /documentation/iaas/investidor/carteira_administrada/suitability/consultar_formulario_suitability :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_suitability URL: /documentation/iaas/investidor/carteira_administrada/suitability/enviar_suitability :::info Disponível em | Perfil | Host | | ---------- | -------------- | | Investidor | `investor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # assinar_documento URL: /documentation/iaas/investidor/distribuicao_externa/assinar_documento :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizacao_cadastral URL: /documentation/iaas/investidor/distribuicao_externa/atualizacao_cadastral :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizar_status_grupo_assinantes URL: /documentation/iaas/investidor/distribuicao_externa/atualizar_status_grupo_assinantes :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # busca_informacoes_de_uma_analise_cadastral_do_investidor URL: /documentation/iaas/investidor/distribuicao_externa/busca_informacoes_de_uma_analise_cadastral_do_investidor :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # busca_informacoes_do_investidor URL: /documentation/iaas/investidor/distribuicao_externa/busca_informacoes_do_investidor :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # buscar_documentos_para_assinatura URL: /documentation/iaas/investidor/distribuicao_externa/buscar_documentos_para_assinatura :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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 :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # consultar_detalhes_assinatura URL: /documentation/iaas/investidor/distribuicao_externa/consultar_detalhes_assinatura :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizar_status_conta_bancaria URL: /documentation/iaas/investidor/distribuicao_externa/contas_bancarias/atualizar_status_conta_bancaria :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # definir_conta_principal URL: /documentation/iaas/investidor/distribuicao_externa/contas_bancarias/definir_conta_principal :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_contas_bancarias URL: /documentation/iaas/investidor/distribuicao_externa/contas_bancarias/enviar_contas_bancarias :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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. :::caution 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 Regra de aprovação em sandbox Em sandbox, o resultado da análise depende do primeiro dígito do CPF/CNPJ: início **1** → reprovação automática; início **8** → análise manual; os demais são aprovados 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). :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "969.698.790-03", "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": "22.333.444/0001-81", "person_type": "legal_person", "investor_sub_type": "default", "registry_user": { "name": "José da Silva", "document_number": "969.698.790-03", "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": "22.333.444/0001-81", "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" } ``` :::caution 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` - **`legal_person`**: `name`, `document_number`, `person_type` - **`nominee`**: `name`, `person_type`, `external_distribution_key` **`investor_sub_type` é opcional.** Se omitido, pessoa física fica `default` e, para pessoa jurídica residente, o subtipo é identificado pelo CNPJ (`financial_institution`, `fund_class` ou `default`). `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. ::: :::caution `investor_owner_type` não é aceito de distribuidores O campo `investor_owner_type` é **recusado** com `IVR000010` 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": "969.698.790-03", "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": "22.333.444/0001-81" } ] } ``` | 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 | :::caution 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`. ::: :::caution 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)**. Se omitido, é inferido (veja acima) | - | Não | | `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)** | - | Não | ### 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` | O valor `non_resident` é recusado com `IVR000255`: a residência é declarada pelos campos `resident` e `non_resident_type`, não pelo subtipo. ### Response ```json title='Response Body' { "investor_key": "UUID", "investor_analysis_key": "UUID" } ``` ## Erros | Status | Código | Quando acontece | | ------ | ------ | --------------- | | 400 | `IVR000004` | CPF/CNPJ com dígito verificador inválido, ou CPF enviado com `legal_person` (e vice-versa) | | 400 | `IVR000009` | Falta um campo obrigatório do `person_type` | | 400 | `IVR000010` | `investor_owner_type` enviado com `natural_person` ou `legal_person` | | 400 | `IVR000222` | `resident: false` sem `non_resident_type` | | 400 | `IVR000255` | `investor_sub_type: non_resident` | | 409 | `IVR000007` | Você já cadastrou um investidor com este documento | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # definir_grupo_assinantes_padrao URL: /documentation/iaas/investidor/distribuicao_externa/definir_grupo_assinantes_padrao :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_cadastro_para_analise URL: /documentation/iaas/investidor/distribuicao_externa/enviar_cadastro_para_analise :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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*** é retornado o objeto `data` da análise, com os blocos cadastrais já gravados (`natural_person` ou `legal_person`, `address`, `net_worth`, `suitability`, `email`, `phone`) e `resident`. As chaves do investidor e da análise não vêm na resposta: use as que você já tem. :::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. ::: :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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": "969.698.790-03" }, "profession": "Engenheiro", "occupation": "Engenheiro de Software", "occupation_company": { "name": "Empresa XYZ Ltda", "document_number": "22.333.444/0001-81" } } } ``` 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": "33334444" }, "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": "33334444" }, "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* | | `nif_number` | string | NIF (identificação fiscal estrangeira). Obrigatório para investidor não residente (`IVR000224`) | 1 - 50 | Condicional | | `non_resident_type` | string | Só pode repetir o valor enviado na criação do investidor (`IVR000225`) | - | Não | \* É 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 | | `father_name` | string | Nome completo do pai | 1 - 255 | Não | | `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 | Sim | | `uf` | string | Estado (UF) | - | Sim | | `city` | string | Cidade | - | Sim | ### 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 O corpo traz o objeto `data` da análise com os blocos já gravados. Para status e demais campos, consulte **Busca informações de uma análise cadastral do investidor**. --- ## Erros Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # enviar_documento_assinado URL: /documentation/iaas/investidor/distribuicao_externa/enviar_documento_assinado :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_endereco URL: /documentation/iaas/investidor/distribuicao_externa/enviar_endereco :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_grupos_assinantes URL: /documentation/iaas/investidor/distribuicao_externa/enviar_grupos_assinantes :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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). :::caution 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. :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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` | :::caution 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`. :::caution 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: ```text 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** | ## Erros Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # enviar_patrimonio URL: /documentation/iaas/investidor/distribuicao_externa/enviar_patrimonio :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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`. ::: :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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`. ::: O envio pode ser repetido enquanto a análise estiver em `pending_registry_data` — o último perfil enviado substitui o anterior. ## Erros | Status | Código | Quando acontece | | ------ | ------ | --------------- | | 400 | `IVR000018` | A análise não está em `pending_registry_data` (já foi enviada ou encerrada) | | 400 | `QIT000001` | `profile` ausente, fora do enumerador, ou corpo com propriedade extra | | 404 | `IVR000008` | Investidor não encontrado para as credenciais utilizadas | | 400 | `IVR000271` | Investidor não residente sem `profile: not_applicable` | | 400 | `IVR000133` | *(no `submit`)* pessoa jurídica `retail` sem suitability | | 400 | `IVR000150` | *(no `submit`)* pessoa física sem suitability | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # consultar_feedback URL: /documentation/iaas/investidor/distribuicao_externa/feedback/consultar_feedback :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_mensagem_feedback URL: /documentation/iaas/investidor/distribuicao_externa/feedback/enviar_mensagem_feedback :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # listar_feedbacks URL: /documentation/iaas/investidor/distribuicao_externa/feedback/listar_feedbacks :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # buscar_fundo_por_cnpj URL: /documentation/iaas/investidor/distribuicao_externa/fundos/buscar_fundo_por_cnpj :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # remover_fundo URL: /documentation/iaas/investidor/distribuicao_externa/fundos/remover_fundo :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # selecionar_fundo URL: /documentation/iaas/investidor/distribuicao_externa/fundos/selecionar_fundo :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # 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-api`). 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. :::caution 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. Selecionar Fundo(s) opcional — adere a séries de emissão ainda durante o cadastro ↓ 8. Enviar Grupos de Assinantes definição de quem deve assinar os documentos ↓ 9. Enviar Documentos do Investidor upload de documentos obrigatórios ↓ 10. Criar Partes Relacionadas sócios, diretores, beneficiários finais ↓ 11. Enviar Documentos das Partes Relacionadas documentos de cada parte relacionada ↓ 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 — inclui os termos de adesão a fundo, quando houver ### 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. --- # enviar_documento_investor_owner URL: /documentation/iaas/investidor/distribuicao_externa/investor_owner/enviar_documento_investor_owner :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizar_parte_relacionada URL: /documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_parte_relacionada :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # atualizar_status_parte_relacionada URL: /documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_status_parte_relacionada :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # criar_parte_relacionada URL: /documentation/iaas/investidor/distribuicao_externa/related_party/criar_parte_relacionada :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # enviar_documento_parte_relacionada URL: /documentation/iaas/investidor/distribuicao_externa/related_party/enviar_documento_parte_relacionada :::info Disponível em | Perfil | Host | | ------------ | ----------------- | | Distribuidor | `distributor-api` | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: --- # Recuperando Informações da Posição do Investidor URL: /documentation/iaas/investidor/informacoes_posicao_investidor Retorna, de forma paginada, a posição do investidor em cada série de emissão em que ele tem cotas. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /quota/investor/INVESTOR_KEY/investor_positions MÉTODO GET ### Query Params | Parâmetro | Tipo | Descrição | |------------------------------|---------|--------------------------------------------------------------------------------------| | `issuance_serie_key` | string | Filtra pela série de emissão | | `fund_class_document_number` | string | Filtra pelo CNPJ da classe de fundo | | `only_active_funds` | boolean | `true` retorna só as séries em que o investidor tem cotas (quantidade maior que zero). Default: `false` | | `number_of_quotas_str` | boolean | `true` devolve as quantidades de cotas como string, sem perda de precisão. Default: `false` | | `page` | integer | Página, a partir de `0`. Default: `0` | | `limit` | integer | Itens por página. Default: `20`; máximo: `100` | Percorra as páginas incrementando `page` enquanto `is_last_page` for `false`. ### 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": "33.444.555/0001-81", "name": "SAMPLE DISTRIBUTOR NAME", "account_data": { "owner": { "name": "SAMPLE DISTRIBUTOR NAME", "document_number": "33.444.555/0001-81" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" } }, "investor_key": "UUID", "document_number": "969.698.790-03", "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" }, "number_of_quotas": 1000.0, "quota_value": 1.05, "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", "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": "44.555.666/0001-81" } } } } ], "limit": 20, "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": "33.444.555/0001-81", "name": "SAMPLE DISTRIBUTOR NAME", "account_data": { "owner": { "name": "SAMPLE DISTRIBUTOR NAME", "document_number": "33.444.555/0001-81" }, "account_digit": "0", "account_branch": "0000", "account_number": "00000", "financial_institution_code": "000", "financial_institution_ispb": "00000000" } }, "investor_key": "UUID", "document_number": "969.698.790-03", "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" }, "number_of_quotas": 1000.0, "quota_value": 1.05, "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", "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": "44.555.666/0001-81" } } } } ], "limit": 20, "page": 0, "is_last_page": true } ``` Caso 03: Investidor com Posição em duas séries, uma COTA SÊNIOR e uma COTA SUBORDINADA ```json { "data":[ { "investor_position_key":"UUID", "investor":{ "distributor":{ "distributor_key":"UUID", "document_number":"33.444.555/0001-81", "name":"SAMPLE DISTRIBUTOR NAME", "account_data":{ "owner":{ "name":"SAMPLE DISTRIBUTOR NAME", "document_number":"33.444.555/0001-81" }, "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" } }, "investor_key":"UUID", "document_number":"969.698.790-03", "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" }, "number_of_quotas": 1000.0, "quota_value": 1.05, "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", "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":"44.555.666/0001-81" } } } }, { "investor_position_key":"UUID", "investor":{ "distributor":{ "distributor_key":"UUID", "document_number":"33.444.555/0001-81", "name":"SAMPLE DISTRIBUTOR NAME", "account_data":{ "owner":{ "name":"SAMPLE DISTRIBUTOR NAME", "document_number":"33.444.555/0001-81" }, "account_digit":"0", "account_branch":"0000", "account_number":"00000", "financial_institution_code":"000", "financial_institution_ispb":"00000000" } }, "investor_key":"UUID", "document_number":"969.698.790-03", "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" }, "number_of_quotas": 1000.0, "quota_value": 1.05, "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", "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":"44.555.666/0001-81" } } } } ], "limit": 20, "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)** | | `number_of_quotas` | float | Número de cotas do investidor na série | | `number_of_quotas_str` | string | O mesmo valor, como string. Só vem com `number_of_quotas_str=true` | | `quota_value` | float | Valor da cota no fechamento mais recente da série. Ausente se a série ainda não tem fechamento | | `issuance_serie` | JSON | Objeto de **[Issuance Serie](#issuance_serie)** | | `investor_position_key` | string | 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 | | `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 | - | ## Erros | Status | Código | Quando acontece | | ------ | ------ | --------------- | | 400 | — | `limit` acima de 100 ou `page` negativo | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Layout CNAB 444 — Baixa URL: /documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa Layout do arquivo de **remessa de baixa** (liquidação) aceito pela QI DTVM. 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`, `06`, `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 (`asset_settlement` / `installment_settlement`) | Sacado | | `14` | **Pagamento parcial** | Amortização (`asset_amortization` / `installment_amortization`) | Sacado | | `75` | **Baixa por depósito do cedente** | Liquidação integral (`asset_settlement` / `installment_settlement`) | Cedente | | `04` | **Abatimento** | Amortização pelo valor do abatimento (posições 206–218, maior que zero) | Cedente | | `06` | **Alteração de vencimento** | Prorrogação (`asset_extension`). Só duplicatas e demais direitos creditórios | Sacado | :::caution Só essas cinco Qualquer outro código de ocorrência recusa o arquivo com a mensagem *"This field only allows one of this values: ['04', '06', '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º de controle do participante** (038–062), o mesmo da cessão | 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º de controle do participante e pela data de vencimento | ## Checklist antes de enviar - [ ] Todas as linhas com exatamente 444 caracteres - [ ] Ocorrência `04`, `06`, `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-liquidacao) | | `installment_number` | obrigatória (coluna) | Número da parcela. Preencha para ativos com parcelas (CCB); deixe vazio para duplicatas; em contratos, use `installment_number` ou `installment_external_id` | | `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` | | `new_maturity_date` | condicional | Nova data de vencimento, no formato `YYYY-MM-DD`. Obrigatória em `asset_extension` e recusada nos demais tipos | | `installment_external_id` | opcional | Para contratos, alternativa a `installment_number` | :::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 | | `asset_extension` | Prorrogação do vencimento (só direitos creditórios; exige a coluna `external_id` e `new_maturity_date`) | ### Tipos de ativo aceitos `ccb` · `cce` · `structured_ccb` · `structured_cce` · `structured_nce` · `structured_cci` · `duplicata_mercantil` · `duplicata_servicos` · `discounted_contract` · `cte` · `commercial_paper` · `check` · `promissory_note` · `debt_acknowledgment` · `financing_contract` · `contract` **[📄 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 Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::info Liquidação, recompra e repasse Liquidação e recompra usam este mesmo endpoint. O campo `collection_origin_type` indica quem pagou: - `borrower` — **liquidação** paga pelo sacado/devedor. - `assignor` — **recompra** paga pelo cedente. - `collection_agent` — pagamento repassado por um agente de cobrança. Exige `counter_party_document_number`. - `bankslip` — pagamento recebido por boleto. ::: :::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). O lote precisa estar em `pending_settlements_insertion`. ::: ## 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 no máximo duas casas decimais. Só pode ser `0` em `installment_settlement`, `asset_settlement`, `asset_refund` e `asset_extension`. | | `external_id` | string | obrigatório | Chave única desta liquidação dentro do lote, 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 | opcional | Quem pagou. Veja [enumeradores de `collection_origin_type`](#enumeradores-de-collection_origin_type). Quando omitido, vale o padrão da configuração de liquidação do fundo, se houver. | | `counter_party_document_number` | string | condicional | CPF ou CNPJ de quem pagou, com pontuação (14 a 18 caracteres). **Obrigatório** quando `collection_origin_type` é `collection_agent` e a configuração de liquidação do fundo não define um documento padrão. Com `borrower`, `bankslip` ou `assignor`, quando omitido, é preenchido com o documento do sacado ou do cedente do ativo. | | `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, 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 | condicional | Número da parcela. Veja [identificação da parcela](#identificacao-do-ativo-e-da-parcela). | | `installment_maturity_date` | string | condicional | Data de vencimento da parcela no formato `YYYY-MM-DD`. | | `installment_external_id` | string | condicional | Identificador externo da parcela. Máximo de 50 caracteres. | | `collection_date` | string | opcional | Data de pagamento no formato `YYYY-MM-DD`. Campo destinado ao controle do integrador. | | `remaining_face_value` | number | opcional | Saldo de valor de face que resta na parcela após o pagamento. Aceito somente em `installment_amortization` e quando a liquidação atinge um único ativo. | | `asset_reduction_value` | number | opcional | Valor a abater do ativo, quando diferente do valor pago. Aceito somente em `installment_amortization` e `installment_partial_refund`. Não pode ser maior que `total_value`. | | `new_maturity_date` | string | condicional | Nova data de vencimento, no formato `YYYY-MM-DD`. **Obrigatório** em `asset_extension` e recusado nos demais tipos. | | `reversed_settlement_external_id` | string | condicional | `external_id` da liquidação que está sendo estornada. **Obrigatório** em `installment_payment_reversal` e recusado nos demais tipos. | :::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**. ::: ### Identificação do ativo e da parcela - Informe **exatamente um** identificador do ativo: `contract_number`, `asset_external_id`, `asset_key`, `if_code` ou `participant_control_number`. Nenhum ou mais de um devolve erro. Duplicatas e demais direitos creditórios não aceitam `contract_number` nem `if_code`; CCBs e demais operações de crédito não aceitam `participant_control_number`. - Nos tipos de liquidação por parcela (`installment_*` e `gloss`), informe **exatamente um** identificador da parcela: `installment_number`, `installment_maturity_date` ou `installment_external_id`. Em CCBs e contratos, `installment_external_id` sozinho também identifica o ativo. #### 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 descontado | | `cte` | Conhecimento de Transporte Eletrônico | | `check` | Cheque | | `promissory_note` | Nota promissória | | `legal_fees` | Honorários | | `debt_acknowledgment` | Confissão de dívida | | `financing_contract` | Contrato de financiamento | | `contract` | Contrato | #### Enumeradores de `settlement_type` | Valor | Descrição | |---|---| | `asset_settlement` | Liquidação total do ativo. | | `asset_amortization` | Amortização do ativo. | | `fine_payment` | Pagamento de juros ou mora do ativo. | | `asset_refund` | Devolução integral do ativo. | | `asset_partial_refund` | Devolução parcial do ativo. | | `asset_gloss` | Glosa do ativo. | | `asset_extension` | Prorrogação do vencimento de duplicatas e demais direitos creditórios. Exige `new_maturity_date` e um único ativo. | | `installment_settlement` | Liquidação de parcela. | | `installment_amortization` | Amortização de parcela. | | `installment_fine_payment` | Pagamento de juros ou mora de parcela. | | `installment_refund` | Devolução integral de parcela. | | `installment_partial_refund` | Devolução parcial de parcela. | | `installment_payment_reversal` | Estorno do pagamento de uma parcela de CCB ou operação de crédito. Exige `reversed_settlement_external_id` e `installment_number`; `total_value` deve ser igual ao da liquidação estornada. | | `gloss` | Glosa de parcela. | | `rco_revenue` | Receita de RCO. | Contratos (`debt_acknowledgment`, `financing_contract`, `contract`) aceitam somente `asset_settlement`, `asset_amortization`, `installment_settlement` e `installment_amortization`. #### Enumeradores de `collection_origin_type` | Valor | Descrição | |---|---| | `borrower` | Liquidação — pagamento realizado pelo sacado/devedor. | | `assignor` | Recompra — pagamento realizado pelo cedente. | | `collection_agent` | Repasse de um agente de cobrança. Exige `counter_party_document_number` (ou documento padrão na configuração do fundo). | | `bankslip` | Pagamento recebido por boleto. | ## Response STATUS 201 A resposta ecoa os campos enviados no corpo e acrescenta os dados calculados pela QI Tech. ```json title="Response 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", "asset_external_id": "CCB-0001", "assignor_document_number": "33.444.555/0001-81", "borrower_document_number": "969.698.790-03", "status": "validated", "type": "installment_settlement", "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890", "total_number_of_units": 1, "settlement_result": 0.0, "next_execution_datetime": "2025-01-01 13:00:00.000000", "counter_party_document_number": "969.698.790-03", "assets": [ { "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361", "number_of_units": 1, "present_value": 1250.00, "installment_face_value": 130.50 } ] } ``` ### Atributos da resposta Além dos campos enviados no corpo: | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Status da liquidação após a inserção: `validated` ou `pending_validation`. Veja abaixo. | | `type` | string | Tipo de liquidação (mesmo valor de `settlement_type`). | | `settlement_key` | string | Identificador único da liquidação gerado pela QI Tech (UUID). | | `total_value` | number | Valor total do pagamento. Negativo em `gloss`, `asset_gloss` e `installment_payment_reversal`. | | `total_number_of_units` | integer | Quantidade total de unidades de ativo afetadas pela liquidação. | | `installment_number` | integer | Número da parcela localizada. Presente quando aplicável. | | `settlement_result` | number | Diferença entre o valor pago e o valor esperado do ativo ou parcela. Presente quando calculado. | | `contract_number`, `asset_external_id` | string | Identificadores do ativo localizado na carteira (CCBs e contratos). | | `assignor_document_number`, `borrower_document_number` | string | Documento do cedente e do sacado do ativo. | | `counter_party_document_number` | string | Documento de quem pagou. Presente quando informado ou preenchido automaticamente. | | `collection_origin_type` | string | Origem do pagamento. Presente quando informada ou definida pela configuração do fundo. | | `next_execution_datetime` | string | Controle do processamento da QI Tech. Pode ser ignorado. | | `denial_reason` | string | Motivo do descarte. Presente apenas em liquidações descartadas. | | `assets` | array | Ativos afetados pela liquidação. Veja [Atributos de `assets`](#atributos-de-assets). | **Status na resposta:** - `validated` — o valor pago está dentro da tolerância em relação ao valor esperado do ativo ou da parcela. A liquidação será processada quando o lote for pago. - `pending_validation` — o valor pago diverge do esperado além da tolerância e a liquidação aguarda revisão da QI Tech. Ao final da revisão ela passa para `validated` ou `discarded`, e você recebe o [webhook de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook) correspondente. Dependendo da configuração de liquidação do fundo, a divergência pode, em vez disso, recusar a inserção com `SET000066`. #### 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. | | `total_purchase_value` | number | Valor de aquisição do ativo. Presente quando aplicável. | | `maturity_date` | string | Vencimento do ativo. Presente quando aplicável. | | `contract_number` | string | Número do contrato do ativo. Presente quando aplicável. | | `external_id` | string | Identificador externo do ativo. Presente quando aplicável. | ## Reenvio e duplicidade Em caso de erro, reenvie a requisição. Duplicidade (`SET000013`) significa que a liquidação já existe neste lote: consulte-a pela [consulta de liquidação](/documentation/iaas/liquidacao_ativos/ativos/recuperacao) em vez de recriar. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ## 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. Não há endpoint para remover uma liquidação individual. Se uma liquidação foi inserida por engano, descarte o lote no [encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) (`batch_status: discarded`) e crie um novo lote com as liquidações corretas. ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000010` | O lote informado na URL não existe neste fundo. | | 403 | `SET000028` | O fundo não pertence ao seu perfil. | | 400 | `SET000026` | O lote não está em `pending_settlements_insertion` (já foi encerrado ou descartado). | | 400 | `SET000013` | Já existe liquidação com este `external_id` no lote. Consulte-a em vez de recriar. | | 409 | `SET000053` | Duas requisições simultâneas com o mesmo `external_id`; uma delas foi gravada. | | 400 | `SET000012` | `asset_type` inválido. | | 400 | `SET000025` | `settlement_type` inválido. | | 400 | `SET000014` | `total_value` com mais de duas casas decimais, ou zero num tipo que não aceita zero. | | 400 | `SET000019` | Nenhum identificador do ativo foi informado. | | 400 | `SET000020` | Mais de um identificador do ativo, ou mais de um identificador da parcela. | | 400 | `SET000029` | Tipo de liquidação por parcela sem identificação da parcela. | | 400 | `SET000040` / `SET000041` | Tipo de liquidação ou identificador não aceito para este `asset_type`. | | 400 | `SET000022` / `SET000023` / `SET000047` | O ativo não está ativo ou não aceita este tipo de liquidação no status atual. | | 400 | `SET000086` / `SET000087` / `SET000088` | `remaining_face_value` fora de `installment_amortization`, com mais de duas casas, ou com a liquidação atingindo mais de um ativo. | | 400 | `SET000092` / `SET000093` / `SET000094` | `asset_extension` sem `new_maturity_date`, `new_maturity_date` em outro tipo, ou prorrogação atingindo mais de um ativo. | | 400 | `SET000112` / `SET000113` / `SET000114` | `asset_reduction_value` fora de `installment_amortization`/`installment_partial_refund`, com mais de duas casas, ou maior que `total_value`. | | 400 | `SET000104` / `SET000105` | `installment_payment_reversal` sem `reversed_settlement_external_id`/`installment_number`, ou `reversed_settlement_external_id` em outro tipo. | | 400 / 404 / 409 | `SET000106` a `SET000111`, `SET000115` | A liquidação estornada não existe, não está `settled`, é de outro tipo, parcela ou ativo, já foi estornada, ou o valor difere. | | 404 | `SET000015` | Nenhum ativo encontrado na carteira do fundo com o identificador informado. | | 400 | `SET000035` / `SET000042` / `SET000052` / `SET000060` | A parcela informada não existe ou não tem saldo no ativo. | | 400 | `SET000046` | Já existe, no mesmo lote, outra liquidação do mesmo grupo para o mesmo ativo/parcela. | | 400 | `SET000080` | Liquidação total de um ativo que já está liquidado (valor presente zero). | | 400 | `SET000066` | Valor pago fora da tolerância e o fundo está configurado para recusar automaticamente. | | 400 | `SET000067` | `collection_origin_type` inválido. | | 400 | `SET000078` | `collection_origin_type` é `collection_agent` sem `counter_party_document_number`. | | 400 | `SET000001` | `counter_party_document_number` não é um CPF/CNPJ válido. | | 400 | `QIT000001` | Corpo inválido (campo obrigatório ausente, tipo errado ou campo não aceito). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta de Liquidação URL: /documentation/iaas/liquidacao_ativos/ativos/recuperacao Retorna uma liquidação de um lote de pagamento pelo `external_id` informado na inserção. Use para conferir o status da liquidação ou quando a inserção devolve duplicidade (`SET000013`). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Visualizar Lotes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave do fundo (UUID). | | `external_id` | string | O `external_id` do lote de pagamento. | | `settlement_external_id` | string | O `external_id` da liquidação, informado no corpo da [inserção](/documentation/iaas/liquidacao_ativos/ativos). | ## Response STATUS 200 O objeto é o mesmo devolvido na [inserção da liquidação](/documentation/iaas/liquidacao_ativos/ativos#atributos-da-resposta): os campos enviados no corpo da inserção mais os dados calculados pela QI Tech, com o `status` atual. ```json title="Response 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", "asset_external_id": "CCB-0001", "assignor_document_number": "33.444.555/0001-81", "borrower_document_number": "969.698.790-03", "status": "settled", "type": "installment_settlement", "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890", "total_number_of_units": 1, "settlement_result": 0.0, "next_execution_datetime": "2025-01-01 13:00:00.000000", "counter_party_document_number": "969.698.790-03", "assets": [ { "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361", "number_of_units": 1, "present_value": 1250.00, "installment_face_value": 130.50 } ] } ``` ### Status da liquidação | Status | Significado | |---|---| | `validated` | Inserida e aprovada; aguarda o pagamento do lote. | | `pending_validation` | Valor pago fora da tolerância; aguarda revisão da QI Tech. | | `waiting_send_to_queue` / `on_queue` | Lote pago; liquidação em processamento na carteira do fundo. | | `settled` | Concluída e conciliada na carteira. Status final. | | `discarded` | Descartada, sem movimentação financeira. Status final. O campo `denial_reason` traz o motivo, quando houver. | | `inconsistent_asset` | A carteira recusou o pagamento por inconsistência no ativo. A QI Tech trata o caso; o lote não chega a `completed` enquanto houver liquidação neste status. | O mapa completo, com os status que geram webhook, está em [Webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook). ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000011` | Não existe liquidação com este `settlement_external_id` no lote informado (ou o lote não existe neste fundo). | | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil (gestora do fundo, consultoria vinculada ou cedente associado). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. A gestora e a consultoria do fundo recebem os webhooks de todas as liquidações; o cedente recebe apenas os das liquidações de ativos cedidos por ele. ::: ## Fluxo de status da liquidação Nem toda mudança de status gera webhook. Só três situações notificam: a conclusão (`settled`) e o resultado de uma revisão da QI Tech (`validated` ou `discarded`). Para os demais status, use a [consulta de liquidação](/documentation/iaas/liquidacao_ativos/ativos/recuperacao). ![Fluxo de status da liquidação, destacando os status que geram webhook](/img/diagrams/iaas-liquidacao-ativos-ativos-webhook.svg) _Como ler o diagrama: **contorno tracejado** = status sem webhook · **azul** = webhook de andamento · **verde** = conclusão com sucesso · **vermelho** = descarte notificado._ | Status | Quando acontece | Webhook? | |---|---|---| | `validated` | Na [inserção](/documentation/iaas/liquidacao_ativos/ativos), quando o valor pago está dentro da tolerância. | Não — é a resposta da própria inserção. | | `pending_validation` | Na inserção, quando o valor pago diverge do esperado além da tolerância. A liquidação aguarda revisão da QI Tech. | Não — é a resposta da própria inserção. | | `validated` (após revisão) | A QI Tech aprova uma liquidação que estava em `pending_validation`. | **Sim** | | `discarded` (após revisão) | A QI Tech descarta uma liquidação que estava em `pending_validation` ou `validated`, com o lote ainda aberto. | **Sim** | | `waiting_send_to_queue` / `on_queue` | O lote foi pago e a liquidação está sendo enviada à carteira do fundo. | Não | | `settled` | A liquidação foi conciliada na carteira. Status final de sucesso. | **Sim** | | `inconsistent_asset` | A carteira recusou o pagamento por inconsistência no ativo. A QI Tech trata o caso e reprocessa; o lote não chega a `completed` enquanto houver liquidação neste status. | Não | | `discarded` (sem aviso) | O lote foi descartado (as liquidações abertas são descartadas junto), ou a carteira recusou em definitivo uma liquidação de valor zero. | Não — no descarte do lote, o aviso é o [webhook do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) com `discarded`. | ## 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). Se a liquidação atingir mais de um ativo, traz o primeiro. | **Identificação do ativo:** | Campo | Tipo | Descrição | |---|---|---| | `contract_number` | string | Número do contrato. Presente se informado na criação; em CCBs e contratos, é preenchido a partir da carteira mesmo quando não informado. | | `asset_external_id` | string | `external_id` do ativo no sistema do parceiro. Presente se informado na criação; em CCBs e contratos, é preenchido a partir da carteira mesmo quando não informado. | **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). | | `new_maturity_date` | string | Nova data de vencimento. Presente em `asset_extension`. | **Campos de parcela — presentes apenas para tipos de liquidação por parcela (`installment_*` e `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": "11.222.333/0001-81", "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": "11.222.333/0001-81", "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 Aprovada após Revisão STATUS validated Enviado quando a QI Tech aprova uma liquidação que estava em `pending_validation`. A liquidação segue para o processamento normal quando o lote for pago. O payload tem a mesma estrutura, com `settlement_status` igual a `validated`. --- ### Liquidação Descartada STATUS discarded Enviado quando a QI Tech descarta uma liquidação após revisão — por exemplo, uma liquidação em `pending_validation` cujo valor não se confirma. Liquidações descartadas não geram movimentação financeira. Descartes que acontecem junto com o descarte do lote, ou por rejeição definitiva da carteira para liquidações de valor zero, **não** geram este webhook. Veja o [mapa de status](#fluxo-de-status-da-liquidacao). ```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": "11.222.333/0001-81", "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 / pending_validation POST /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement Cada liquidação recebe validated ou, se o valor pago divergir do esperado além da tolerância, pending_validation (revisão pela QI Tech; o resultado chega por webhook). Não há como remover uma liquidação individual: se necessário, descarte o lote e crie outro. Ver documentação completa → 3 Encerramento do lote Agente Integrador Sinaliza que todas as liquidações foram inseridas e que o processamento pode iniciar — ou descarta o lote inteiro. Lote: pending_payment / pending_validation / pending_discard Liquidação: validated Processar lote pending_payment É necessário ter ao menos uma liquidação no lote. Se houver liquidação em revisão, o lote fica em pending_validation e segue sozinho para pending_payment ao fim da revisão. Descartar lote pending_discard → discarded Nenhuma liquidação será processada. O webhook do lote com discarded confirma o fim do fluxo. 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 → 4 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 consulta de lote para acompanhar o lote. GET /settlement/fund_class/{fund_class_key}/payment_batch/{external_id} Consulta opcional do status atual do lote. Webhooks do lote → 5 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. Se a carteira recusar o ativo, a liquidação fica em inconsistent_asset (sem webhook) até a QI Tech tratá-la. 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 4) | 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 5) | Liquidação concluída e conciliada na carteira. | | 3 | `settlement.settlement_status_change` | `settlement_status` | `validated` | Por liquidação, quando a QI Tech aprova uma liquidação que estava em `pending_validation` | Nenhuma: a liquidação segue o fluxo normal. | | 4 | `settlement.settlement_status_change` | `settlement_status` | `discarded` | Por liquidação, quando a QI Tech a descarta após revisão | Liquidação não será processada. Nenhuma movimentação financeira é gerada. | | 5 | `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. | | 6 | `settlement.payment_batch_status_change` | `status` | `discarded` | Quando o descarte do lote é concluído (por solicitação do parceiro ou descarte automático de lotes em aberto) | Nenhuma liquidação do lote será processada. As liquidações abertas são descartadas sem webhook próprio. | :::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:** `contract_number` e `asset_external_id` aparecem quando informados na criação; em CCBs e contratos, os dois são preenchidos a partir da carteira. - **Campos de parcela** (`installment_number`, `installment_maturity_date`, `installment_external_id`): presentes somente para tipos de liquidação por parcela (`installment_*` e `gloss`). 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 DTVM. 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 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: ```text /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)** Para conferir um lote já criado, use a [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao). ### 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)** Não há endpoint para remover uma liquidação individual. Se uma liquidação foi inserida por engano, descarte o lote no encerramento e crie um novo. Para conferir uma liquidação já inserida, use a [consulta de liquidação](/documentation/iaas/liquidacao_ativos/ativos/recuperacao). ### 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 Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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: ```text /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. Em caso de erro, reenvie a requisição. Duplicidade (`SET000009`) significa que o lote já existe: consulte-o pela [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao) em vez de recriar. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ::: ## 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 do lote no formato `YYYY-MM-DD`. Quando omitida, vale a data corrente (horário de Brasília). Não pode ser anterior à data contábil atual do fundo. | | `end_to_end_id` | string | opcional | Identificador end-to-end do Pix da contraparte financeira da liquidação (32 caracteres, começando com `E`). | | `source_document_number` | string | opcional | CPF ou CNPJ da contraparte financeira da liquidação, com pontuação (ex: `11.222.333/0001-81` ou `969.698.790-03`). Quando omitido, pode ser preenchido pelo documento padrão da configuração de liquidação do fundo. | | `settlement_expenses` | array | opcional | Despesas de liquidação descontadas no lote, no máximo uma por tipo. Veja [Atributos de `settlement_expenses`](#atributos-de-settlement_expenses). | :::caution Atenção Os campos `account` e `account_key` não devem ser passados simultaneamente (`SET000034`). Caso nenhum dos dois seja informado, a liquidação será gerada na conta principal do fundo. A conta deve pertencer ao fundo ou tê-lo como agente autorizado (`SET000032`). ::: #### 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. | #### Atributos de `settlement_expenses` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `amount` | number | obrigatório | Valor da despesa. | | `expense_type` | string | obrigatório | `bank_account` (despesa bancária) ou `collection_agent_fee` (taxa de agente de cobrança). | | `description` | string | opcional | Descrição da despesa. Máximo de 255 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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "11.222.333/0001-81", "accounting_date": "2025-01-01", "payment_batch_automatic_discard": false }, "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 do lote no formato `YYYY-MM-DD`. | | `account_key` | string | Chave da conta associada ao lote (UUID). | | `settlement_expenses` | array | Despesas de liquidação criadas, com `settlement_expense_key`, `amount`, `status`, `description` e `type`. Presente apenas quando informadas. | A resposta também ecoa os demais campos enviados no corpo (por exemplo `account`, `source_document_number`, `end_to_end_id`). #### 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. | | `accounting_date` | string | Data contábil atual do fundo, no formato `YYYY-MM-DD`. | | `payment_batch_automatic_discard` | boolean | Indica se o fundo descarta automaticamente lotes deixados em aberto. | #### 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. | ## 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. ## Erros | Status | Código | Quando acontece | |---|---|---| | 409 | `SET000009` | Já existe lote com este `external_id` no fundo. Consulte-o em vez de recriar. | | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil (gestora do fundo, consultoria vinculada ou cedente associado). | | 400 | `SET000044` | `reference_date` anterior à data contábil atual do fundo. | | 404 | `SET000031` | A conta informada (`account_key` ou `account`) não foi encontrada. | | 400 | `SET000032` | A conta informada não pertence ao fundo. | | 400 | `SET000034` | `account` e `account_key` enviados juntos. | | 403 | `SET000085` | Conta escrow não autorizada a operar para este fundo. | | 400 | `SET000001` | `source_document_number` não é um CPF/CNPJ válido. | | 400 | `SET000050` / `SET000051` | `expense_type` inválido, ou mais de uma despesa do mesmo tipo. | | 400 | `QIT000001` | Corpo inválido (campo obrigatório ausente, formato inválido ou campo não aceito). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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. Só é aceito com o lote em `pending_settlements_insertion` e com ao menos uma liquidação `validated` ou `pending_validation`. | | `discarded` | Descarta o lote inteiro. Nenhuma liquidação será processada. Aceito com o lote em `pending_settlements_insertion`, `pending_validation` ou `pending_payment`. | ## 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. Veja abaixo. | **Status devolvido:** | Você enviou | Status devolvido | O que significa | |---|---|---| | `pending_payment` | `pending_payment` | Lote encerrado; aguarda a confirmação do pagamento. | | `pending_payment` | `pending_validation` | Há liquidações em revisão pela QI Tech. Quando a revisão terminar, o lote segue sozinho para `pending_payment`. | | `discarded` | `pending_discard` ou `pending_discard_on_cash_account` | Descarte em processamento. O status final `discarded` chega pelo [webhook do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook). | ## Próximos passos Após encerrar o lote, o processamento é iniciado automaticamente. Acompanhe o resultado através dos webhooks ou da [consulta do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao): 1. **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificação quando o lote for pago, concluído ou descartado. 2. **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificação individual de cada liquidação processada. ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil (gestora do fundo, consultoria vinculada ou cedente associado). | | 404 | `SET000010` | O lote informado na URL não existe neste fundo. | | 400 | `SET000026` | `batch_status` diferente de `pending_payment` ou `discarded`. | | 400 | `SET000049` | Pedido de encerramento para um lote já em `pending_payment`, `paid` ou `completed`. | | 400 | `SET000016` | Pedido de encerramento para um lote fora de `pending_settlements_insertion` (por exemplo, em `pending_validation` ou em descarte). | | 400 | `SET000017` | O lote não tem nenhuma liquidação `validated` ou `pending_validation`. | | 400 | `SET000069` | Pedido de descarte para um lote já em status final (`paid`, `completed` ou `discarded`). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. Para consultar um lote específico pelo `external_id`, use a [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Visualizar Lotes | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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`. | ```text 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": "22.333.444/0001-81" }, "fund_class_key": "a3ecf74b-d280-4d3c-aefd-cb223dbf0451", "document_number": "11.222.333/0001-81", "accounting_date": "2025-08-08", "payment_batch_automatic_discard": false }, "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_validation` | Lote encerrado com liquidações em revisão pela QI Tech. | | `pending_payment` | Lote encerrado, aguardando processamento do pagamento. | | `paid` | Pagamento do lote realizado; liquidações em processamento. | | `completed` | Todas as liquidações chegaram a `settled` ou `discarded`. | | `pending_discard` | Descarte solicitado, em processamento. | | `pending_discard_on_cash_account` | Descarte solicitado, aguardando o cancelamento na conta caixa. | | `discarded` | Lote descartado. | Os lotes também trazem `settlement_expenses` quando há despesas de liquidação, e ecoam os campos enviados na criação. Veja a [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao#atributos-da-resposta). ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta de Lote de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao Retorna um lote de pagamento pelo `external_id` informado na criação. Use para acompanhar o status do lote ou quando a criação devolve duplicidade (`SET000009`). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Visualizar Lotes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave do fundo (UUID). | | `external_id` | string | O `external_id` informado na [criação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). Também aceita o `payment_batch_key` devolvido pela QI Tech. | ## Response STATUS 200 A resposta ecoa os campos enviados na criação do lote (por exemplo `account`, `source_document_number`, `end_to_end_id`) e acrescenta os dados abaixo. ```json title="Response 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" }, "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "11.222.333/0001-81", "accounting_date": "2025-01-01", "payment_batch_automatic_discard": false }, "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b", "status": "pending_payment", "reference_date": "2025-01-01", "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "total_value": 4520.75, "settlement_expenses": [ { "settlement_expense_key": "0b6f3c1e-8f0a-4c55-9a4e-2f1d7c9e3b10", "amount": 15.00, "status": "pending_submission", "description": "Despesa de Liquidação - Despesa Bancária", "type": "bank_account" } ] } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | Chave externa do lote fornecida pelo parceiro. | | `description` | string | Descrição do lote. Quando não informada na criação, é gerada como `Lote de Pagamento - {reference_date} - {external_id}`. | | `fund_class` | object | Dados do fundo: `name`, `manager` (`name`, `manager_key`, `document_number`), `fund_class_key`, `document_number`, `accounting_date` (data contábil atual do fundo) e `payment_batch_automatic_discard`. | | `payment_batch_key` | string | Identificador único do lote gerado pela QI Tech (UUID). | | `status` | string | Status atual do lote. Veja abaixo. | | `reference_date` | string | Data de referência do lote, no formato `YYYY-MM-DD`. | | `account_key` | string | Chave da conta associada ao lote (UUID). | | `total_value` | number | Valor total do lote. Presente depois que o total é apurado. | | `settlement_expenses` | array | Despesas de liquidação informadas na criação, com `settlement_expense_key`, `amount`, `status`, `description` e `type`. Presente apenas quando há despesas. | ### Status do lote | Status | Significado | |---|---| | `pending_settlements_insertion` | Lote criado, aceitando liquidações. | | `pending_validation` | Lote encerrado com liquidações em revisão pela QI Tech. Ao fim da revisão, segue para `pending_payment`. | | `pending_payment` | Lote encerrado, aguardando a confirmação do pagamento. | | `paid` | Pagamento confirmado; as liquidações estão sendo processadas. | | `completed` | Todas as liquidações chegaram a `settled` ou `discarded`. Status final. | | `pending_discard` / `pending_discard_on_cash_account` | Descarte solicitado, em processamento. | | `discarded` | Lote descartado. Status final. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000010` | Não existe lote com este `external_id` (nem com este `payment_batch_key`) no fundo. | | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil (gestora do fundo, consultoria vinculada ou cedente associado). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. Só três geram webhook: `paid`, `completed` e `discarded`. Os demais — `pending_settlements_insertion`, `pending_validation`, `pending_payment`, `pending_discard` e `pending_discard_on_cash_account` — resultam das suas chamadas de [criação](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) e [encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento), ou de etapas internas, e **não** disparam notificação. Para acompanhá-los, use a [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao). ![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._ | Status | Quando acontece | Webhook? | |---|---|---| | `pending_settlements_insertion` | Lote criado, aceitando liquidações. | Não | | `pending_validation` | Lote encerrado com liquidações em revisão pela QI Tech. Ao fim da revisão, segue sozinho para `pending_payment`. | Não | | `pending_payment` | Lote encerrado, aguardando a confirmação do pagamento. | Não | | `paid` | Pagamento confirmado; as liquidações passam a ser processadas. | **Sim** | | `completed` | Todas as liquidações chegaram a `settled` ou `discarded`. Uma liquidação em `inconsistent_asset` segura o lote em `paid` até ser tratada. | **Sim** | | `pending_discard` / `pending_discard_on_cash_account` | Descarte solicitado (ou automático) em processamento. | Não | | `discarded` | Lote descartado. | **Sim** | ## 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-e-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": "11.222.333/0001-81", "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 DTVM 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": "11.222.333/0001-81", "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-e-formado). ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "completed", "fund_class_document_number": "11.222.333/0001-81", "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 descarte do lote é concluído. Isso ocorre: - por solicitação do parceiro integrador no [encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) (`batch_status: discarded`); ou - por descarte automático, nos fundos configurados para isso: lotes que continuam em `pending_settlements_insertion`, `pending_validation` ou `pending_payment` quando a data contábil do fundo avança são descartados. Quando o lote já estava em `pending_payment` com valor apurado, o descarte passa antes pelo cancelamento da expectativa na conta caixa (`pending_discard_on_cash_account`). Nenhuma liquidação associada ao lote será processada após este status, e as liquidações abertas são descartadas sem webhook próprio. 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": "11.222.333/0001-81", "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 400 — Contratos Parcelados URL: /documentation/iaas/negociacao_recebiveis/arquivo/cnab400_contrato Layout do arquivo de **remessa de cessão de contratos parcelados** no padrão CNAB 400 de cobrança (registros `0`, `1`, `2` e `9`). Cada registro `1` é uma parcela; as parcelas com o mesmo número do documento formam um contrato. :::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, ou pela API da gestora. O layout 400 só é aceito em configuração de cessão de **contrato parcelado** (`contract`) ou de **contrato descontado** (`discounted_contract`). Em qualquer outra configuração o arquivo é recusado com a mensagem *"O layout CNAB 400 aceita apenas cessão de contratos, mas a configuração de cessão é de '…'."* ::: [Baixar remessa de exemplo](/downloads/modelos_arquivo/exemplo_cessao_contrato_cnab400.rem) — dados fictícios: troque o código do originador no header (posições 27–46) pelo seu antes de testar. ## Estrutura do arquivo | Registro | Identificação (posição 1) | Quantidade | |---|---|---| | **Header** | `0` | 1, sempre a primeira linha | | **Detalhe** | `1` | 1 por parcela | | **Complemento** | `2` | Opcional, depois de uma parcela. É conferido e não altera o contrato | | **Trailer** | `9` | 1, sempre a última linha | Todas as linhas têm **exatamente 400 caracteres**, sem contar a quebra de linha. O arquivo é reconhecido como CNAB 400 pelo tamanho das linhas: não remova os espaços do fim da linha. ## Regras gerais de preenchimento | Regra | Detalhe | |---|---| | **Tamanho fixo** | Toda linha tem 400 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** | 13 posições, com 2 casas decimais, **sem** vírgula ou ponto. `R$ 1.234,56` → `0000000123456`. | | **Datas** | Formato `DDMMAA`. Ex.: 15/10/2026 → `151026`. | | **Extensão** | `.rem` ou `.txt`. Quebra de linha `CRLF` ou `LF`. | ## 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 cadastrado na configuração de cessão, alinhado à direita com zeros | | 7 | 047–076 | 30 | Nome do originador | Sim | Razão social | | 8 | 077–079 | 3 | Número do banco | Sim | Dígitos | | 9 | 080–094 | 15 | Nome do banco | Sim | Não pode ficar em branco | | 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 | Sim | Dígitos | | 14 | 118–394 | 277 | Brancos | Sim | Exatamente 277 espaços | | 15 | 395–400 | 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. Solicite o código no processo de homologação do cedente. ::: ## Registro Detalhe (parcela) Um registro por parcela. Só os campos abaixo são lidos; as demais posições do layout de cobrança (por exemplo, 002–037, conta de débito e identificação da empresa) podem vir preenchidas e não são usadas. | # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito | |---|---|---|---|---|---| | 1 | 001–001 | 1 | Identificação do registro | Sim | `1` | | 2 | 038–062 | 25 | **Nº de controle do participante** | Sim | Identificador da parcela no seu sistema. Único no arquivo e não deve mudar depois da cessão: é por ele que a parcela é encontrada na liquidação | | 3 | 109–110 | 2 | **Identificação da ocorrência** | Sim | `01` (entrada) | | 4 | 111–120 | 10 | **Nº do documento** | Sim | Número do contrato. Repita o mesmo número em todas as parcelas do contrato | | 5 | 121–126 | 6 | **Data de vencimento** | Sim | `DDMMAA` | | 6 | 127–139 | 13 | **Valor de face** | Sim | Valor da parcela, 2 decimais, maior que zero | | 7 | 148–149 | 2 | **Espécie do título** | Sim | `60` contrato · `61` contrato físico | | 8 | 151–156 | 6 | **Data de emissão** | Sim | `DDMMAA`. Igual em todas as parcelas do contrato | | 9 | 193–205 | 13 | **Valor presente (aquisição)** | Sim | Preço que o fundo paga pela parcela (valor de face com o desconto acertado), 2 decimais, maior que zero | | 10 | 219–220 | 2 | **Tipo de inscrição do sacado** | Sim | `01` pessoa física (CPF), `02` pessoa jurídica (CNPJ) | | 11 | 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.** Igual em todas as parcelas do contrato | | 12 | 235–274 | 40 | **Nome do sacado** | Sim | Não pode ficar em branco | | 13 | 275–314 | 40 | **Endereço do sacado** | Sim | Não pode ficar em branco. Ex.: `AV EXEMPLO, 100` | | 14 | 327–334 | 8 | **CEP do sacado** | Sim | 8 dígitos, sem hífen | | 15 | 395–400 | 6 | Nº sequencial do registro | Sim | Sequencial da linha | :::caution Posições 193–205 No layout de cobrança bancária essas posições costumam trazer o IOF, muitas vezes zerado. Na cessão elas trazem o **valor presente da parcela**: com zeros, a linha é recusada. ::: ## Registro Complemento | # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito | |---|---|---|---|---|---| | 1 | 001–001 | 1 | Identificação do registro | Sim | `2` | | 2 | 002–394 | 393 | Mensagens e descontos do boleto | Não | Livre; não é lido | | 3 | 395–400 | 6 | Nº sequencial do registro | Sim | 6 dígitos | ## Registro Trailer | # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito | |---|---|---|---|---|---| | 1 | 001–001 | 1 | Identificação do registro | Sim | `9` | | 2 | 002–394 | 393 | Brancos | Sim | Exatamente 393 espaços | | 3 | 395–400 | 6 | Nº sequencial do registro | Sim | 6 dígitos | ## Como as parcelas viram contratos - **Agrupamento:** linhas com o mesmo **Nº do documento** (111–120) são as parcelas de um mesmo contrato, e esse número vira o identificador e o número do contrato na carteira. O arquivo pode ter contratos de vários sacados. - **Consistência:** todas as parcelas de um contrato precisam ter o mesmo **Nº de inscrição do sacado** e a mesma **data de emissão**; senão, o arquivo é recusado. Os demais dados do sacado vêm da primeira linha do contrato. - **Numeração:** não informe número de parcela. As parcelas de cada contrato são numeradas 1, 2, 3, … pela data de vencimento. - **Nº de controle do participante:** obrigatório e sem repetição no arquivo. - **Valores:** o valor de compra do contrato é a soma dos valores presentes das suas parcelas. O layout 400 não traz taxa, e o contrato entra sem taxa nominal. ## Exemplo O [arquivo de exemplo](/downloads/modelos_arquivo/exemplo_cessao_contrato_cnab400.rem) tem dois contratos: | Linha | Registro | Nº do documento | Nº de controle | Vencimento | Valor de face | Valor presente | Resultado | |---|---|---|---|---|---|---|---| | 2 | `1` | `CT4001` | `400002` | 15/10/2026 | 1.500,00 | 1.400,00 | Contrato CT4001, parcela 1 | | 3 | `2` | — | — | — | — | — | Complemento, não lido | | 4 | `1` | `CT4001` | `400001` | 15/11/2026 | 1.500,00 | 1.350,00 | Contrato CT4001, parcela 2 | | 5 | `2` | — | — | — | — | — | Complemento, não lido | | 6 | `1` | `CT4002` | `400003` | 20/10/2026 | 800,00 | 760,00 | Contrato CT4002, parcela 1 | | 7 | `2` | — | — | — | — | — | Complemento, não lido | O contrato CT4001 entra com valor de compra de R$ 2.750,00 e o CT4002 com R$ 760,00. --- # Layout CNAB 444 — Cessão URL: /documentation/iaas/negociacao_recebiveis/arquivo/cnab444 Layout do arquivo de **remessa de cessão** aceito pela QI DTVM. É 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, ou pela API da gestora. 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 DTVM 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 DTVM, 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](#ocorrencias-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. **Estes 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) | | `51`, `52`, `87` | Cheque | `check` | — | Dispensada | — | | `02`, `06` | Nota promissória | `promissory_note` | — | Dispensada | — | No cheque e na nota promissória, o número do instrumento é o **Nº do documento** (posições 111–120) e a data de emissão é a das posições 151–156. O banco (063–065) e a agência (143–147), quando preenchidos, também são levados ao instrumento: use-os no cheque e deixe-os em branco ou zerados na nota promissória, que não aceita esses campos e teria o ativo recusado. :::caution Outros códigos passam na estrutura, mas não são processados O layout CNAB 444 prevê outras espécies — `41` CCB digital, `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) (ou [CTE](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte)). | 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 DTVM. É 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, ou pela API da gestora. 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,José de Souza,969.698.790-03,1,2026-12-25,500.46 contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,José de Souza,969.698.790-03,2,2027-01-25,500.46 contract,CONTRATO_0002,2244927986/XXX,450.00,post_fixed,Empresa Souza LTDA,11.222.333/0001-81,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 --- # Layout CSV — Duplicatas, CT-e, Cheques e Notas Promissórias URL: /documentation/iaas/negociacao_recebiveis/arquivo/csv_duplicatas_titulos Layout do arquivo CSV de **cessão de duplicatas, CT-e, cheques e notas promissórias** (`asset_type` igual a `duplicata_mercantil`, `duplicata_servicos`, `cte`, `check` ou `promissory_note`) aceito pela QI DTVM. É um CSV com **uma linha por título**: cada linha é um ativo do lote. É uma alternativa à remessa [CNAB 444](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444), que continua aceita para os mesmos títulos. :::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, ou pela API da gestora. Para ceder duplicata ativo a ativo pela API, veja [Criação de Ativo — Duplicata](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata). ::: **📄 Baixar modelo CSV:** [duplicata mercantil](/downloads/modelos_arquivo/modelo_cessao_duplicata_mercantil.csv) · [duplicata de serviços](/downloads/modelos_arquivo/modelo_cessao_duplicata_servicos.csv) · [CT-e](/downloads/modelos_arquivo/modelo_cessao_cte.csv) · [cheque](/downloads/modelos_arquivo/modelo_cessao_check.csv) · [nota promissória](/downloads/modelos_arquivo/modelo_cessao_promissory_note.csv) Todos os modelos têm o mesmo cabeçalho; cada um vem com uma linha de exemplo do seu tipo. Apague a linha 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 **título**. Cada linha é um ativo do lote | | **Um tipo por arquivo** | Todas as linhas têm o `asset_type` da configuração de cessão selecionada. Para ceder duplicatas e cheques, por exemplo, envie um lote para cada configuração | | **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$ 960,00` → `960.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 que não se aplicam ao título da linha (por exemplo, nota fiscal em um cheque) ficam no cabeçalho e em branco na linha. ::: ## Colunas ### Identificação | Coluna | Obrigatoriedade | Descrição | |---|---|---| | `asset_type` | obrigatória | Tipo do título: `duplicata_mercantil`, `duplicata_servicos`, `cte`, `check` ou `promissory_note`. Precisa ser igual ao tipo da configuração de cessão, em todas as linhas | | `external_id` | obrigatória | Identificador do título no seu sistema, até 25 caracteres. É a chave do ativo e não pode se repetir no arquivo | | `order_number` | obrigatória | Número do título (seu número), até 45 caracteres. No cheque e na nota promissória é o número do próprio título, com até 20 caracteres | | `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 | ### Datas e valores | Coluna | Obrigatoriedade | Descrição | |---|---|---| | `issue_date` | obrigatória | Data de emissão, em `AAAA-MM-DD`. Nas duplicatas e no CT-e é a data de emissão da nota; no cheque e na nota promissória, a do título | | `maturity_date` | obrigatória | Data de vencimento do título, em `AAAA-MM-DD` | | `face_value` | obrigatória | Valor de face — quanto o sacado paga no vencimento. Ponto como separador decimal, até 8 casas | | `total_purchase_value` | obrigatória | Valor que o fundo paga pelo título (preço de aquisição). Não pode ser maior que o `face_value` | ### Nota fiscal | Coluna | Obrigatoriedade | Descrição | |---|---|---| | `invoice_access_key` | condicional | Chave de acesso da NF-e ou do CT-e, exatamente 44 dígitos, sem espaços. O modelo (posições 21–22 da chave) precisa ser `55` na duplicata mercantil e `57` ou `67` no CT-e. Obrigatória para `duplicata_mercantil` e `cte`; opcional para `duplicata_servicos`; em branco para cheque e nota promissória | | `invoice_number` | condicional | Número da nota fiscal, até 9 dígitos. Obrigatória para `duplicata_mercantil`, `duplicata_servicos` e `cte` | | `invoice_serie` | opcional | Série da nota fiscal, até 3 caracteres. Em branco, é assumida a série `1` | ### Cheque | Coluna | Obrigatoriedade | Descrição | |---|---|---| | `bank_code` | opcional | Código do banco do cheque, 3 dígitos | | `agency` | opcional | Agência do cheque, até 5 dígitos | ### 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_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` | obrigatória | CEP no formato `00000-000`. Os demais campos de endereço em branco são completados pelo CEP | | `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`). Em branco, é assumido `BRA` | ## Regras do arquivo - **Uma linha por título.** O `external_id` não pode se repetir no arquivo, e o contador de ativos do lote é o número de linhas. - **Um tipo por arquivo.** O `asset_type` de todas as linhas precisa ser o da configuração de cessão; uma linha de outro tipo recusa o arquivo. - **Nota fiscal conforme o tipo.** `duplicata_mercantil` exige `invoice_access_key` de modelo `55` e `cte` exige modelo `57` ou `67`, ambos com `invoice_number`; `duplicata_servicos` exige só `invoice_number`. - **Cheque e nota promissória não têm nota fiscal.** O `order_number` é o número do título e a `issue_date` é a data de emissão. Banco e agência valem apenas para cheque. - **O `face_value` não pode ser menor que o `total_purchase_value`.** - **Todas as linhas precisam ter o mesmo `originator_document_number`**, e esse originador precisa estar cadastrado e vinculado à configuração de cessão. - **Lote de substituição:** as linhas de recompra entram no mesmo CSV, com as colunas de recompra (`assignor_document_number`, `settlement_type` e `repurchase_value`) e as demais colunas em branco. - **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 | |---|---| | A coluna obrigatória … está ausente no arquivo | O cabeçalho foi editado ou salvo de um modelo antigo | | A coluna … não é reconhecida | Coluna de outro modelo (CCB, contrato) ou nome traduzido | | O campo Chave de acesso da nota fiscal é obrigatório | Duplicata mercantil ou CT-e sem `invoice_access_key` | | O campo Chave de acesso da nota fiscal deve ter 44 dígitos, com o modelo 55 (NF-e) … | Chave com espaços, pontuação, tamanho errado ou modelo que não é o do tipo (NF-e numa linha de CT-e, por exemplo) | | O tipo de ativo … não é o da configuração da cessão | Linha com `asset_type` diferente do tipo da configuração selecionada | | O identificador … está duplicado | Duas linhas com o mesmo `external_id` | | O 'face_value' não pode ser menor que o 'total_purchase_value' | Preço de aquisição acima do valor de face | ## Exemplo ```csv title="modelo_cessao_duplicata_mercantil.csv (colunas principais)" asset_type,external_id,order_number,issue_date,maturity_date,face_value,total_purchase_value,invoice_access_key,invoice_number duplicata_mercantil,DUPLICATA_0001,000123-1,2026-11-01,2026-12-25,1000.00,960.00,35261153020654000143550010000001231000001230,000000123 duplicata_mercantil,DUPLICATA_0002,000124-1,2026-11-01,2027-01-25,1000.00,940.00,35261153020654000143550010000001241000001240,000000124 ``` 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 do seu tipo: [duplicata mercantil](/downloads/modelos_arquivo/modelo_cessao_duplicata_mercantil.csv) · [duplicata de serviços](/downloads/modelos_arquivo/modelo_cessao_duplicata_servicos.csv) · [CT-e](/downloads/modelos_arquivo/modelo_cessao_cte.csv) · [cheque](/downloads/modelos_arquivo/modelo_cessao_check.csv) · [nota promissória](/downloads/modelos_arquivo/modelo_cessao_promissory_note.csv). ## Checklist antes de enviar - [ ] Cabeçalho igual ao do modelo, sem colunas extras nem faltando - [ ] `asset_type` de todas as linhas igual ao tipo da configuração de cessão - [ ] Um `external_id` diferente por linha, com até 25 caracteres - [ ] Chave de acesso (44 dígitos) e número da nota nas duplicatas mercantis e CT-e - [ ] Colunas de nota fiscal em branco nos cheques e notas promissórias - [ ] `face_value` maior ou igual ao `total_purchase_value` - [ ] 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 — ou, para a gestora, também pela API. 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: portal ou API da gestora No **portal** do gestor e do consultor, o envio é feito pela tela descrita abaixo. A **gestora** também pode enviar o arquivo pela API (`manager-api`, permissão de Escrita), em três chamadas: 1. `POST /trade_receivables_files/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment` com `external_id`, `filename` (extensão `.rem`, `.txt` ou `.csv`), `assignment_type` (`assignment` ou `substitution_assignment`) e `assignment_date` (a data contábil aberta do fundo). A resposta traz em `bucket_link` a `url` e os `fields` de um upload por formulário (POST multipart), válido por 10 minutos. 2. Upload do arquivo para a `url` de `bucket_link`, com os `fields` devolvidos. 3. `PUT /trade_receivables_files/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/file_uploaded`, sem body, que dispara a validação do arquivo. Esse fluxo ainda não tem página de referência; para detalhes, fale com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). Consultoria e cedente cedem pela API ativo a ativo, pelo fluxo de [criação de lote + inserção de ativos](/documentation/iaas/negociacao_recebiveis/fluxo_cessao). ::: | | 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, CT-e, cheques e notas promissórias), CNAB 400 (contratos parcelados) e CSV (duplicatas, CT-e, cheques, notas promissórias, 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 da gestora | 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 | Manual | Modelo | |---|---|---|---|---| | `duplicata_mercantil` | **CNAB 444**, espécie `01`, ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 444 · Layout CSV — Duplicatas e Títulos | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) · [Modelo CSV](/downloads/modelos_arquivo/modelo_cessao_duplicata_mercantil.csv) | | `duplicata_servicos` | **CNAB 444**, espécie `14`, ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 444 · Layout CSV — Duplicatas e Títulos | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) · [Modelo CSV](/downloads/modelos_arquivo/modelo_cessao_duplicata_servicos.csv) | | `cte` | **CNAB 444**, espécie `53`, ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 444 · Layout CSV — Duplicatas e Títulos | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) · [Modelo CSV](/downloads/modelos_arquivo/modelo_cessao_cte.csv) | | `check` (cheque) e `promissory_note` (nota promissória) | **CNAB 444**, espécies `51`, `52` e `87` (cheque) e `02` e `06` (nota promissória), ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 444 · Layout CSV — Duplicatas e Títulos | [Modelo CSV — cheque](/downloads/modelos_arquivo/modelo_cessao_check.csv) · [Modelo CSV — nota promissória](/downloads/modelos_arquivo/modelo_cessao_promissory_note.csv) | | `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) | **CNAB 400**, espécie `60` ou `61`, ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 400 — Contratos Parcelados · Layout CSV — Contratos Parcelados | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_contrato_cnab400.rem) · [Modelo CSV](/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 Para **cessão de duplicatas, CT-e, cheques e notas promissórias** você escolhe entre 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) — e o **CSV** descrito em [Layout CSV — Duplicatas, CT-e, Cheques e Notas Promissórias](/documentation/iaas/negociacao_recebiveis/arquivo/csv_duplicatas_titulos). CCB e honorários entram apenas por CSV. Contratos parcelados entram por CSV, descrito em [Layout CSV — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado), ou por remessa CNAB 400 de cobrança, descrita em [Layout CNAB 400 — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/cnab400_contrato). O layout 400 só é aceito em configuração de contrato parcelado ou de contrato descontado. Contratos descontados (`discounted_contract`) entram por remessa CNAB 400/444/500 com espécie `60` ou `61`, ou por CSV com o modelo disponível na tela de envio. ::: ## 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. No CSV de duplicatas e títulos vale o mesmo: cada linha precisa de um `external_id` 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 DTVM 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. O mesmo contrato vale para `structured_cci`. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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 o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::caution Atenção O campo `external_id` da operação de crédito identifica o ativo dentro do lote 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": "Empresa Exemplo Ltda", "document_number": "11.222.333/0001-81", "person_type": "legal_person", "email": "financeiro@empresaexemplo.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": "22.333.444/0001-81", "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": "33.444.555/0001-81" }, "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. Veja [Atributos de `premiums`](#atributos-de-premiums). | | `deductions` | array | opcional | Lista de deságios envolvidos na venda. Veja [Atributos de `deductions`](#atributos-de-deductions). | | `credit_operation` | object | obrigatório | Dados da operação de crédito. Veja [Atributos de `credit_operation`](#atributos-de-credit_operation). | :::info Ágios e deságios entram na conferência de valor Na inserção, a QI Tech calcula o valor presente das parcelas e o compara com o valor de compra do ativo: `total_purchase_value` − soma de `premiums` + soma de `deductions`. Diferenças pequenas são registradas automaticamente como ajuste (`math_adjustment`); acima disso, a inserção devolve `TRC100014`. ::: #### Atributos de `premiums` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `premium_type` | string | obrigatório | Tipo do ágio: `spread`, `math_adjustment`, `banker_fee`, `transaction_fee` ou `originator_fee`. | | `total_value` | number | obrigatório | Valor total do ágio. Mínimo `0.01`. Até 2 casas decimais. | #### Atributos de `deductions` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `deduction_type` | string | obrigatório | Tipo do deságio: `bad_debt_discount` ou `math_adjustment`. | | `total_value` | number | obrigatório | Valor total do deságio. Mínimo `0.01`. Até 2 casas decimais. | #### 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 (`000.000.000-00` ou `00.000.000/0000-00`) do originador que viabilizou a operação. Precisa estar cadastrado na QI Tech; caso contrário, devolve `TRC000019`. | | `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 | condicional | Dados do cálculo 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 do cálculo da parte pós-fixada. Obrigatório quando `interest_rate_type` for `post_fixed`. Veja [Atributos de `post_fixed`](#atributos-de-post_fixed). | | `installments` | array | obrigatório | Lista de parcelas da operação. Veja [Atributos de `installments`](#atributos-de-installments). | | `delay` | object | obrigatório | 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. Quando omitido, vale o da configuração de cessão. | | `b3_code` | string | opcional | Código do ativo na B3. Até 50 caracteres. Só é aceito quando a configuração de cessão usa registro `registry_transfer`, `deferred_registry` ou `external_registry`; nas demais, devolve `TRC000188`. | | `b3_self_code` | string | opcional | Código próprio do ativo na B3. Até 50 caracteres. Mesma regra de `b3_code`. | | `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. | | `price_days` | Amortização do tipo Price com juros calculados por dias corridos. | **Enumeradores de `interest_rate_type`:** | Valor | Descrição | |---|---| | `pre_fixed` | Para operações pré-fixadas. Informe o objeto `pre_fixed`. | | `post_fixed` | Para operações pós-fixadas. Informe o objeto `post_fixed`. | #### 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 | 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. O CPF em `document_number` tem o dígito verificador conferido. 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 | 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, em maiúsculas (ex.: `SP`). | | `complement` | string | opcional | Complemento. Máximo de 255 caracteres. | | `postal_code` | string | obrigatório | CEP no formato `00000-000`. Obrigatório sempre que o objeto `address` for informado. | | `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. | | `international_dial_code` | string | opcional | Código internacional (DDI). Até 3 caracteres. | #### 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 | 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. 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 | obrigatório | E-mail do representante. Máximo de 255 caracteres. | | `phone` | object | obrigatório | Telefone. Mesma estrutura de [Atributos de `phone`](#atributos-de-phone). | | `address` | object | obrigatório | Endereço. Mesma estrutura de [Atributos de `address`](#atributos-de-address). | | `person_type` | string | opcional | 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, em fração decimal entre 0 e 1. Para 1%, informar `0.01`. Até 8 casas decimais. | | `nominal_monthly_rate` | number | opcional | Taxa mensal nominal do contrato, no mesmo formato de `monthly_rate`. | **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 `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-pre_fixed). | | `indexer` | string | obrigatório | Índice que corrige a operação: `di`, `selic` ou `ipca`. | | `rate` | number | obrigatório | Taxa aplicada sobre o indexador. Para 100% do DI, informar `1`. | | `lag` | object | obrigatório | Defasagem do índice: `reference` (`daily` ou `monthly`) e `amount` (quantidade). Para usar o índice de dois meses antes, informar `{"reference": "monthly", "amount": 2}`. | #### 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 | obrigatório | 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. | | `external_id` | string | opcional | Identificador da parcela no seu sistema. | #### Atributos de `delay` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `fine` | object | obrigatório | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). Sem multa, envie `fine_type` `percentage` com `percentage_value` `0`. | | `interest` | object | obrigatório | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). Sem juros de mora, envie `monthly_rate` `0`. | #### 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 | Taxa do juros de mora: `calendar_base` e `monthly_rate` **ou** `daily_rate`. Não aceita `nominal_monthly_rate`. Veja [Atributos de `pre_fixed` do juros de mora](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte#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 `consignee` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `name` | string | opcional | 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-imovel). | | `vehicle` | Garantia de veículo. Incluir os campos de [Atributos de garantia veículo](#atributos-de-garantia-veiculo). | #### 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. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. | | 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. | | 404 | `TRC000015` | O `asset_type` não existe. | | 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. | | 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). | | 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. | | 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. | | 400 | `TRC000188` | `b3_code` ou `b3_self_code` enviados numa configuração cujo tipo de registro não os aceita. | | 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. | | 400 | `TRC100014` | O valor presente do fluxo de parcelas não bate com o valor de compra (`total_purchase_value`, ágios e deságios). | | 400 | `TRC100004` / `TRC100005` | Parcelas sem numeração sequencial ou fora de ordem crescente de vencimento. | | 400 | `TRC100009` | `issue_value` menor que o principal da operação. | | 409 | `TRC100017` | O fundo não pode comprar ativos vencidos. | Os códigos `TRC1000xx` vêm da validação financeira do ativo, feita na inserção. O corpo de erro segue o formato abaixo: ```json { "title": "Already Exist This External Id", "description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3", "translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3", "code": "TRC000054" } ``` Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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 o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::tip Contrato descontado ou contrato parcelado? Pense num contrato de 5 parcelas como uma cartela com 5 cupons. - **[Contrato descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract)** (`discounted_contract`): você cede **cupons soltos**. Cada parcela é um ativo e vai numa requisição só dela. - **[Contrato parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract)** (`contract`): você cede **a cartela inteira**. O contrato é um ativo só e vai numa requisição, com as parcelas dentro. | | Contrato descontado | Contrato parcelado | |---|---|---| | O ativo é | uma parcela | o contrato inteiro | | Requisições por contrato | uma por parcela | uma | | O que você precisa ter na hora | só a parcela que vai ceder | valor e vencimento de todas as parcelas que vai ceder | | Preço (`total_purchase_value`) | de cada parcela | do contrato; a QI Tech reparte entre as parcelas | | Como as parcelas são cedidas | uma a uma, cada uma no lote que você quiser | juntas, no mesmo ativo | | Recusa na elegibilidade | sai só a parcela | sai o contrato inteiro | | [Boleto](/documentation/iaas/boletos/campos_do_boleto) | um por parcela | um por parcela | | [Pagamentos informados por você](/documentation/iaas/liquidacao_ativos/ativos/ativos) | todos os tipos de direito creditório, inclusive devolução, glosa e juros | só liquidação e amortização, do contrato ou de uma parcela | | Prorrogar o vencimento | sim, parcela a parcela (`asset_extension`) | não | | [Recompra](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset) | parcela a parcela | só o contrato inteiro | | [Relatório de estoque](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) | uma linha por parcela; a coluna de número do contrato traz o `order_number` | uma linha por parcela, com o número do contrato e o da parcela | **Qual combina com a sua operação:** - Vende parcelas aos poucos, escolhe quais vender ou precisa prorrogar, devolver ou recomprar parcelas soltas: **contrato descontado**. - Vende o contrato como uma unidade, com um preço só, e todas as parcelas são conhecidas na hora da cessão: **contrato parcelado**. O tipo não é escolhido no envio: ele vem da sua configuração de cessão, e o lote só aceita ativos desse tipo (`TRC000025`). Para ver o seu, consulte o `asset_type` na [listagem de configurações](/documentation/iaas/negociacao_recebiveis/listagem). Para mudar de tipo, fale com o time de integração. ::: :::caution Atenção O campo `external_id` do contrato identifica o ativo dentro do lote 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": "22.333.444/0001-81", "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": "José de Souza", "document_number": "969.698.790-03", "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 Não envie `premiums` nem `deductions` em contrato parcelado: eles não são registrados para este tipo de ativo. O valor de aquisição do ativo é 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 do originador que viabilizou a operação, no formato `000.000.000-00` ou `00.000.000/0000-00`. O originador precisa estar cadastrado na QI Tech com esse documento; caso contrário, a inserção devolve `TRC000019`. | | `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. Em cessão com boleto, vira o número de controle do [boleto](/documentation/iaas/boletos/campos_do_boleto) da parcela: envie um valor único por parcela, com até 25 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. ::: ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. | | 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. | | 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. | | 400 | `TRC000084` | O objeto `contract` foi enviado com um `asset_type` diferente de `contract` (por exemplo, `financing_contract` ou `debt_acknowledgment`, que não são cedidos por este fluxo). | | 400 | `TRC000174` | Ordenando as parcelas por `maturity_date`, os `installment_number` não formam a sequência `1, 2, 3, …`. | | 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). | | 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. | | 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Confira se o documento está formatado exatamente como no cadastro. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. | | 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. | | 400 | `TRC1000xx` | A validação financeira do ativo recusou o fluxo. Exemplo: `TRC100014`, valor presente das parcelas diferente do `total_purchase_value`. | O corpo de erro segue o formato abaixo: ```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" } ``` Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie, com `document_type` igual a `contract`, o PDF do contrato parcelado deste ativo (o contrato com o devedor, não o contrato de cessão). Um arquivo por ativo. 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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 o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::caution Atenção O campo `external_id` do direito creditório identifica o ativo dentro do lote 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": "22.333.444/0001-81", "maturity_date": "2023-12-10", "order_number": "18923619954796912", "face_value": 1023.01, "person_type": "legal_person", "borrower": { "name": "Transportadora Exemplo Ltda", "document_number": "11.222.333/0001-81", "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": "35231011222333000181570010000000011892361995", "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 (`000.000.000-00` ou `00.000.000/0000-00`) do originador que viabilizou a operação. Precisa estar cadastrado na QI Tech; caso contrário, devolve `TRC000019`. | | `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. Sem ele, a inserção devolve `TRC000078`. Em cessão com boleto, os 10 últimos caracteres viram o número do documento do boleto. | | `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. | | `invoice` | object | obrigatório | Dados do CT-e. Veja [Atributos de `invoice`](#atributos-de-invoice). Sem ele, a inserção devolve `TRC000075`. Não envie o objeto `contract` neste tipo de ativo (`TRC000076`). | | `participant_control_number` | string | opcional | Número de controle do participante no sistema do parceiro. Máximo de 25 caracteres alfanuméricos. Em cessão com boleto, vira o número de controle do participante do boleto e deve ser enviado sempre, com valor único. Veja [Do ativo ao boleto](/documentation/iaas/boletos/campos_do_boleto). | | `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. As posições 21 e 22 da chave precisam ser o 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 `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 | obrigatório | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). | | `interest` | object | obrigatório | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). | Quando enviar `delay`, informe `fine` e `interest`. Este objeto vale para todos os direitos creditórios (duplicatas e CT-e). #### 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. Para 1%, informar `0.01`. Informe `daily_rate` **ou** `monthly_rate`. | | `monthly_rate` | number | condicional | Taxa mensal. Para 1%, informar `0.01`. Informe `daily_rate` **ou** `monthly_rate`. | | `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. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. | | 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. | | 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. | | 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). | | 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. | | 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. | | 400 | `TRC000078` | `order_number` ausente. | | 400 | `TRC000075` | Objeto `invoice` ausente. | | 400 | `TRC000076` | Objeto `contract` enviado num CT-e. | | 400 | `TRC000134` | `invoice.access_key` ausente. | | 400 | `TRC000133` | `invoice.access_key` não é de um CT-e (modelo `57` ou `67` nas posições 21 e 22). | | 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. | | 409 | `TRC100026` | Já existe um direito creditório com esse `external_id` para o mesmo cedente na carteira do fundo. | | 400 | `TRC1000xx` | A validação financeira do ativo recusou o payload. Exemplo: `TRC100017` (409), o fundo não compra ativos vencidos. | O corpo de erro segue o formato abaixo: ```json { "title": "Already Exist This External Id", "description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3", "translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3", "code": "TRC000054" } ``` Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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 o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::caution Atenção O campo `external_id` do direito creditório identifica o ativo dentro do lote e não deve ser confundido com o `external_id` do lote. ::: :::tip Contrato descontado ou contrato parcelado? Pense num contrato de 5 parcelas como uma cartela com 5 cupons. - **[Contrato descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract)** (`discounted_contract`): você cede **cupons soltos**. Cada parcela é um ativo e vai numa requisição só dela. - **[Contrato parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract)** (`contract`): você cede **a cartela inteira**. O contrato é um ativo só e vai numa requisição, com as parcelas dentro. | | Contrato descontado | Contrato parcelado | |---|---|---| | O ativo é | uma parcela | o contrato inteiro | | Requisições por contrato | uma por parcela | uma | | O que você precisa ter na hora | só a parcela que vai ceder | valor e vencimento de todas as parcelas que vai ceder | | Preço (`total_purchase_value`) | de cada parcela | do contrato; a QI Tech reparte entre as parcelas | | Como as parcelas são cedidas | uma a uma, cada uma no lote que você quiser | juntas, no mesmo ativo | | Recusa na elegibilidade | sai só a parcela | sai o contrato inteiro | | [Boleto](/documentation/iaas/boletos/campos_do_boleto) | um por parcela | um por parcela | | [Pagamentos informados por você](/documentation/iaas/liquidacao_ativos/ativos/ativos) | todos os tipos de direito creditório, inclusive devolução, glosa e juros | só liquidação e amortização, do contrato ou de uma parcela | | Prorrogar o vencimento | sim, parcela a parcela (`asset_extension`) | não | | [Recompra](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset) | parcela a parcela | só o contrato inteiro | | [Relatório de estoque](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) | uma linha por parcela; a coluna de número do contrato traz o `order_number` | uma linha por parcela, com o número do contrato e o da parcela | **Qual combina com a sua operação:** - Vende parcelas aos poucos, escolhe quais vender ou precisa prorrogar, devolver ou recomprar parcelas soltas: **contrato descontado**. - Vende o contrato como uma unidade, com um preço só, e todas as parcelas são conhecidas na hora da cessão: **contrato parcelado**. O tipo não é escolhido no envio: ele vem da sua configuração de cessão, e o lote só aceita ativos desse tipo (`TRC000025`). Para ver o seu, consulte o `asset_type` na [listagem de configurações](/documentation/iaas/negociacao_recebiveis/listagem). Para mudar de tipo, fale com o time de integração. ::: ## Parcela e contrato Neste tipo de ativo, **cada parcela é um ativo**. Um contrato de 5 parcelas vira 5 inserções, cada uma com o seu `external_id`, o seu `face_value` (o valor daquela parcela), o seu `maturity_date` e o seu `installment_number`. Você não envia os valores das demais parcelas. O objeto `contract` identifica o contrato de origem e se repete, igual, em todas as parcelas do mesmo contrato: - `number` agrupa as parcelas. É por ele que você filtra os ativos de um contrato na [consulta de ativos](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos), e é ele que aparece no anexo do Termo de Cessão e identifica o ativo na recompra. Mantenha o mesmo valor em todas as parcelas. - `issue_date` é a data de emissão do contrato e passa a ser a data de emissão do ativo. - `total_face_value` e `number_of_installments` são informativos. Eles descrevem o contrato inteiro e não entram no preço, na elegibilidade nem no boleto. A QI Tech não confere esses valores contra as parcelas recebidas. As parcelas podem ser cedidas em lotes diferentes, na ordem que você quiser. Não é preciso ceder todas, nem ceder a primeira antes das outras. ## 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": "22.333.444/0001-81", "face_value": 1231.21, "maturity_date": "2025-12-10", "installment_number": 1, "borrower": { "name": "Natália Nascimento", "document_number": "969.698.790-03", "person_type": "natural_person", "email": "natalia.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": "CT958431587P01", "contract": { "number_of_installments": 5, "total_face_value": 6156.05, "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 (`000.000.000-00` ou `00.000.000/0000-00`) do originador que viabilizou a operação. Precisa estar cadastrado na QI Tech; caso contrário, devolve `TRC000019`. | | `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 | obrigatório | Número da parcela do contrato que este ativo representa. Sem ele, a inserção devolve `TRC000077`. | | `participant_control_number` | string | opcional | Seu número de controle do ativo. Máximo de 25 caracteres. Em cessão com boleto, vira o número de controle do participante do boleto e deve ser enviado sempre, com valor único. Veja [Do ativo ao boleto](/documentation/iaas/boletos/campos_do_boleto). | | `order_number` | string | opcional | Número do documento no seu sistema. Máximo de 45 caracteres. Em cessão com boleto, os 10 últimos caracteres viram o número do documento do boleto. | | `bankslip` | object | opcional | Dados do boleto, quando o nosso número é emitido por você. Consulte os [Atributos de `bankslip`](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata#atributos-de-bankslip) na página de Criação de Ativo — Duplicata. | | `delay` | object | opcional | Multa e juros por atraso do boleto. Consulte os [Atributos de `delay`](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte#atributos-de-delay) na página de Criação de Ativo — CTE. Sem ele, valem os encargos da configuração de cobrança do fundo. | | `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). Sem ele, a inserção devolve `TRC000075`. Não envie o objeto `invoice` neste tipo de ativo (`TRC000076`). | #### Atributos de `contract` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `number_of_installments` | integer | obrigatório | Quantidade total de parcelas do contrato, cedidas ou não. Informativo. | | `total_face_value` | number | obrigatório | Soma do valor de face de todas as parcelas do contrato, cedidas ou não. Informativo. Até 2 casas decimais. | | `number` | string | obrigatório | Número do contrato no seu sistema. Máximo de 50 caracteres. Use o mesmo valor em todas as parcelas do contrato. | | `issue_date` | string | obrigatório | Data de emissão do contrato no formato `YYYY-MM-DD`. Use a mesma data em todas as parcelas. | Veja em [Parcela e contrato](#parcela-e-contrato) como cada campo é usado. ## 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. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. | | 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. | | 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. | | 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). | | 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. | | 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. | | 400 | `TRC000077` | `installment_number` ausente. | | 400 | `TRC000075` | Objeto `contract` ausente. | | 400 | `TRC000076` | Objeto `invoice` enviado num ativo `discounted_contract`. | | 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. | | 409 | `TRC100026` | Já existe um direito creditório com esse `external_id` para o mesmo cedente na carteira do fundo. | | 400 | `TRC1000xx` | A validação financeira do ativo recusou o payload. Exemplo: `TRC100017` (409), o fundo não compra ativos vencidos. | O corpo de erro segue o formato abaixo: ```json { "title": "Already Exist This External Id", "description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3", "translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3", "code": "TRC000054" } ``` Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos 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 Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::info Diferença entre os tipos Ambos os tipos utilizam a mesma estrutura de request body. As diferenças: na **duplicata mercantil**, a chave de acesso da NF-e é obrigatória e, após a elegibilidade, o documento da duplicata é gerado pela QI Tech a partir desses dados; na **duplicata de serviços**, a chave é opcional e os documentos exigidos são os definidos na configuração de cessão. 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 o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::caution Atenção O campo `external_id` do direito creditório identifica o ativo dentro do lote 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": "22.333.444/0001-81", "maturity_date": "2023-12-10", "order_number": "18923619954796912", "face_value": 1023.01, "person_type": "natural_person", "borrower": { "name": "Natália Nascimento", "document_number": "969.698.790-03", "person_type": "natural_person", "email": "natalia.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": "35231011222333000181551239584315871861703272", "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 (`000.000.000-00` ou `00.000.000/0000-00`) do originador que viabilizou a operação. Precisa estar cadastrado na QI Tech; caso contrário, devolve `TRC000019`. | | `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. Sem ele, a inserção devolve `TRC000078`. Em cessão com boleto, os 10 últimos caracteres viram o número do documento do boleto. | | `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 25 caracteres alfanuméricos. Em cessão com boleto, vira o número de controle do participante do boleto e deve ser enviado sempre, com valor único. Veja [Do ativo ao boleto](/documentation/iaas/boletos/campos_do_boleto). | | `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_cte#atributos-de-delay) na página de Criação de Ativo — CTE. | | `invoice` | object | obrigatório | Dados da nota fiscal. Veja [Atributos de `invoice`](#atributos-de-invoice). Sem ele, a inserção devolve `TRC000075`. Não envie o objeto `contract` neste tipo de ativo (`TRC000076`). | #### 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 | condicional | Chave de acesso da NF-e, 44 caracteres. Obrigatória para `duplicata_mercantil` (`TRC000134`), e as posições 21 e 22 da chave precisam ser o modelo `55` (NF-e); outro modelo devolve `TRC000135`. Opcional para `duplicata_servicos`. | | `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 9 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. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. | | 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. | | 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. | | 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). | | 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. | | 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. | | 400 | `TRC000078` | `order_number` ausente. | | 400 | `TRC000075` | Objeto `invoice` ausente. | | 400 | `TRC000076` | Objeto `contract` enviado numa duplicata. | | 400 | `TRC000134` | `invoice.access_key` ausente numa `duplicata_mercantil`. | | 400 | `TRC000135` | `invoice.access_key` não é de uma NF-e (modelo `55` nas posições 21 e 22). | | 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. | | 409 | `TRC100026` | Já existe um direito creditório com esse `external_id` para o mesmo cedente na carteira do fundo. | | 400 | `TRC1000xx` | A validação financeira do ativo recusou o payload. Exemplo: `TRC100017` (409), o fundo não compra ativos vencidos. | O corpo de erro segue o formato abaixo: ```json { "title": "Already Exist This External Id", "description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3", "translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3", "code": "TRC000054" } ``` Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Próximos passos Após inserir o ativo, o fluxo continua com: 1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos 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, num lote de substituição, um ativo da carteira do fundo que será **recomprado** pelo cedente. O valor dos ativos recomprados é abatido do pagamento da cessão dos novos ativos do mesmo lote. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::info Lotes de substituição Este endpoint só aceita lotes criados numa configuração de cessão **de recompra** (`assignment_configuration_type` = `repurchase_configuration`). O lote precisa estar em `pending_assets_insertion`. Os ativos de recompra e os novos ativos podem ser inseridos em qualquer ordem enquanto o lote estiver aberto. Para encerrar a inserção, o lote precisa ter pelo menos um ativo de recompra, e o valor dos novos ativos não pode ser menor que o dos ativos recomprados — veja [Encerrar Inserção de Ativos](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). ::: :::tip Onde estou no fluxo? Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Insira também 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": "11.222.333/0001-81", "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 | O `external_id` com que o ativo foi originalmente cedido ao fundo. De 1 a 50 caracteres. | | `assignor_document_number` | string | obrigatório | CPF ou CNPJ, com pontuação, do cedente que cedeu o ativo ao fundo. | | `settlement_type` | string | obrigatório | Modalidade da recompra. Veja a tabela abaixo. | | `repurchase_value` | number | opcional | Valor de recompra, em reais. Mínimo `0.01`. Se omitido, vale o valor justo atual do ativo na carteira do fundo. | **Valores de `settlement_type`:** | Valor | Descrição | |---|---| | `asset_settlement` | Recompra total do ativo. | | `asset_amortization` | Recompra parcial (amortização) do ativo. | ## Response STATUS 201 ```json title="Response Body (assignment resumido)" { "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-4890-abcd-ef1234567890", "document_number": "11.222.333/0001-81", "name": "Cedente Exemplo Ltda" }, "status": "pending_assignment_validation", "assignment": { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "name": "CESSÃO #12345", "assignment_number": "12345", "assignment_date": "2024-04-01", "status": "pending_assets_insertion", "origin_type": "client" }, "repurchase_value": 1000.00, "contract_number": "000123", "maturity_date": "2024-09-30" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `repurchased_asset_key` | string | Identificador único da recompra gerado pela QI Tech (UUID). | | `asset_type` | string | Tipo do ativo recomprado. | | `asset_key` | string | Identificador do ativo na carteira do fundo (UUID). | | `external_id` | string | O `external_id` do ativo, conforme informado na requisição. | | `assignor` | object | Cedente que cedeu o ativo: `assignor_key`, `document_number` e `name`. | | `status` | string | Status da recompra. Veja a tabela abaixo. | | `assignment` | object | Lote de substituição, com a mesma estrutura da [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-da-resposta), sem `status_events`. | | `repurchase_value` | number | Valor de recompra, em reais. | | `contract_number` | string | Número do contrato do ativo recomprado, quando houver. | | `maturity_date` | string | Vencimento do ativo recomprado, no formato `YYYY-MM-DD`. | **Status da recompra:** | Status | Descrição | |---|---| | `pending_assignment_validation` | Recompra registrada, aguardando o lote seguir o fluxo. | | `sending_to_wallet` | Recompra sendo liquidada na carteira do fundo. | | `completed` | Recompra concluída. | | `discarded` | Recompra descartada junto com o lote. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `TRC000088` | A configuração de cessão do lote não é de recompra. | | 400 | `TRC000089` | O lote não está em `pending_assets_insertion`. | | 400 | `TRC000090` | O ativo não foi encontrado na carteira do fundo para esse cedente, tipo e `external_id`, ou não pode ser recomprado. | | 404 | `TRC000005` | Nenhum cedente com esse `assignor_document_number`. | | 404 | `TRC000012` | `asset_type` inexistente. | | 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Próximos passos 1. **[Inserção dos novos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** — adicione os ativos que substituirão os recomprados. 2. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos 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. --- # Envio do Lastro do Ativo URL: /documentation/iaas/negociacao_recebiveis/asset/documents Endpoint para enviar o lastro de um ativo do lote de cessão: os documentos que comprovam o direito creditório, como a CCB, a nota fiscal, o CT-e ou o contrato parcelado. O arquivo vai codificado em Base64, um documento por requisição, e cada ativo recebe o seu. :::caution Lastro não é Termo de Cessão O lastro é **por ativo** e quem envia é você, por este endpoint. O Termo de Cessão é **por lote**, gerado pela QI Tech depois da aprovação: você só o consulta, em [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). Para baixar o lastro já enviado de todos os ativos de uma cessão, use o relatório [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents). ::: :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::tip Onde estou no fluxo? Você pode enviar os documentos logo depois de inserir o ativo (status `pending_eligibility`) ou depois do [webhook](/documentation/iaas/negociacao_recebiveis/asset/webhooks) `pending_documentation`, que indica que o ativo foi aprovado na elegibilidade e aguarda documentação. Um ativo reprovado por documento (`denied` com `denied_by` = `document`) volta para `pending_documentation` quando recebe um novo documento. ::: :::info Quais documentos compõem o lastro? Os tipos exigidos são definidos por produto e vêm na [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). Só esses tipos são aceitos. - **Duplicata mercantil** (`duplicata_mercantil`): não é preciso enviar documento — a QI Tech gera o documento da duplicata a partir dos dados da nota fiscal. A chamada é aceita e devolve um `document_key`, mas nada é armazenado. - **Contrato parcelado** (`contract`): veja [Qual documento enviar no contrato parcelado](#qual-documento-enviar-no-contrato-parcelado). O ativo só avança para `pre_approved` depois que todos os documentos exigidos forem enviados e validados. ::: :::info Formato do documento Arquivo em **PDF**, **P7S** ou **XML**, codificado em Base64, com até 10 MB. Outros formatos são recusados com `TRC000166`. ::: ## 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 codificado em Base64 (PDF, P7S ou XML; até 10 MB). | **Valores de `document_type`** (aceitos só quando constam da configuração de cessão): | Valor | Descrição | |---|---| | `ccb` | Cédula de Crédito Bancário — ativos do tipo CCB. | | `duplicata_servicos` | Duplicata de serviços. | | `invoice` | Nota fiscal. | | `cte` | Conhecimento de Transporte Eletrônico. | | `discounted_contract` | Contrato descontado. | | `contract` | O próprio contrato parcelado cedido (o ativo), e não o contrato de cessão. | | `legal_fees_contract` | Contrato de honorários advocatícios. | | `check` | Cheque. | | `promissory_note` | Nota promissória. | | `disbursement_receipt` | Comprovante de desembolso. | | `vehicle_reservation_receipt` | Comprovante de reserva do veículo — operações com garantia de veículo. Documento **pós-cessão**. | ### Qual documento enviar no contrato parcelado No `document_type` `contract`, envie **o contrato que está sendo cedido**: o instrumento firmado entre o originador e o devedor, com as parcelas informadas na [criação do ativo](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract). Ele é o lastro do ativo. Não envie aqui o contrato de cessão nem o Termo de Cessão. Esses documentos formalizam a transferência dos ativos ao fundo: o contrato é firmado na [homologação do cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato) e o termo é gerado pela QI Tech para cada lote — veja [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). Cada ativo recebe **um PDF com o seu próprio contrato**. Em um lote com três contratos (A, B e C), envie três arquivos: o contrato A no ativo A, o B no ativo B e o C no ativo C. Não junte vários contratos no mesmo PDF. Um ativo aceita um único documento de cada tipo; enviar outro `contract` para o mesmo ativo devolve `TRC000035`, a menos que o anterior tenha sido reprovado. :::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` e é enviado o webhook `completed` do ativo, se você assina esse status. Também é possível acompanhar pela [consulta do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). 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 não está configurado para aquela cessão, inclusive um valor que não existe, devolve `TRC000032`. ::: ## 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). | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `TRC000032` | `document_type` não consta de `required_documents` nem de `after_assignment_required_documents` da configuração de cessão (inclui valores inexistentes). | | 400 | `TRC000034` | `document_b64` não é um Base64 válido. | | 400 | `TRC000155` | Arquivo acima de 10 MB. | | 400 | `TRC000166` | Formato não aceito. Formatos aceitos: PDF, P7S e XML. | | 404 | `TRC000020` | Nenhum ativo com esse `asset_external_id` no lote. | | 409 | `TRC000026` | O ativo não está num status que receba documentos (`pending_eligibility`, `pending_documentation`, `denied` por documento ou `pending_after_assignment_documentation`). | | 409 | `TRC000035` | O ativo já tem um documento desse tipo que não foi reprovado. | | 409 | `TRC000162` | O lote está `denied` ou `discarded`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## 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 foram inseridos para que o lote siga para a análise de elegibilidade. --- # Qual ativo enviar URL: /documentation/iaas/negociacao_recebiveis/asset/qual_ativo_enviar O tipo do ativo é definido pelo **documento que comprova o recebível**: uma cédula, uma nota fiscal, um CT-e ou um contrato. Encontre o seu na tabela e siga para a página de criação. ## Encontre o seu tipo | O que você tem | `asset_type` | Página de criação | |---|---|---| | Cédula de Crédito Bancário | `ccb` | [CCB](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) | | Cédula de Crédito Imobiliário estruturada | `structured_cci` | [CCB](/documentation/iaas/negociacao_recebiveis/asset/criacao_co), com o mesmo corpo | | Nota fiscal de venda de mercadoria (NF-e) | `duplicata_mercantil` | [Duplicatas](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata) | | Nota fiscal de prestação de serviço | `duplicata_servicos` | [Duplicatas](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata) | | Conhecimento de Transporte Eletrônico | `cte` | [CT-e](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte) | | Contrato com parcelas, cedido **parcela a parcela** | `discounted_contract` | [Contrato descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract) | | Contrato com parcelas, cedido **inteiro** | `contract` | [Contrato parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract) | Para **trocar** ativos que já estão no fundo por outros, não existe um tipo próprio: você usa um lote de substituição, com os ativos novos e os recomprados. Veja [Criação do Ativo — Substituição](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset). :::info O tipo vem da configuração de cessão Cada configuração de cessão tem um único `asset_type`, e os lotes dela só aceitam ativos desse tipo; um ativo de outro tipo é recusado com `TRC000025`. Consulte o tipo da sua na [listagem de configurações](/documentation/iaas/negociacao_recebiveis/listagem). Se a sua operação cede mais de um tipo, você precisa de uma configuração para cada. Para criar ou alterar uma configuração, fale com o time de integração. ::: ## Título ou operação parcelada Os tipos se dividem em dois grupos, e o grupo decide o que conta como **um ativo**. Elegibilidade, pagamento e recompra acontecem sempre por ativo. - **Um vencimento por ativo:** duplicatas, CT-e e contrato descontado. Cada ativo tem um valor e um vencimento. Uma nota com três vencimentos vira três ativos, cada um com o seu `external_id` e `installment_number`. - **Várias parcelas num ativo:** CCB, CCI estruturada e contrato parcelado. O ativo leva a lista de parcelas, e todas precisam ser informadas no envio. ## O que muda depois da cessão | | Duplicatas e CT-e | Contrato descontado | CCB e CCI estruturada | Contrato parcelado | |---|---|---|---|---| | O ativo é | o título | a parcela | a operação | o contrato | | Recusa na elegibilidade | tira o título | tira a parcela | tira a operação | tira o contrato | | Pagamentos informados | do título | da parcela | da operação ou de uma parcela | do contrato ou de uma parcela | | Prorrogar o vencimento | sim | sim | não | não | | Recompra | do título | da parcela | da operação ou de uma parcela | do contrato, total ou parcial; nunca de uma parcela | | Boleto na cessão | um por título | um por parcela | consulte o time de integração | um por parcela | Detalhes de cada linha em [liquidação de ativos](/documentation/iaas/liquidacao_ativos/ativos/ativos), [substituição](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset) e [do ativo ao boleto](/documentation/iaas/boletos/campos_do_boleto). O [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) não depende do tipo: os documentos exigidos vêm da sua configuração de cessão. A exceção é a duplicata mercantil, cujo documento é gerado pela QI Tech a partir da nota fiscal. :::tip Contrato descontado ou contrato parcelado? Os dois cedem contratos com parcelas. A diferença está em ceder uma parcela por vez ou o contrato inteiro, e isso muda o preço, a recompra, a prorrogação e o relatório de estoque. A comparação completa está em [Contrato descontado ou contrato parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract). ::: --- # 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. A resposta traz só os ativos que o seu perfil pode ver. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cessões | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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. | | `invoice_access_key` | string | — | Filtra pela chave de acesso da nota fiscal (duplicatas e CT-e). | | `invoice_number` | string | — | Filtra pelo número da nota fiscal. | | `invoice_serie` | string | — | Filtra pela série da nota fiscal. | | `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. | ```text title="Exemplo — listagem simples" GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?page=0&limit=10 ``` ```text 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 ``` :::caution Status inválido Se o valor enviado em `status` não corresponder a nenhum enumerador válido, a requisição retorna `TRC000163` (400). 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`). | | `ipoc_code` | string | Código IPOC do ativo, quando houver. | | `purchase_irr` | number | Taxa de compra do ativo, quando calculada. | | `contract_number` | string | Número do contrato, quando houver. | | `premiums` | array | Ágios do ativo (`premium_type`, `total_value`). Ausente quando não há. | | `deductions` | array | Deságios do ativo (`deduction_type`, `total_value`). Ausente quando não há. | | `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-reprovacao-denied_by). | | `denial_reason` | string | Descrição do motivo da reprovação. Presente apenas quando há detalhe da reprovação. | | `denial_translation` | string | Tradução do motivo, quando houver. | | `denial_description` | string | Descrição complementar do motivo, quando houver. | :::info Objetos aninhados Dependendo do tipo de ativo, a resposta inclui o objeto `credit_operation` (CCB), `discounted_credit_right` (duplicatas, CT-e, contratos descontados) ou `contract` (contratos parcelados), com os dados enviados na criação e o objeto `originator`. ::: ## 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`: ```text 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#eventos-por-status) — 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, com o histórico de status e os documentos enviados. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cessões | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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 de: | Campo | Tipo | Descrição | |---|---|---| | `status_events` | array | Histórico de status do ativo: `status`, `event_datetime` (UTC) e, em reprovações, `denial_reason` e `denial_metadata`. | | `documents` | array | Documentos enviados para o 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. | | `pending_after_assignment_documentation` | Ativo encarteirado, aguardando documentos pós-cessão. | | `pending_deferred_registry` | Aguardando o registro pós-cessão (registro diferido). | | `completed` | Ativo encarteirado na carteira do fundo. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `TRC000163` | Listagem: valor de `status` que não é um status de ativo. | | 400 | — | Listagem: `limit` acima de 100 ou `page` negativo (validação de parâmetro). | | 404 | `TRC000020` | Consulta individual: nenhum ativo com esse `asset_external_id` no lote. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Remoção de Ativos do Lote URL: /documentation/iaas/negociacao_recebiveis/asset/remocao_ativos Para retirar um ativo de um lote antes da aprovação, atualize o status do ativo para `denied`. O ativo deixa de compor o lote e seu valor sai do total da cessão. Se for preciso também **incluir** ativos, reabra o lote, ajuste os ativos e encerre a inserção de novo. :::info Quando cada perfil pode remover ativos O ativo precisa estar em `pending_eligibility`, `pending_invoice_validation`, `pending_documentation` ou `pre_approved`. O lote precisa estar num destes status: | Perfil | Status do lote em que pode remover ativos | |---|---| | Gestora | `pending_assets_insertion`, `completed_assets_insertion`, `pending_consultant_approval`, `pending_manager_approval` | | Consultoria | `pending_assets_insertion`, `completed_assets_insertion`, `pending_consultant_approval` | | Cedente | `pending_assets_insertion`, `completed_assets_insertion` | A gestora remove ativos de um lote em `pending_manager_approval` sem reabri-lo e depois [aprova](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) o lote. ::: ## Remover um ativo Faça uma requisição para cada ativo a ser removido. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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 | |---|---|---| | `assignment_external_id` | string | O `external_id` do lote. | | `asset_external_id` | string | O `external_id` do ativo que será removido. | ```json title="Request Body" { "asset_status": "denied", "denial_reason": { "reason_type": "manager", "denial_reason": "Sacado fora da política do fundo" } } ``` #### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_status` | string | obrigatório | Único valor aceito: `denied`. | | `denial_reason` | object | opcional | Motivo da remoção: `reason_type` (obrigatório dentro do objeto; use `manager`, `consultant` ou `assignor`) e `denial_reason` (texto livre). Sem esse objeto, a origem registrada é o seu perfil. | ### Response STATUS 200 A resposta é o ativo atualizado, no mesmo formato de cada item da [Consulta de Ativos do Lote](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos#atributos-de-cada-ativo-objetos-dentro-de-data), com o objeto da operação (`credit_operation`, `discounted_credit_right` ou `contract`). Trecho: ```json title="Response Body (trecho)" { "asset_key": "f4348106-01c4-4c59-a261-7c09db811c47", "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36", "total_purchase_value": 1231.21, "asset_type": "ccb", "status": "denied", "denied_by": "manager", "denial_reason": "Sacado fora da política do fundo" } ``` ## Reabrir e encerrar o lote Para incluir novos ativos num lote que já teve a inserção encerrada, reabra-o com `pending_assets_insertion`, insira ou remova os ativos e encerre de novo com `completed_assets_insertion`. Depois de encerrado, o lote passa outra vez pela elegibilidade e pelas aprovações. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: O lote pode ser reaberto quando está em `completed_assets_insertion`, `pending_consultant_approval` ou `pending_manager_approval`. A consultoria não reabre lotes em `pending_manager_approval`. ### 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 — reabrir" { "assignment_status": "pending_assets_insertion" } ``` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `assignment_status` | string | obrigatório | `pending_assets_insertion` para reabrir. Para encerrar de novo, envie `completed_assets_insertion` — veja [Encerrar Inserção de Ativos](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). | ### 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": 0, "assignment_total_value": 1234.99 } ``` | 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 | Sempre `0` nesta chamada. | | `assignment_total_value` | number | Último valor total calculado para o lote, em reais. É recalculado no próximo encerramento. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `TRC000086` | O ativo não está em `pending_eligibility`, `pending_invoice_validation`, `pending_documentation` ou `pre_approved` (por exemplo, já reprovado ou formalizado). | | 400 | `TRC000023` | `asset_status` diferente de `denied`, ou `assignment_status` com valor não aceito. | | 400 | `TRC000087` | O status do lote não permite que o seu perfil remova ativos ou reabra o lote (veja as tabelas acima). | | 400 | `TRC000024` | Reabertura pedida para um lote que não está em `completed_assets_insertion`, `pending_consultant_approval` ou `pending_manager_approval`. | | 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. | | 404 | `TRC000020` | Nenhum ativo com esse `asset_external_id` no lote. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. A configuração define **quais status** você recebe: só são enviados os eventos assinados nela. O webhook de criação (`asset_creation`) é enviado a quem assina o status `pending_eligibility`. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. Entrega, tentativas e assinatura: veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ::: ## 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. O diagrama mostra o caminho principal; a lista completa de status está em [Enumeradores de status do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos#enumeradores-de-status-do-ativo). ![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 envio, no formato `YYYY-MM-DDTHH:MM:SSZ`. | | `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. | | `operation_type` | string | Tipo de operação da configuração de cessão (ex.: `unsecured_credit`, `duplicata_mercantil`). | | `asset_payload` | object | Presente apenas no webhook de criação (`asset_creation`). Contém os dados do ativo conforme enviados na criação, com `purchase_irr` calculado dentro de `credit_operation` (CCB) ou `contract` (contratos). | | `denial_reason` | string | Presente em `denied` e `registry_denied`: origem da reprovação (os valores de [`denied_by`](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos#origens-de-reprovacao-denied_by)). | | `denial_metadata` | object | Presente em `denied` e `registry_denied` quando há detalhe — por exemplo, as regras de elegibilidade reprovadas ou o motivo informado na [remoção do ativo](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). | :::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", "operation_type": "unsecured_credit" }, "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", "operation_type": "unsecured_credit", "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": "969.698.790-03" }, "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": "22.333.444/0001-81" }, "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 a configuração de cessão exige documentos (duplicata mercantil e CT-e sempre passam por este status). Envie o lastro exigido pelo [Envio do Lastro do Ativo](/documentation/iaas/negociacao_recebiveis/asset/documents), se ainda não tiver enviado. ```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", "operation_type": "unsecured_credit" }, "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", "operation_type": "unsecured_credit" }, "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", "operation_type": "unsecured_credit" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Pendente Formalização STATUS pending_formalization Status em que o ativo foi formalizado (registrado, quando a configuração exige registro) e está apto a seguir no lote até o encarteiramento. Hoje esta passagem **não gera webhook**, mesmo que o status esteja assinado. Acompanhe pela [consulta do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos) ou pelo webhook do lote `waiting_assets_to_formalize`, nos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks#eventos-por-status). --- ### 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", "operation_type": "unsecured_credit" }, "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 elegibilidade, na validação de documentos ou da nota fiscal — ou [removido do lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). O webhook traz `denial_reason` e, quando houver, `denial_metadata`. Um ativo reprovado por documento volta para `pending_documentation` se você enviar um novo documento. ```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", "operation_type": "unsecured_credit" }, "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. O ativo não segue para a formalização nem para o encarteiramento; quando o lote é aprovado, ele passa a `denied`. O webhook traz `denial_reason` e, quando houver, `denial_metadata`; o detalhe também aparece na [consulta do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). ```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", "operation_type": "unsecured_credit" }, "webhook_type": "trade_receivables.asset_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Ativo Descartado STATUS discarded Status do ativo descartado junto com o lote — por exemplo, no fechamento contábil do fundo. Depois da assinatura do Termo de Cessão, os ativos reprovados (`denied`) do lote também passam para `discarded`. Hoje esta passagem **não gera webhook do ativo**, mesmo que o status esteja assinado. Acompanhe pela [consulta do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos); o descarte do lote é avisado pelo webhook `discarded` dos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks#eventos-por-status). Para retirar um ativo do lote, use a [remoção de ativos](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos), que leva o ativo a `denied`. --- # Aprovação do Lote URL: /documentation/iaas/negociacao_recebiveis/assignment/aprovacao Quando a configuração de cessão exige aprovação manual, o lote aprovado na elegibilidade fica aguardando a decisão da consultoria (`pending_consultant_approval`) e/ou da gestora (`pending_manager_approval`). Este endpoint registra essa decisão: aprovar ou reprovar o lote. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). O cedente acessa o mesmo endpoint pela `assignor-api` para [encerrar a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento), mas não pode enviar `approved` nem `denied` (`TRC000059`). ::: :::info Quem decide em cada status | Status do lote | Gestora | Consultoria | |---|---|---| | `pending_consultant_approval` | Pode reprovar (`denied`) ou reabrir (`pending_assets_insertion`). Não pode aprovar. | Pode aprovar, reprovar ou reabrir. | | `pending_manager_approval` | Pode aprovar, reprovar ou reabrir. | Não pode agir (`TRC000087`). | A mesma decisão pode ser tomada pelo [Portal do Gestor](https://portal-do-gestor.fundos.qitech.com.br/) ou pelo [Portal do Consultor](https://portal-do-consultor.fundos.qitech.com.br/). ::: :::tip Onde estou no fluxo? Este passo ocorre após a **elegibilidade do lote**. Você recebe um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com o status `pending_consultant_approval` ou `pending_manager_approval` indicando que o lote aguarda decisão. Para conferir a quantidade de ativos e o valor que serão aprovados, consulte o [Resumo de Ativos do Lote](/documentation/iaas/negociacao_recebiveis/assignment/resumo_ativos). Para retirar ativos antes de aprovar, veja [Remoção de Ativos do Lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). ::: ## 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", "number_of_approved_assets": 45, "assignment_total_value": 150000.00 } ``` ```json title="Request Body — Reprovação" { "assignment_status": "denied", "denial_reason": { "reason_type": "manager", "denial_reason": "Concentração por sacado acima do limite do fundo" } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `assignment_status` | string | obrigatório | `approved` aprova o lote; `denied` reprova. | | `disbursement_account_key` | string | opcional | Só na aprovação. Chave (UUID) da conta do cedente que receberá o pagamento, entre as contas cadastradas na homologação do cedente. Se omitida, é usada a conta marcada como padrão do cedente. Recusada quando o lote já tem conta de desembolso definida ou quando o contrato de cessão fixa outra conta. | | `transfer_type` | string | opcional | Só na aprovação. Forma de pagamento ao cedente: `pix` ou `wire_transfer`. Se omitida, vale a do lote ou da configuração de cessão. | | `number_of_approved_assets` | integer | opcional | Só na aprovação. Quantidade de ativos aprovados que você espera no lote. Se enviado, `assignment_total_value` também é obrigatório, e os dois são conferidos com o lote antes de aprovar. Use para garantir que aprova exatamente o que analisou. A conferência só é feita na aprovação que encerra a decisão: quando a aprovação da consultoria leva o lote para `pending_manager_approval`, os dois campos são ignorados. | | `assignment_total_value` | number | opcional | Só na aprovação. Valor total do lote que você espera, em reais. Enviado junto com `number_of_approved_assets`. | | `denial_reason` | object | opcional | Só na reprovação. Motivo da reprovação: `reason_type` (obrigatório dentro do objeto; use `manager` ou `consultant`) e `denial_reason` (texto livre). Fica registrado em `status_events[].denial_reason` e `status_events[].denial_metadata` na [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao). | ## Response STATUS 200 ```json title="Response Body — Aprovação" { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "status": "waiting_assets_to_formalize", "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" } ``` ### 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. Na aprovação: `pending_manager_approval` (consultoria aprovou e a gestora ainda precisa aprovar), `pending_assets_registry` (configurações com registro dos ativos) ou `waiting_assets_to_formalize`. Na reprovação: `denied`. | | `number_of_approved_assets` | integer | Só na aprovação. Quantidade de ativos aprovados no lote. É `0` quando o lote segue para a gestora. | | `assignment_total_value` | number | Só na aprovação. Valor total da cessão, em reais. | :::caution Aprovação final sem webhook Quando a aprovação leva o lote para `pending_assets_registry` ou `waiting_assets_to_formalize`, nenhum webhook do lote é enviado nessa transição: use o `status` da resposta. O próximo webhook do lote chega na etapa seguinte (termo de cessão, custódia ou pagamento). A transição para `pending_manager_approval` gera webhook normalmente. ::: Um lote reprovado (`denied`) não volta para a esteira pela API. No fechamento contábil do dia ele passa para `discarded`. ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `TRC000024` | O lote não está em um status que aceite essa decisão (por exemplo, já aprovado ou ainda em elegibilidade). Consulte a [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao). | | 400 | `TRC000087` | A gestora tentou aprovar um lote em `pending_consultant_approval`, ou a consultoria tentou agir num lote em `pending_manager_approval`. | | 400 | `TRC000059` | O cedente enviou `approved` ou `denied`. | | 400 | `TRC000095` | Foi enviado só um entre `number_of_approved_assets` e `assignment_total_value`. | | 400 | `TRC000096` | `assignment_total_value` não confere com o valor atual do lote. | | 400 | `TRC000097` | `number_of_approved_assets` não confere com a quantidade de ativos aprovados. | | 400 | `TRC000118` | Foi enviado `disbursement_account_key`, mas o lote já tem conta de desembolso definida. | | 400 | `TRC000149` | Os descontos ao cedente superam o limite permitido para o lote. | | 400 | `TRC000185` | `disbursement_account_key` diferente da conta fixada no contrato de cessão. | | 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. | | 404 | `TRC000116` | `disbursement_account_key` não corresponde a nenhuma conta do cedente. | | 422 | `TRC000186` | A conta de desembolso fixada no contrato de cessão não está mais ativa no cadastro do cedente. Contate o time de integração. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Próximos passos Após a aprovação, o fluxo continua automaticamente: 1. **Registro e formalização dos ativos** — conforme o tipo de registro da configuração de cessão. 2. **Termo de Cessão** — o termo é gerado e enviado para assinatura. Você recebe um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_assignment_term_signature`. O termo pode ser baixado em [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). 3. **Pagamento** — após a assinatura, o sistema realiza o pagamento ao cedente. Um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_payment` é enviado. 4. **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 Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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) ou na [Listagem de Configurações de Cessão](/documentation/iaas/negociacao_recebiveis/listagem). A configuração precisa estar com status `active`. Essas duas chaves compõem o caminho de todos os endpoints de cessão: ```text /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key} ``` ::: ## 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 | Identificador do lote no seu sistema, de 1 a 50 caracteres. É único em **toda** a plataforma, não só no fundo: use um UUID. É por ele que você consulta o lote e que os webhooks identificam o lote. | | `assignment_date` | string | opcional | Data da cessão, no formato `YYYY-MM-DD`. Não pode ser anterior à data contábil vigente do fundo. Se omitida, vale a data contábil vigente. Com data futura, o lote fica em `waiting_assignment_date` depois do encerramento da inserção e só entra na esteira nessa data. | | `payment_type` | string | opcional | Forma de pagamento ao cedente: `pix` ou `wire_transfer`. Se omitido, vale a forma definida na configuração de cessão. | | `disbursement` | object | opcional | Conta de desembolso específica deste lote, no campo `target_account` (veja abaixo). Se omitido, a conta é definida na aprovação. Recusado quando o contrato de cessão fixa uma única conta de desembolso. | | `assignor_discounts` | array | opcional | Descontos ao cedente, deduzidos do pagamento da cessão. Só aceito quando a configuração de cessão permite descontos (veja abaixo). | | `assignment_number` | number | opcional | Número do lote. Se omitido, a QI Tech gera um. | #### Atributos de `disbursement.target_account` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `account_branch` | string | obrigatório | Agência, com 4 dígitos. | | `account_number` | string | obrigatório | Número da conta, sem o dígito. | | `account_digit` | string | obrigatório | Dígito da conta (1 caractere). | | `account_type` | string | obrigatório | `checking_account` ou `escrow_account`. | | `financial_institution_ispb` | string | obrigatório | ISPB da instituição, com 8 dígitos. | | `financial_institution_code` | string | opcional | Código COMPE da instituição, com 3 dígitos. | | `owner.document_number` | string | obrigatório | CPF ou CNPJ do titular, com pontuação. | #### Atributos de cada item de `assignor_discounts` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `assignor_discount_type` | string | obrigatório | `expense_reimbursement` (reembolso de despesa) ou `others`. | | `total_value` | number | obrigatório | Valor do desconto, em reais. Mínimo `0.01`. | | `description` | string | obrigatório | Descrição do desconto, de 1 a 500 caracteres. | | `assignor_discount_key` | string | opcional | UUID v4 do desconto. Se omitido, a QI Tech gera um. | ## 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: `pending_assets_insertion`, pronto para receber ativos. | ## Reenvio e duplicidade Em caso de erro, reenvie a requisição. Duplicidade (`TRC000041`) significa que o lote já existe: consulte-o pela [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao) em vez de recriar. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `TRC000014` | A configuração de cessão não está ativa. | | 400 | `TRC000083` | `assignment_date` é anterior à data contábil vigente do fundo. Omita o campo ou envie a data contábil vigente. | | 400 | `TRC000136` | Foram enviados `assignor_discounts`, mas a configuração de cessão não permite descontos ao cedente. | | 400 | `TRC000185` | Foi enviado `disbursement`, mas o contrato de cessão fixa uma única conta de desembolso. | | 404 | `TRC000016` | A combinação de `fund_class_key` e `assignment_configuration_key` não corresponde a nenhuma configuração de cessão. | | 409 | `TRC000041` | Já existe um lote com esse `external_id`. Veja [Reenvio e duplicidade](#reenvio-e-duplicidade). | | 422 | `TRC000161` | A configuração exige registro dos ativos, mas não tem câmara de registro configurada. Contate o time de integração. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Próximos passos 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 do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos para cada ativo. O Termo de Cessão não é enviado por você: a QI Tech o gera depois da aprovação do lote. 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. --- # Termo de Cessão do Lote URL: /documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao O Termo de Cessão é o documento que formaliza a transferência dos ativos de **um lote** ao fundo. Quem gera o termo é a QI Tech, depois da aprovação do lote; você não envia nada nesta página, só consulta o termo e acompanha a assinatura. :::caution Termo de Cessão não é lastro São três documentos diferentes, cada um com o seu lugar: | Documento | De quê | Quem produz | Onde fica | |---|---|---|---| | **Contrato de cessão** | Do acordo entre cedente e fundo, que vale para todos os lotes | Firmado na homologação do cedente | [Consulta dos Documentos do contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos) | | **Termo de Cessão** | De cada lote | A QI Tech, após a aprovação do lote | Esta página | | **Lastro** | De cada ativo (CCB, nota fiscal, CT-e, contrato parcelado etc.) | Você envia | [Envio do Lastro do Ativo](/documentation/iaas/negociacao_recebiveis/asset/documents); para baixar depois, o relatório [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) | ::: ## Qual consulta usar O termo existe a partir do status `pending_assignment_term_signature` (veja o [webhook do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)). Antes disso, as consultas desta página devolvem `TRC000099`. Na [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao), `assignment_term_key` preenchido indica que o termo já foi gerado. | Você quer | Use | |---|---| | Baixar o termo (original e assinado) de um lote | [`GET .../assignment/{assignment_external_id}/assignment_term_link`](#link-do-termo-de-cessao) | | Baixar os termos de vários lotes, por data, status ou cedente | [`GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms`](#listagem-de-termos-de-cessao) | | Abrir a tela de assinatura do termo na CertifiQI (consultoria) | [`GET .../assignment/{assignment_external_id}/assignment_signature_url`](#link-de-assinatura) | | Receber o termo assinado sem consultar | Campo `signed_term_url` do [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) `pending_payment`, válido por 24 horas | ## Link do Termo de Cessão Recupera os links para download do Termo de Cessão — tanto a versão original quanto a versão assinada. O endpoint responde a partir do momento em que o Termo é gerado; antes disso devolve `TRC000099`. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cessões | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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 | URL pré-assinada para download do Termo de Cessão assinado. O arquivo só fica disponível depois que todas as partes assinarem. | :::info Observação As duas URLs são pré-assinadas e expiram em 1 hora. Gere um novo link chamando o endpoint novamente. O campo `signed_assignment_term_url` é sempre retornado, mas o arquivo só existe depois que o Termo de Cessão for assinado por todas as partes envolvidas. Antes disso, o acesso à URL retorna erro. Após a conclusão da assinatura, o lote avança para `pending_payment`, com [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks), ou para `pending_custody`, sem webhook, conforme a configuração de cessão. Nesse segundo caso, acompanhe pela [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao). ::: --- ## Listagem de Termos de Cessão Endpoint de consulta paginada que retorna os Termos de Cessão dos lotes de uma classe de fundo, com os links pré-assinados para download do termo original e do termo assinado. Utilize os filtros para buscar os termos por data da cessão, período, status ou por um lote específico. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cessões | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::info Endpoint por classe de fundo Assim como a [Listagem de Lotes](/documentation/iaas/negociacao_recebiveis/assignment/listagem), este endpoint utiliza apenas a `fund_class_key` na URL — não é necessário informar a `assignment_configuration_key`. Para obter o termo de um lote específico, informe o `external_id` do lote como filtro. ::: São retornados apenas os lotes que já possuem Termo de Cessão gerado e que pertencem ao agente autenticado (gestor ou consultor vinculado à classe de fundo). ### Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_terms 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_date` | string | opcional | Filtra por data da cessão no formato `YYYY-MM-DD`. | | `start_date` | string | opcional | Retorna lotes com data da cessão igual ou posterior à data informada, no formato `YYYY-MM-DD`. | | `end_date` | string | opcional | Retorna lotes com data da cessão igual ou anterior à data informada, no formato `YYYY-MM-DD`. | | `external_id` | string | opcional | Filtra pelo `external_id` informado na criação do lote. | | `assignment_key` | string | opcional | Filtra pela chave do lote (UUID). | | `assignment_status` | string | opcional | Filtra por um status específico do lote. | | `in_status` | string | opcional | Lista de status separados por vírgula. Retorna apenas lotes que estejam em um dos status informados. | | `not_in_status` | string | opcional | Lista de status separados por vírgula. Exclui os lotes nesses status. | | `assignor_document_number` | string | opcional | Filtra por número de documento (CPF/CNPJ) do cedente. Deve ser enviado **com pontuação** (ex.: `11.222.333/0001-81` ou `969.698.790-03`). | | `origin_type` | string | opcional | Filtra pela origem do lote (ex: `client`). | | `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`. | ```text title="Exemplo de chamada — termos de uma data" GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms?assignment_date=2024-04-01&page=0&limit=25 ``` ```text title="Exemplo de chamada — termo de um lote pelo external_id" GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms?external_id=931e9437-d025-41ab-bb53-6b94e10fd361 ``` ### 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_key": "3571e292-3a83-4011-904d-20ee963022ef", "assignment_number": "00012345", "assignment_date": "2024-04-01", "status": "completed", "assignment_term_key": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", "assignment_term_url": "https://storage.example.com/term/abc123.pdf", "signed_assignment_term_url": "https://storage.example.com/term/abc123_signed.pdf" } ], "limit": 25, "page": 0, "is_last_page": true } ``` #### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de Termos 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 termo (objetos dentro de `data`)** | 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_configuration_key` | string | Chave da configuração de cessão do lote (UUID). | | `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 os [enumeradores de status do lote](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote). | | `assignment_term_key` | string | Chave do Termo de Cessão (UUID). | | `assignment_term_url` | string | URL pré-assinada para download do Termo de Cessão original. | | `signed_assignment_term_url` | string | URL pré-assinada para download do Termo de Cessão assinado. O arquivo só fica disponível depois que todas as partes assinarem. | :::info Observação As URLs são pré-assinadas e expiram em 1 hora. Para obter novos links, chame o endpoint novamente. Os lotes são ordenados do mais recente para o mais antigo. Lotes que ainda não tiveram o Termo de Cessão gerado não aparecem na listagem. ::: --- ## 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. O endpoint responde a partir do momento em que o Termo é gerado. Não está disponível quando a assinatura é feita pela QCertifica ou quando a configuração de cessão dispensa assinatura (`TRC000131`). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Consultoria | `consultant-api` | Ler Cessões | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### 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 em `pending_send_to_signature` ou `pending_assignment_term_signature`. Depois da assinatura por todas as partes, passa a apontar para o Termo de Cessão assinado. A URL é pré-assinada e expira em 1 hora. ::: ## Erros | Status | Código | Endpoint | Quando acontece | |---|---|---|---| | 400 | `TRC000099` | Link do termo, link de assinatura | O Termo de Cessão do lote ainda não foi gerado. | | 400 | `TRC000131` | Link de assinatura | A configuração de cessão não usa assinatura eletrônica com link (por exemplo, assinatura pela QCertifica ou sem assinatura), ou o link ainda não está disponível. | | 400 | — | Listagem de termos | `limit` acima de 155 ou `page` negativo (validação de parâmetro). | | 404 | `TRC000018` | Link do termo, link de assinatura | Nenhum lote com esse `external_id` nesta configuração de cessão. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 o lote não recebe novos ativos. Quando todos os ativos estiverem com a análise individual concluída (`pre_approved`, `pending_formalization`, `denied` ou `registry_denied`), a elegibilidade do lote como um todo é avaliada automaticamente. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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 aguarda até que todos estejam com a análise concluída 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 o lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) de cada ativo ::: ## 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 | Para encerrar a inserção de ativos, envie `completed_assets_insertion`. O lote precisa estar em `pending_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": 15230.75 } ``` ### 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`, ou `waiting_assignment_date` quando a `assignment_date` do lote é posterior à data contábil do fundo. Nesse caso o lote passa para `completed_assets_insertion` na data da cessão. Essa passagem não gera webhook. | | `number_of_approved_assets` | integer | Sempre `0` nesta chamada: a contagem de ativos aprovados só é feita na aprovação. | | `assignment_total_value` | number | Soma do `total_purchase_value` dos ativos não reprovados (`denied`/`registry_denied`), em reais. Em lotes de substituição, já descontado o valor dos ativos recomprados. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | `TRC000023` | `assignment_status` com valor não aceito. Os valores aceitos neste endpoint são `completed_assets_insertion`, `pending_assets_insertion`, `approved` e `denied`. | | 400 | `TRC000024` | O lote não está em `pending_assets_insertion`. | | 400 | `TRC000042` | O lote não tem nenhum ativo em análise ou aprovado. [Insira pelo menos um ativo](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) antes de encerrar. | | 400 | `TRC000160` | Todos os ativos do lote foram reprovados. | | 400 | `TRC000092` | Lote de substituição: o valor dos novos ativos é menor que o valor dos ativos recomprados. | | 400 | `TRC000093` | Lote de substituição sem nenhum [ativo de recompra](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset). | | 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). ## Próximos passos Após encerrar a inserção, o fluxo segue automaticamente: 1. **Elegibilidade dos ativos** — cada ativo é analisado individualmente. Você recebe [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 é avaliada. O resultado é informado via [webhook do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). 3. **[Aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)** — se a configuração de cessão exigir, a consultoria e/ou a gestora aprovam o lote. --- # 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 classe de fundo, de todas as configurações de cessão. Use os filtros para buscar lotes por data, status, cedente ou identificador. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cessões | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::info Endpoint por classe de fundo Diferente dos demais endpoints de lote, este usa apenas a `fund_class_key` na URL. A resposta traz só os lotes que o seu perfil pode ver. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignments MÉTODO GET ### Query params Todos os filtros são opcionais e podem ser combinados. | Parâmetro | Tipo | Descrição | |---|---|---| | `assignment_date` | string | Data da cessão, no formato `YYYY-MM-DD`. | | `start_date` | string | Lotes com data da cessão igual ou posterior, no formato `YYYY-MM-DD`. | | `end_date` | string | Lotes com data da cessão igual ou anterior, no formato `YYYY-MM-DD`. | | `assignment_status` | string | Um status do lote. | | `in_status` | string | Lista de status separados por vírgula. Retorna só os lotes em um deles. | | `not_in_status` | string | Lista de status separados por vírgula. Exclui os lotes nesses status. | | `assignor_document_number` | string | CPF/CNPJ do cedente, **com pontuação** (ex.: `11.222.333/0001-81` ou `969.698.790-03`). | | `external_id` | string | O `external_id` do lote. | | `assignment_key` | string | A chave do lote (UUID). | | `origin_type` | string | Origem do lote (ex.: `client`). | | `page` | integer | Número da página (começa em 0). Padrão: `0`. | | `limit` | integer | Registros por página. Padrão: `25`. Máximo: `155`. | ```text 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 (objetos de data resumidos)" { "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", "asset_type": "ccb" }, "assignment_number": "12345", "assignment_date": "2024-04-01", "status": "completed", "assignment_term_key": "b1c2d3e4-f5a6-4890-abcd-ef1234567890", "disbursement": null, "origin_type": "client", "payment_type": "pix", "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 | Lotes encontrados, do mais recente para o mais antigo. | | `page` | integer | Número da página atual. | | `limit` | integer | Registros por página. | | `is_last_page` | boolean | `true` na última página de resultados. | Cada objeto de `data` tem a mesma estrutura da [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-da-resposta) — inclusive o objeto `assignment_configuration` completo —, exceto `status_events`, que não vem na listagem. ## Enumeradores de status do lote | Status | Descrição | |---|---| | `created` | Lote criado; passa imediatamente para `pending_assets_insertion`. | | `pending_assets_insertion` | Aguardando inserção de ativos. | | `waiting_assignment_date` | Inserção encerrada, aguardando a data da cessão (lote com `assignment_date` futura). | | `completed_assets_insertion` | Inserção encerrada, aguardando a análise individual dos ativos terminar. | | `pending_eligibility` | Em análise de elegibilidade do lote. | | `pending_consultant_approval` | Aguardando aprovação da consultoria. | | `pending_manager_approval` | Aguardando aprovação da gestora. | | `pending_assets_registry` | Aguardando o registro dos ativos. | | `waiting_assets_to_formalize` | Aguardando a formalização dos ativos aprovados. | | `pending_assignment_term` | Gerando o Termo de Cessão. | | `pending_send_to_signature` | Termo de Cessão gerado, sendo enviado para assinatura. | | `pending_assignment_term_signature` | Aguardando assinatura do Termo de Cessão. | | `pending_assignment_term_validation` | Termo de Cessão em validação. | | `pending_custody` | Aguardando custódia. | | `pending_payment` | Aguardando pagamento ao cedente. | | `pending_assets_wallet_inclusion` | Aguardando encarteiramento dos ativos. | | `pending_after_assignment_documentation` | Ativos encarteirados; aguardando documentos pós-cessão. | | `pending_after_assignment_registry` | Ativos encarteirados; aguardando o registro pós-cessão (registro diferido). | | `waiting_after_assignment_registry` | Registro pós-cessão enviado, aguardando retorno. | | `completed` | Cessão finalizada com sucesso. | | `denied` | Lote reprovado (elegibilidade, registro ou decisão da consultoria/gestora). | | `discarded` | Lote descartado, por exemplo no fechamento contábil do fundo. | Quais desses status geram webhook está em [Webhooks do Lote de Cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | — | `limit` acima de 155 ou `page` negativo (validação de parâmetro). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 a configuração de cessão, o status atual, o histórico de eventos, os dados de desembolso e os valores financeiros. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cessões | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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 já foi aprovado ou se o pagamento foi realizado. Também é a consulta a fazer quando a criação devolve duplicidade (`TRC000041`). ::: ## 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 **Response Body** ```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": "5f0e3a4c-2b7d-4c1e-9a8f-0d6b1c2e3f40", "assignment_configuration_name": "Config CCB Fundo Alpha", "assignment_contract_key": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "registry_type": "internal_registry", "asset_type": "ccb", "fund_class": { "fund_class_key": "f1a2b3c4-d5e6-4890-abcd-ef1234567890", "name": "Fundo Alpha FIDC", "document_number": "11.222.333/0001-81", "accounting_date": "2024-04-01", "manager": { "manager_key": "e1f2a3b4-c5d6-4890-abcd-ef1234567890", "document_number": "22.222.222/0001-91", "manager_name": "Gestora Exemplo S.A." } }, "assignor": { "assignor_key": "c1d2e3f4-a5b6-4890-abcd-ef1234567890", "document_number": "33.333.333/0001-91", "name": "Cedente Exemplo Ltda" }, "assignment_reports": { "send_reports": false }, "assignment_configuration_type": "default_configuration", "status": "active", "consultant_decision_type": "manual_approval", "manager_decision_type": "manual_approval", "asset_fees": null, "payment_type": "pix", "custody_type": "internal", "required_documents": ["ccb"], "after_assignment_required_documents": [], "certifier": "certifiqi", "disbursement_account_policy": "all_assignor_accounts", "consultant": { "consultant_key": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d", "document_number": "44.444.444/0001-91", "name": "Consultoria Exemplo Ltda" }, "operation_type": "unsecured_credit", "originator_bonds": [ { "originator": { "originator_key": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "document_number": "33.333.333/0001-91", "name": "Cedente Exemplo Ltda" } } ] }, "assignment_number": "12345", "assignment_date": "2024-04-01", "status": "completed", "assignment_term_key": "b1c2d3e4-f5a6-4890-abcd-ef1234567890", "disbursement": { "target_account": { "account_key": "d1e2f3a4-b5c6-4890-abcd-ef1234567890", "account_type": "checking_account", "account_branch": "0001", "account_number": "12345", "account_digit": "4", "financial_institution_code": "341", "financial_institution_ispb": "60701190", "owner": { "document_number": "33.333.333/0001-91" }, "payment_type": "pix" } }, "origin_type": "client", "payment_type": "pix", "assignment_total_value": 150000.00, "assignment_irr": 0.0215, "status_events": [ { "status": "pending_assets_insertion", "event_datetime": "2024-04-01 10:00:00.123456", "selected_agent": { "AGENT-TYPE": "assignor", "AGENT-KEY": "c1d2e3f4-a5b6-4890-abcd-ef1234567890", "AGENT-USER": "usuario@exemplo.com" } }, { "status": "completed_assets_insertion", "event_datetime": "2024-04-01 11:30:00.654321" }, { "status": "completed", "event_datetime": "2024-04-01 16:00:00.000000" } ] } ``` ### 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 do lote de cessão. | | `assignment_date` | string | Data da cessão no formato `YYYY-MM-DD`. | | `status` | string | Status atual do lote. Veja os [status do lote](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote). | | `origin_type` | string | Origem do lote. Lotes criados pela API de integração têm `client`. | | `payment_type` | string \| null | Forma de pagamento ao cedente: `pix` ou `wire_transfer`. Vem do lote ou, se não informada nele, da configuração de cessão. | | `assignment_term_key` | string \| null | Chave do Termo de Cessão (UUID). Preenchida depois que o termo é gerado; a partir daí, baixe-o em [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). | | `assignment_total_value` | number | Valor total da cessão em reais. Ausente até o primeiro cálculo, feito no encerramento da inserção. | | `assignment_irr` | number | Taxa interna de retorno do lote. Ausente enquanto não calculada. | | `assignment_configuration` | object | Configuração de cessão do lote. Os campos estão em [Listagem de Configurações de Cessão](/documentation/iaas/negociacao_recebiveis/listagem#atributos-de-cada-configuracao-objetos-dentro-de-data). | | `disbursement` | object \| null | Conta de desembolso do lote, em `target_account`, com os campos da conta e a `payment_type` usada. `null` enquanto não definida. | | `assignor_discounts` | array | Descontos ao cedente. Presente apenas quando o lote tem descontos. Veja tabela abaixo. | | `status_events` | array | Histórico de transições de status do lote. Veja tabela abaixo. | #### Atributos de `assignor_discounts` | Campo | Tipo | Descrição | |---|---|---| | `assignor_discount_key` | string | Chave única do desconto (UUID). | | `assignor_discount_type` | string | `expense_reimbursement` ou `others`. | | `status` | string | `created`, `pending_execution`, `executed` ou `rejected`. | | `total_value` | number | Valor do desconto em reais. | | `description` | string | Descrição do desconto. | #### Atributos de `status_events` | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Status para o qual o lote foi. | | `event_datetime` | string | Data e hora da transição, em UTC, no formato `YYYY-MM-DD HH:MM:SS.ffffff`. | | `selected_agent` | object | Agente que fez a transição (`AGENT-TYPE`, `AGENT-KEY` e `AGENT-USER`). Ausente em transições automáticas. | | `denial_reason` | string | Presente em `denied` e `discarded`: origem da reprovação ou do descarte (`eligibility`, `registry`, `accounting_close`, `payment`, `manager`, `asset_documents`, `manual`, `consultant` ou `inconsistency`). | | `denial_metadata` | object | Detalhe da reprovação, quando houver — por exemplo, as regras de elegibilidade reprovadas ou o `denial_reason` enviado na [aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao). | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `TRC000016` | A combinação de `fund_class_key` e `assignment_configuration_key` não corresponde a nenhuma configuração de cessão. | | 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Resumo de ativos do lote URL: /documentation/iaas/negociacao_recebiveis/assignment/resumo_ativos Retorna a quantidade de ativos de um lote de cessão, separada entre aprovados e reprovados, e o valor total do lote. São os mesmos números conferidos na [aprovação do lote](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cessões | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::tip Quando utilizar O [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) `pending_consultant_approval` ou `pending_manager_approval` informa só a mudança de status do lote. Consulte este endpoint nesse momento para saber quantos ativos o lote tem, por exemplo para confirmar que todos os ativos esperados chegaram, sem precisar paginar a [listagem de ativos](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Os valores de `number_of_approved_assets` e `assignment_total_value` podem ser enviados sem alteração no corpo da aprovação. ::: ## Request ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assets_summary 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_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "assignment_status": "pending_manager_approval", "number_of_assets": 198, "number_of_approved_assets": 195, "number_of_denied_assets": 3, "assignment_total_value": 1234567.89 } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `assignment_external_id` | string | O `external_id` do lote informado na criação. | | `assignment_status` | string | Status atual do lote. Veja os [status do lote](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote). | | `number_of_assets` | integer | Quantidade total de ativos do lote, em qualquer status. Inclui os ativos ainda em análise. | | `number_of_approved_assets` | integer | Ativos em `pre_approved` ou `pending_formalization`. É o número conferido em `number_of_approved_assets` na aprovação. | | `number_of_denied_assets` | integer | Ativos em `denied` ou `registry_denied`. | | `assignment_total_value` | number | Valor total do lote, em reais: soma do valor de compra dos ativos não reprovados, descontado o valor dos ativos recomprados no lote. É o valor conferido em `assignment_total_value` na aprovação. | `number_of_assets` pode ser maior que a soma de aprovados e reprovados enquanto houver ativos em análise. Quando o lote chega em `pending_consultant_approval` ou `pending_manager_approval`, a análise de todos os ativos já terminou e os números ficam estáveis até a decisão, salvo se ativos forem [removidos do lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). :::caution Envie o valor sem arredondar A aprovação compara `assignment_total_value` com o valor do lote de forma exata. Envie o número como ele veio na resposta: um valor arredondado ou truncado devolve `TRC000096`. ::: ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `TRC000016` | A combinação de `fund_class_key` e `assignment_configuration_key` não corresponde a nenhuma configuração de cessão. | | 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 do Lastro Para cada ativo inserido, envie o lastro exigido pelo produto: os documentos que comprovam o ativo (CCB, contrato, nota fiscal etc.) — pode ser logo após a inserção. O ativo só prossegue na esteira após todos os documentos exigidos serem enviados. **[Acessar documentação do envio do lastro](/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 Após a elegibilidade do lote, se a configuração de cessão exigir, a consultoria e/ou a gestora aprovam ou reprovam o lote. Com aprovação automática, nenhuma ação é necessária. **[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). Para baixar o termo, original ou assinado, ou abrir o link de assinatura, veja [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). --- # 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 mudanças de status do lote. Todos têm o tipo `trade_receivables.assignment_status_change` e identificam o lote pelo `assignment_external_id` informado na criação. :::info Configuração de webhooks Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. A configuração define **quais status** você recebe: só são enviados os eventos assinados nela. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. Entrega, tentativas e assinatura: veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ::: ## Fluxo de status do lote ![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 com webhook · **tracejado** = status sem webhook · **verde** = cessão concluída · **vermelho** = status final de recusa ou descarte._ A lista completa de status, inclusive os que não geram webhook, está em [Enumeradores de status do lote](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote). ## Estrutura do webhook | Campo | Tipo | Descrição | |---|---|---| | `webhook_type` | string | Sempre `trade_receivables.assignment_status_change`. | | `webhook_datetime` | string | Data e hora do envio, no formato `YYYY-MM-DDTHH:MM:SSZ`. | | `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 | Configuração de cessão à qual o lote pertence — a mesma chave usada nas URLs dos endpoints. Como um cedente pode ter mais de uma configuração ativa, ela indica sob qual acordo o evento aconteceu. | | `fund_class_key` | string | Classe do fundo do lote. | | `signed_term_url` | string | Só no webhook `pending_payment`, quando o Termo de Cessão foi assinado eletronicamente: URL pré-assinada para download do termo assinado, válida por 24 horas. Depois disso, gere um novo link em [Termo de Cessão do Lote](/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_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" } ``` ## Eventos por status O corpo é sempre o mesmo; muda o `assignment_new_status`. | `assignment_new_status` | Quando é enviado | |---|---| | `pending_assets_insertion` | Lote criado e pronto para receber ativos. Também quando um lote é reaberto. | | `completed_assets_insertion` | Inserção de ativos encerrada. Também quando o lote volta do registro com ativos recusados pela registradora. Não é enviado para lote com `assignment_date` futura: ele passa por `waiting_assignment_date` e entra em `completed_assets_insertion` na data da cessão, sem webhook. | | `pending_eligibility` | Todos os ativos foram analisados e o lote entrou na análise de elegibilidade. | | `pending_consultant_approval` | Lote aprovado na elegibilidade, aguardando a [aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) da consultoria. | | `pending_manager_approval` | Lote aprovado na elegibilidade (e pela consultoria, quando aplicável), aguardando a [aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) da gestora. | | `pending_assets_registry` | Lote aprovado automaticamente, com ativos sendo registrados. | | `waiting_assets_to_formalize` | Ativos registrados (ou lote aprovado automaticamente sem registro), aguardando formalização. | | `pending_assignment_term` | Termo de Cessão sendo gerado. | | `pending_assignment_term_signature` | Termo de Cessão enviado para assinatura. A partir daqui o termo pode ser baixado em [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). | | `pending_custody` | Aguardando custódia, conforme a configuração de cessão. Enviado só quando a configuração dispensa a assinatura do termo; depois da assinatura, a passagem para `pending_custody` não gera webhook. | | `pending_payment` | Termo assinado (ou dispensado) e pagamento ao cedente em processamento. Pode trazer `signed_term_url`. | | `pending_assets_wallet_inclusion` | Pagamento confirmado; ativos sendo encarteirados. | | `waiting_after_assignment_registry` | Registro pós-cessão (registro diferido) enviado à registradora. | | `completed` | Ativos encarteirados na carteira do fundo — cessão concluída. Em configurações com registro diferido, é enviado no encarteiramento, antes do registro pós-cessão. | | `denied` | Lote reprovado: na elegibilidade, por todos os ativos terem sido reprovados, no registro, ou pela consultoria/gestora. Não volta para a esteira pela API. | | `discarded` | Lote descartado — por exemplo, no fechamento contábil do fundo, quando ainda não tinha sido pago. Lotes `denied` também são descartados nesse momento. | :::caution Transições sem webhook - A aprovação final feita pela API ou pelo portal (que leva o lote para `pending_assets_registry` ou `waiting_assets_to_formalize`) **não** gera webhook nessa transição. Use o `status` da resposta da [aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao). - `waiting_assignment_date`, `pending_send_to_signature`, `pending_assignment_term_validation` e `pending_after_assignment_documentation` não geram webhook. - A passagem para `pending_custody` depois da assinatura do Termo de Cessão. Para conferir o status a qualquer momento, use a [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao). ::: --- # 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ê pode receber — só chegam os status assinados na sua configuração de webhook. ::: {` .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) Consultoria / Gestora 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 do Lastro Agente Integrador Envia o lastro de cada ativo: os documentos que o comprovam (PDF, P7S ou XML em Base64). Duplicatas mercantis não exigem documentos. Não é aqui que entra o Termo de Cessão (etapa 7). Lote: pending_assets_insertion Ativo: pending_eligibility POST /trade_receivables/.../asset/{asset_external_id}/document Os documentos podem ser enviados logo após a inserção do ativo ou depois do webhook pending_documentation (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: pending_documentation / pre_approved / denied Webhook: asset_status_change Ativo aprovado pre_approved O ativo foi aprovado na elegibilidade; se o produto exige documentos, passa por pending_documentation antes. 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_consultant_approval / pending_manager_approval / denied Webhook: assignment_status_change Lote elegível pending_manager_approval O lote aguarda a aprovação da consultoria e/ou da gestora (passo 6). Se a configuração prevê aprovação automática, segue direto para o registro e a formalização dos ativos. Lote reprovado denied O lote foi reprovado pelas regras de elegibilidade do fundo, ou todos os ativos foram reprovados. 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 da Consultoria e/ou da Gestora Consultoria / Gestora Quando a configuração exige aprovação manual, a consultoria e/ou a gestora aprovam ou reprovam o lote (via API ou pelo portal). Aprovado, o lote segue para o registro e a formalização dos ativos e, depois, para o Termo de Cessão. Lote: pending_assets_registry / waiting_assets_to_formalize PUT /trade_receivables/.../assignment/{assignment_external_id} Envie {"assignment_status": "approved"} ou "denied" . A aprovação final não gera webhook: use o status da resposta. O próximo webhook do lote chega com o Termo de Cessão ( pending_assignment_term_signature ). Ver documentação completa → 7 Termo de Cessão do Lote QI Tech A QI Tech gera o Termo de Cessão do lote e o encaminha para assinatura. Todas as partes relacionadas precisam assinar o termo para que o fluxo prossiga. O integrador não envia o termo: só o consulta, a partir de pending_assignment_term_signature . Lote: pending_payment Webhook: assignment_status_change GET /trade_receivables/.../assignment/{assignment_external_id}/assignment_term_link GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms Consulte o Termo de Cessão (original e assinado) de um lote ou liste os termos da classe de fundo por data. 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 é feito automaticamente ao cedente na conta de desembolso definida para o lote. Lote: pending_assets_wallet_inclusion Webhook: assignment_status_change O valor total é a soma dos total_purchase_value dos ativos não reprovados; em lotes de substituição, descontado o valor dos ativos recomprados. 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` | `pending_documentation` / `pre_approved` | Ativo aprovado na elegibilidade (passo 5a) | Se `pending_documentation`, [enviar o lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) que falta. | | 3 | `asset_status_change` | `denied` | Ativo reprovado na elegibilidade (passo 5a) | Nenhuma — ativo não segue adiante. | | 4 | `assignment_status_change` | `pending_consultant_approval` / `pending_manager_approval` | Lote aprovado na elegibilidade (passo 5b) | [Aprovar ou reprovar](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao), se você é a consultoria ou a gestora. | | 5 | `assignment_status_change` | `denied` | Lote reprovado na elegibilidade (passo 5b) | Nenhuma — fluxo encerrado. | | 6 | `assignment_status_change` | `pending_assignment_term_signature` | Termo de Cessão enviado para assinatura (passo 7) | Opcional: [baixar o Termo de Cessão do lote](/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` | Fechamento contábil do fundo, para lotes ainda não pagos ou reprovados | 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). Lá também estão os status intermediários que não aparecem nesta tabela. ::: --- # 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 DTVM. 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 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, CT-e, cheques e notas promissórias, ou **CSV** para CCB, honorários advocatícios e contratos parcelados | Portal do gestor/consultor; API da gestora | :::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. Não sabe qual tipo enviar? Em [Qual ativo enviar](/documentation/iaas/negociacao_recebiveis/asset/qual_ativo_enviar) você encontra o tipo de cada recebível e o que muda entre eles depois da cessão, inclusive a diferença entre contrato descontado e contrato parcelado. **[Acessar documentação da inserção de ativos](/documentation/iaas/negociacao_recebiveis/asset/qual_ativo_enviar)** ### 3. Envio do Lastro Para cada ativo inserido, envie o lastro exigido pelo produto: os documentos que comprovam o ativo (CCB, contrato, nota fiscal etc.). O ativo só prossegue na esteira após todos os documentos exigidos serem enviados. Não confunda com o Termo de Cessão, que é do lote e gerado pela QI Tech no passo 6. **[Acessar documentação do envio do lastro](/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 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). Para baixar o termo, original ou assinado, ou abrir o link de assinatura, veja [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). ## Lotes de substituição O fluxo de substituição segue as mesmas etapas do fluxo de cessão, com um passo a mais: inserir, no mesmo lote, os ativos que serão **recomprados** pelo cedente — [Inserção de Ativo para Recompra](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset). Recompras e novos ativos podem entrar em qualquer ordem enquanto o lote estiver aberto; para encerrar a inserção, o lote precisa de ao menos um ativo de recompra, e o valor dos novos ativos não pode ser menor que o dos recomprados. --- # 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 de uma classe de fundo. Cada configuração representa o acordo entre o fundo cessionário e um cedente: tipo de ativo aceito, regras de registro, aprovação, pagamento e documentos exigidos. A `assignment_configuration_key` de cada configuração compõe o caminho dos endpoints de cessão. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Cessões | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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 Todos os filtros são opcionais e podem ser combinados. | Parâmetro | Tipo | Descrição | |---|---|---| | `assignment_contract_key` | string | Chave do contrato de cessão que originou a configuração (UUID). | | `asset_type` | string | Tipo de ativo aceito (ex.: `ccb`, `duplicata_mercantil`, `duplicata_servicos`). | | `assignor_document_number` | string | CPF/CNPJ do cedente, **com pontuação** (ex.: `11.222.333/0001-81` ou `969.698.790-03`). | | `assignment_configuration_type` | string | `default_configuration` (cessão) ou `repurchase_configuration` (substituição com recompra). | | `has_assignor_coobligation` | boolean | Configurações com ou sem coobrigação do cedente. | | `has_bankslip` | boolean | Configurações com ou sem cobrança por boleto. | | `page` | integer | Número da página (começa em 0). Padrão: `0`. | | `limit` | integer | Registros por página. Padrão: `25`. Máximo: `155`. | ```text title="Exemplo de chamada" GET /trade_receivables/fund_class/{fund_class_key}/assignment_configurations?asset_type=ccb&assignor_document_number=11.222.333/0001-81&page=0&limit=10 ``` ## Response STATUS 200 **Response Body** ```json title="Response Body" { "data": [ { "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef", "validation_configuration_key": "5f0e3a4c-2b7d-4c1e-9a8f-0d6b1c2e3f40", "assignment_configuration_name": "Config CCB Fundo Alpha", "assignment_contract_key": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "registry_type": "internal_registry", "asset_type": "ccb", "fund_class": { "fund_class_key": "f1a2b3c4-d5e6-4890-abcd-ef1234567890", "name": "Fundo Alpha FIDC", "document_number": "11.222.333/0001-81", "accounting_date": "2024-04-01", "manager": { "manager_key": "e1f2a3b4-c5d6-4890-abcd-ef1234567890", "document_number": "22.222.222/0001-91", "manager_name": "Gestora Exemplo S.A." } }, "assignor": { "assignor_key": "c1d2e3f4-a5b6-4890-abcd-ef1234567890", "document_number": "33.333.333/0001-91", "name": "Cedente Exemplo Ltda" }, "assignment_reports": { "send_reports": false }, "assignment_configuration_type": "default_configuration", "status": "active", "consultant_decision_type": "manual_approval", "manager_decision_type": "manual_approval", "asset_fees": null, "payment_type": "pix", "custody_type": "internal", "required_documents": ["ccb"], "after_assignment_required_documents": [], "certifier": "certifiqi", "disbursement_account_policy": "all_assignor_accounts", "consultant": { "consultant_key": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d", "document_number": "44.444.444/0001-91", "name": "Consultoria Exemplo Ltda" }, "operation_type": "unsecured_credit", "originator_bonds": [ { "originator": { "originator_key": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "document_number": "33.333.333/0001-91", "name": "Cedente Exemplo Ltda" } } ] } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Configurações de cessão encontradas. Veja tabela abaixo. | | `page` | integer | Número da página atual. | | `limit` | integer | Registros por página. | | `is_last_page` | boolean | `true` na última página de resultados. | #### Atributos de cada configuração (objetos dentro de `data`) O mesmo objeto aparece em `assignment_configuration` na [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao). | 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. | | `assignment_contract_key` | string | Contrato de cessão que originou a configuração (UUID). | | `validation_configuration_key` | string \| null | Configuração de validação de documentos (UUID). | | `status` | string | `created`, `active`, `inactive` ou `blocked`. Só configurações `active` aceitam novos lotes. | | `asset_type` | string | Tipo de ativo aceito. Um lote só recebe ativos desse tipo. | | `assignment_configuration_type` | string | `default_configuration` (cessão) ou `repurchase_configuration` (substituição com recompra). | | `operation_type` | string | Tipo de operação (ex.: `unsecured_credit`, `fgts`, `duplicata_mercantil`). Ausente quando não definido. | | `registry_type` | string | Registro dos ativos: `internal_registry`, `external_registry`, `registry_transfer`, `deferred_registry`, `unfit` ou `skip_registry` (sem registro). | | `consultant_decision_type` | string | Aprovação da consultoria: `manual_approval`, `automatic_approval` ou `not_applicable`. | | `manager_decision_type` | string | Aprovação da gestora: `manual_approval` ou `automatic_approval`. | | `payment_type` | string | Forma de pagamento ao cedente: `pix` ou `wire_transfer`. | | `custody_type` | string | Custódia: `internal`, `cetip`, `skip_custody` ou `wait_custody_approval`. | | `certifier` | string | Certificadora da assinatura do Termo de Cessão: `certifiqi`, `qi_sign`, `id_trust` ou `qcertifica`. | | `disbursement_account_policy` | string \| null | Escolha da conta de desembolso: `all_assignor_accounts` (qualquer conta do cedente), `locked_on_assignment_contract` (conta fixada no contrato) ou `locked_on_assignment_term`. | | `disbursement_account_key` | string | Conta de desembolso fixada no contrato. Presente só quando há conta fixada. | | `required_documents` | array | Tipos de documento exigidos **antes** da cessão, enviados pelo [Envio do Lastro do Ativo](/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. | | `asset_fees` | object \| null | Taxas dos ativos, quando configuradas. | | `assignment_reports` | object | Envio de relatórios da cessão. | | `assignor_discounts_configuration` | object | Presente só quando a configuração permite [descontos ao cedente](/documentation/iaas/negociacao_recebiveis/assignment/criacao). | | `collection_configuration` | object | Configuração de cobrança, quando houver. | | `fund_class` | object | Fundo cessionário: `fund_class_key`, `name`, `document_number` (CNPJ), `accounting_date` (data contábil vigente) e `manager` (`manager_key`, `document_number`, `manager_name`). | | `assignor` | object | Cedente: `assignor_key`, `document_number` e `name`. | | `consultant` | object | Consultoria vinculada: `consultant_key`, `document_number` e `name`. Ausente quando não há consultoria. | | `originator_bonds` | array | Originadores vinculados, cada um em `originator` (`originator_key`, `document_number`, `name`). | ## Erros | Status | Código | Quando acontece | |---|---|---| | 400 | — | `limit` acima de 155 ou `page` negativo (validação de parâmetro). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. ::: :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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`. | | `status` | array de strings | opcional | Um ou mais status da solicitação (veja [Enumeradores de `status`](#enumeradores-de-status)). Repita o parâmetro para enviar mais de um. | | `issuance_serie_key` | string | opcional | Filtra por série de emissão. | | `quotation_date` | string | opcional | Filtra pela data de cotização (`YYYY-MM-DD`). | | `dto_filters_issuance_serie` | string | opcional | Envie `true` para omitir o objeto `issuance_serie` de cada item. | | `dto_filters_investor_amortizations` | string | opcional | Envie `true` para omitir o array `investor_amortizations` de cada item. | | `dto_filters_status_events` | string | opcional | Envie `true` para omitir o array `status_events` de cada item. | :::caution Atenção Os parâmetros `dto_filters_*` omitem o campo com **qualquer** valor não vazio — inclusive `false`. Para receber o campo, não envie o parâmetro. ::: Os resultados vêm da data de cotização mais recente para a mais antiga. ```text 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_person", "document_number": "11.222.333/0001-81", "distributor": { "distributor_key": "dddd4444-eeee-5555-ffff-aaaa66667777", "name": "Distribuidora Exemplo", "document_number": "22.333.444/0001-81", "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": "yield_curve", "status": "active", "internal_code": "SR-001", "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": "33.444.555/0001-81", "accounting_date": "2026-06-09", "sub_type": "regular", "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": "44.555.666/0001-81" } } } } } ], "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 cotizaçã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_person`, `legal_person` ou `nominee`). | | `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. | | `status` | string | Status da série de emissão. | | `internal_code` | string | Código interno 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. | | `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 (`regular` ou `cash`). | | `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 cotizaçã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 | | `blocked` | Bloqueada | ## 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 | | `reprocessed` | Reprocessada | | `blocked` | Bloqueada | ## 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 | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------- | | 400 | `QIT000004` | O fundo não é da gestora | | 404 | `QTA000002` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta paginada de Aplicação Financeira URL: /documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras Lista as aplicações financeiras de um cotista ou de uma classe de fundo, com paginação. ## Por cotista Retorna as aplicações financeiras de um cotista. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------------------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ENDPOINT /quota/investor/INVESTOR_KEY/financial_applications MÉTODO GET STATUS 200 Para a gestora, a consulta retorna apenas aplicações em fundos dela, e só de investidores aos quais ela está vinculada. ### Query Params | Parâmetro | Descrição | | ---------------------------- | --------------------------------------------------------------------------------------------- | | `page` | Página, a partir de 0 (default 0) | | `limit` | Itens por página (default 20, máximo 500) | | `status` | Lista de **[Financial Application Status](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave#financial_application_status)** | | `types` | Lista de tipos: `primary_market`, `secondary_market` | | `issuance_serie_key` | Filtra por série de emissão | | `quotation_date` | Data de cotização (`yyyy-mm-dd`) | | `fund_class_document_number` | CNPJ da classe de fundo | | `application_from_datetime` | Aplicações com data/hora maior ou igual ao valor, no formato `yyyy-mm-ddTHH:MM:SSZ` (UTC) | | `application_to_datetime` | Aplicações com data/hora menor ou igual ao valor, no formato `yyyy-mm-ddTHH:MM:SSZ` (UTC) | ## Por classe de fundo Retorna as aplicações financeiras de uma classe de fundo da gestora, da mais recente para a mais antiga. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ENDPOINT /quota/fund_class/FUND_CLASS_KEY/financial_applications MÉTODO GET STATUS 200 ### Query Params | Parâmetro | Descrição | | --------------------------- | ---------------------------------------------------------------------------------------------- | | `page` | Página, a partir de 0 (default 0) | | `limit` | Itens por página (default 20, máximo 100) | | `status` | Lista de **[Financial Application Status](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave#financial_application_status)** | | `investor_name` | Parte do nome do investidor (sem diferenciar maiúsculas) | | `investor_document_number` | CPF/CNPJ do investidor | | `quotation_date` | Data de cotização (`yyyy-mm-dd`) | | `application_from_datetime` | Aplicações com data/hora maior ou igual ao valor, no formato `yyyy-mm-ddTHH:MM:SSZ` (UTC) | | `application_to_datetime` | Aplicações com data/hora menor ou igual ao valor, no formato `yyyy-mm-ddTHH:MM:SSZ` (UTC) | `limit` acima do máximo devolve 400. ## Response As duas consultas devolvem a mesma estrutura. Cada item de `data` é o objeto **Financial Application** descrito em [Consultar Aplicação Financeira por chave](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave#financial_application). ```json { "data": [ { "financial_application_key": "UUID", "share_capital": 1000.0, "status": "quoted", "financial_application_type": "primary_market", "quotation_date": "2025-01-10" } ], "limit": 20, "page": 0, "is_last_page": true } ``` | Campo | Tipo | Descrição | | -------------- | ------- | --------------------------------------------- | | `data` | array | Lista de aplicações financeiras | | `limit` | int | Itens por página | | `page` | int | Página retornada | | `is_last_page` | boolean | `true` quando não há mais páginas | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------------------------------------------------------------- | | 400 | `QIT000001` | Data ou data/hora em formato inválido | | 400 | `QIT000004` | A gestora não é a gestora do fundo ou não está vinculada ao investidor | | 404 | `QTA000002` | Classe de fundo não encontrada (consulta por classe) | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta paginada de Fechamento das Aplicações Financeiras URL: /documentation/iaas/passivo/aplicacao_financeira/busca_paginada_fechamento_das_aplicacoes_financeiras Lista os fechamentos diários (posição contábil) das aplicações financeiras, por classe de fundo ou por aplicação. ## Por classe de fundo :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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 (`yyyy-mm-dd`) | | `from_date` | Data de início do período (`yyyy-mm-dd`) | | `to_date` | Data de fim do período (`yyyy-mm-dd`) | | `investor_document_number` | CPF/CNPJ do investidor | | `limit` | Itens por página (default 75, máximo 75) | | `page` | Página, a partir de 0 (default 0) | :::caution Atenção Envie `accounting_date` **ou** o par `from_date` e `to_date` — nunca os dois. Sem nenhum deles, a API devolve `QTA000026`; com os dois, `QIT000001`. Parâmetros fora desta lista também são recusados com `QIT000001`. ::: Os resultados vêm ordenados da data contábil mais recente para a mais antiga. ## Por investidor e aplicação financeira :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: 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 (default `false`) | | `limit` | Itens por página (default 50, máximo 500) | | `page` | Página, a partir de 0 (default 0) | ## Response Caso 01: Consulta bem-sucedida ```json { "data": [ { "financial_application": { "financial_application_key": "UUID", "share_capital": 1000.0, "status": "quoted", "financial_application_type": "primary_market", "payment_method": "regular", "quotation_date": "2025-01-10", "investor": { "investor_key": "UUID", "name": "INVESTIDOR EXEMPLO", "person_type": "natural_person" }, "issuance_serie": { "issuance_serie_key": "UUID" } }, "total_value": 1012.35, "number_of_quotas": 998.12345678, "principal_value": 1000.0, "acquisition_cost": 1000.0, "yield_value": 12.35, "ir_value": 2.78, "iof_value": 0.0, "taxable_yield_value": 12.35, "accounting_date": "2025-01-31" } ], "limit": 75, "page": 0, "is_last_page": true } ``` | Campo | Tipo | Descrição | | -------------- | ------- | --------------------------------------------------------------------------------------- | | `data` | array | Lista de objetos **[Financial Application Closing](#financial-application-closing)** | | `limit` | int | Itens por página | | `page` | int | Página retornada | | `is_last_page` | boolean | `true` quando não há mais páginas | ### Financial Application Closing | Campo | Tipo | Descrição | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `financial_application` | object | Aplicação financeira completa, no formato de [Consultar Aplicação Financeira por chave](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave#financial_application) | | `total_value` | float | Valor total da aplicação no fechamento | | `number_of_quotas` | float | Número de cotas no fechamento | | `principal_value` | float | Valor principal no fechamento | | `acquisition_cost` | float | Custo de aquisição das cotas no fechamento | | `yield_value` | float | Rendimento bruto | | `ir_value` | float | IR | | `iof_value` | float | IOF | | `taxable_yield_value` | float | Rendimento tributável | | `accounting_date` | string | Data contábil do fechamento | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------------------------------- | | 400 | `QTA000026` | Consulta por classe sem `accounting_date` nem o par `from_date`/`to_date` | | 400 | `QIT000001` | Parâmetro inválido ou desconhecido, `limit` acima de 75, ou `accounting_date` junto com `from_date`/`to_date` | | 400 | `QIT000004` | O fundo não é da gestora | | 404 | `QTA000020` | Investidor não encontrado (a API responde com o erro de distribuidor não encontrado) | | 404 | `QTA000023` | Aplicação financeira não encontrada para o investidor | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consultar Aplicação Financeira por chave URL: /documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave Retorna uma aplicação financeira de um investidor pela chave. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /quota/investor/INVESTOR_KEY/financial_application/FINANCIAL_APPLICATION_KEY MÉTODO GET STATUS 200 A gestora só consulta investidores aos quais está vinculada; a consultoria, aplicações de fundos em que tem permissão. ## Responses Caso 01: Consulta bem-sucedida ```json { "financial_application_key": "UUID", "external_id": "SEU_ID_EXTERNO", "share_capital": 1000.0, "status": "quoted", "financial_application_type": "primary_market", "payment_method": "regular", "central_depositary": "unregistered", "quotation_date": "2025-01-10", "original_number_of_quotas": 998.12345678, "original_number_of_quotas_str": "998.12345678", "current_number_of_quotas": 998.12345678, "current_principal_value": 1000.0, "acquisition_cost": 1000.0, "status_events": [ { "event_datetime": "2025-01-09T14:30:00Z", "status": "pending_payment" }, { "event_datetime": "2025-01-10T21:00:00Z", "status": "quoted" } ], "redemptions": [], "amortizations": [], "investor": { "investor_key": "UUID", "name": "INVESTIDOR EXEMPLO", "person_type": "natural_person", "document_number": "969.698.790-03", "distributor": { "distributor_key": "UUID", "document_number": "11.222.333/0001-81", "name": "DISTRIBUIDORA EXEMPLO", "account_data": {} } }, "issuance_serie": { "issuance_serie_key": "UUID", "name": "SERIE 1", "serie": 1, "status": "active", "remuneration_type": "yield_curve", "original_quota_value": 1.0, "current_quota_value": 1.0018, "sub_class": { "name": "COTA SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "name": "FUNDO EXEMPLO", "fund_class_key": "UUID", "document_number": "11.222.333/0001-81" } } }, "water_mark_events": [] } ``` Campos opcionais (`external_id`, `original_number_of_quotas`, `current_number_of_quotas`, `current_principal_value`, `acquisition_cost`, `quotation_date`) só aparecem quando preenchidos. As listas `status_events`, `redemptions`, `amortizations` e `reserved_taxable_yields` são omitidas quando vazias. ### Financial Application {#financial_application} | Campo | Tipo | Descrição | | ------------------------------- | ------ | -------------------------------------------------------------------------------- | | `financial_application_key` | string | Chave única da aplicação financeira | | `external_id` | string | Identificador externo | | `share_capital` | float | Valor aplicado | | `status` | string | Enumerador de **[Financial Application Status](#financial_application_status)** | | `financial_application_type` | string | `primary_market` (aplicação) ou `secondary_market` (mercado secundário) | | `payment_method` | string | `regular` (Pix ou TED) ou `b3` | | `central_depositary` | string | `unregistered` ou `cetip` | | `quotation_date` | string | Data de cotização (`yyyy-mm-dd`) | | `original_number_of_quotas` | float | Quantidade de cotas na cotização (`_str`: o mesmo valor como string, sem arredondamento) | | `current_number_of_quotas` | float | Quantidade atual de cotas | | `current_principal_value` | float | Principal atual | | `acquisition_cost` | float | Custo de aquisição | | `status_events` | array | Histórico de status: `status` e `event_datetime` (UTC) | | `redemptions` | array | Resgates que consumiram a aplicação: `redemption_key`, `redemption_type`, `number_of_quotas`, `total_value`, `ir_value`, `iof_value`, `yield_value`, `taxable_yield_value`, `redemption_date` | | `amortizations` | array | Amortizações pagas: `amortization_key`, `payment_date`, `total_value`, `principal_reduction`, `acquisition_cost_reduction` e, quando houver, `yield_value`, `taxable_yield_value`, `ir_value`, `iof_value` | | `reserved_taxable_yields` | array | Rendimentos tributáveis reservados (come-cotas) | | `investor` | object | Investidor: `investor_key`, `name`, `person_type`, `document_number` e `distributor` | | `issuance_serie` | object | Série de emissão, com `sub_class` e `sub_class.fund_class` | | `water_mark_quota_value` | float | Valor de cota de referência da marca d'água (taxa de performance), quando houver | | `water_mark_reference_date` | string | Data de referência da marca d'água, quando houver | | `water_mark_events` | array | Eventos de marca d'água | ### Financial Application Status {#financial_application_status} | Enumerador | Descrição | | ----------------------------------- | ----------------------------------------------- | | `created` | Criada | | `pending_formalization` | Pendente de formalização (boletim de subscrição) | | `pending_payment` | Pendente de pagamento | | `processing_quotation` | Cotização em processamento | | `pending_quote` | Pendente de cotização | | `processing_issuance_serie_impacts` | Processando impactos na série | | `quoted` | Cotizada | | `settled` | Totalmente amortizada | | `redeemed` | Totalmente resgatada | | `canceled` | Cancelada | | `reprocessed` | Reprocessada | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------------------------------------------- | | 400 | `QIT000004` | A gestora não está vinculada ao investidor | | 403 | `QTA000315` | A consultoria não tem permissão no fundo da aplicação | | 404 | `QTA000021` | Investidor não encontrado | | 404 | `QTA000260` | Aplicação financeira não encontrada para o investidor | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Criar Aplicação Financeira URL: /documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira Cria uma aplicação financeira de um investidor em uma série de emissão. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | --------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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" } ``` :::info Campos obrigatórios - issuance_serie_key - share_capital ::: :::caution Atenção **payment_method** e **central_depositary** são opcionais. Se não forem enviados, a API usa os valores marcados como default na tabela abaixo (`regular` e `unregistered`). - Com **central_depositary** `cetip`, o **payment_method** pode ser `regular` ou `b3`. Com `unregistered`, apenas `regular` (`b3` devolve o erro `QTA000359`). ::: ### 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 (maior ou igual a 0). Se a série tiver valor mínimo de aplicação, o valor precisa atingi-lo | | `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 **(default)**
• cetip: Registrado na Cetip | | `quotation_date` | string | Data de cotização da aplicação, no formato yyyy-mm-dd (opcional). Precisa ser dia útil e não pode ser anterior à data contábil do fundo. Se omitida, é calculada pela configuração de prazos da série | ## Response A resposta traz o objeto da aplicação financeira criada, no mesmo formato da [consulta por chave](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave). Guarde o `financial_application_key`. ```json title='Response Body (resumido)' { "financial_application_key": "UUID", "share_capital": 1000.0, "status": "pending_payment", "financial_application_type": "primary_market", "payment_method": "regular", "central_depositary": "unregistered", "quotation_date": "2025-01-10" } ``` ## Erros | Status | Código | Quando acontece | | ------ | ----------- | --------------------------------------------------------------------------------------------------- | | 400 | `QIT000001` | Corpo inválido: campo obrigatório ausente, tipo errado ou campo não previsto | | 400 | `QIT000004` | A série não pertence a um fundo da gestora | | 400 | `QTA000359` | `payment_method` `b3` com `central_depositary` `unregistered` | | 400 | `QTA000272` | `share_capital` abaixo do valor mínimo de aplicação da série | | 400 | `QTA000176` | `quotation_date` não é dia útil | | 400 | `QTA000225` | `quotation_date` anterior à data contábil do fundo | | 400 | `QTA000264` | Valor acima do disponível na oferta ou no boletim de subscrição (fundo fechado) | | 400 | `QTA000267` | O boletim de subscrição do investidor ainda não está pronto para subscrição (fundo fechado) | | 400 | `QTA000269` | A aplicação deixaria a subclasse desenquadrada (índice de subordinação) | | 403 | `QTA000315` | A consultoria não tem permissão no fundo da série | | 404 | `QTA000004` | Valor inválido em `payment_method` ou `central_depositary` | | 404 | `QTA000015` | `issuance_serie_key` não encontrada | | 404 | `QTA000021` | Investidor não encontrado (na `manager-api`, hoje a resposta vem como `QTA000020`) | | 404 | `QTA000265` | O investidor não tem boletim de subscrição (fundo fechado) | | 404 | `QTA000266` | A série não tem oferta de cotas (fundo fechado) | | 422 | `QTA000425` | A série de emissão já foi liquidada | | 422 | `QTA000357` | Movimentação bloqueada: a série está com valor de cota zerado ou negativo | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. :::caution 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%** ::: :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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 ## Erros Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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**. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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 | - | ## Erros Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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**. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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 | - | ## Erros Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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" } ``` ## Erros Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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" } ``` ## Erros Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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](/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas). Uma execução solicitada sobre uma garantia com cadastro incompleto **não é registrada**. :::caution 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. ::: :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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](/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas), 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" } ] } ] } ``` :::info 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](/documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota). ## Erros | Status | Código | Quando acontece | |--------|-------------|---------------------------------------------------------------------------------| | 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 | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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**. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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](/documentation/iaas/passivo/bloqueio_de_cotas/execucao_de_garantia). ## Erros Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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**. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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": "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": "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` | JSON | 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 bloqueado | - | Não | ## Responses ```json title='Response Body' { "quota_lock_key": "UUID" } ``` ## Erros Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 de fechamento. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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`). Padrão: `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. | | `name` | string | opcional | Parte do nome do investidor (sem diferenciar maiúsculas). | | `reference_date` | string (data) | opcional | Retorna só investidores com fechamento de aplicação financeira nessa data contábil (`YYYY-MM-DD`). | ```text 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": "11.222.333/0001-81", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "11.222.333/0001-81" }, "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": "969.698.790-03", "external_id": "ext-inv-001", "external_distribution_key": null }, { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "11.222.333/0001-81", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "11.222.333/0001-81" }, "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": "22.333.444/0001-81", "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. | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------- | | 400 | `QIT000004` | O fundo não é da gestora | | 404 | `QTA000002` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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). | ```text title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/investor_positions?page=0&limit=20&document_number=969.698.790-03 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "investor": { "distributor": { "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef", "document_number": "11.222.333/0001-81", "name": "Distribuidora Exemplo S.A.", "account_data": { "owner": { "name": "Distribuidora Exemplo S.A.", "document_number": "11.222.333/0001-81" }, "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": "969.698.790-03", "external_id": "ext-inv-001" }, "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", "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": "11.222.333/0001-81", "fund_class_key": "e5f6a7b8-c9d0-1234-ef01-345678901234", "accounting_date": "2024-06-01", "sub_type": "regular", "tax_classification": "long_term", "condominum_type": "open_ended", "prevent_payment": false, "manager": { "manager_key": "f6a7b8c9-d0e1-2345-f012-456789012345", "document_number": "11.222.333/0001-81", "manager_name": "Gestora Exemplo S.A." } } }, "status": "active", "internal_code": "INT-FEX-01", "current_quota_value": 1.0500015, "post_fixed": { "calendar_base": "calendar_252", "indexer": "cdi", "rate": 1.0, "lag": { "reference": "daily", "amount": 1 } }, "isin_code": "BRSTREXTFID6", "water_mark_events": [] }, "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 de `issuance_serie` (como `pre_fixed`, `post_fixed`, `isin_code`, `external_id`) só aparecem quando preenchidos no cadastro da série. Só entram posições com saldo de cotas maior que zero, em fundos da gestora da integração. Um fundo de outra gestora devolve lista vazia. 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). ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------- | | 404 | `QTA000002` | Classe de fundo não encontrada | | 404 | `QTA00053` | Gestora da integração não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta paginada dos fechamentos de uma série de emissão URL: /documentation/iaas/passivo/consultas/consultar_fechamentos_serie_de_emissao Retorna os **fechamentos diários** de uma série de emissão (cota e patrimônio líquido de cada etapa do fechamento), de forma paginada e ordenada da data contábil mais recente para a mais antiga. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /quota/fund_class/{fund_class_key}/sub_class/{sub_class_key}/issuance_serie/{issuance_serie_key}/issuance_serie_closings MÉTODO GET STATUS 200 ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave única da classe de fundo (UUID). | | `sub_class_key` | string | Chave única da subclasse da série (UUID). | | `issuance_serie_key` | string | Chave única da série de emissão (UUID). | As chaves podem ser obtidas na **[Consulta paginada de todas as séries](/documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao)**. ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `accounting_date` | string (data) | condicional | Data contábil de um fechamento específico (`YYYY-MM-DD`). | | `from_date` | string (data) | condicional | Data contábil inicial do período (`YYYY-MM-DD`). Deve ser enviada junto com `to_date`. | | `to_date` | string (data) | condicional | Data contábil final do período (`YYYY-MM-DD`). Deve ser enviada junto com `from_date`. | | `status` | string | opcional | Lista de status do fechamento separados por vírgula. `pending_distribution`: retorna o valor da cota das séries indexadas nos dias em que o fundo ainda não fechou. `closed`: retorna os fechamentos concluídos. Sem o parâmetro, retornam apenas os fechamentos com cota bruta já calculada. | | `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. | | `limit` | integer | opcional | Registros por página. Padrão: `50`. Máximo: `500`. | :::caution Atenção É obrigatório enviar `accounting_date` **ou** a combinação de `from_date` e `to_date`. Sem nenhum deles, a API devolve `QTA000026`. ::: ```text title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/sub_class/{sub_class_key}/issuance_serie/{issuance_serie_key}/issuance_serie_closings?from_date=2026-09-29&to_date=2026-09-30&page=0&limit=50 ``` ## Response ```json title="Response Body" { "data": [ { "gross_quota_value": 1250.0, "gross_net_worth": 1250000.0, "accounting_date": "2026-09-30", "status": "closed", "before_amortization_quota_value": 1248.5, "before_amortization_net_worth": 1248500.0, "quota_value": 1248.5, "total_net_worth": 1248500.0, "closed_net_worth": 1248500.0, "closed_quota_value": 1248.5, "performance_fee_current_value": 1500.0 }, { "gross_quota_value": 1249.1, "gross_net_worth": 1249100.0, "accounting_date": "2026-09-29", "status": "closed", "before_amortization_quota_value": 1247.7, "before_amortization_net_worth": 1247700.0, "quota_value": 1247.7, "total_net_worth": 1247700.0, "closed_net_worth": 1247700.0, "closed_quota_value": 1247.7, "performance_fee_current_value": 1400.0 } ], "limit": 50, "page": 0, "is_last_page": true } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de fechamentos da série, da data contábil mais recente para a mais antiga. | | `limit` | integer | Tamanho da página. | | `page` | integer | Página atual. | | `is_last_page` | boolean | Indica fim da paginação. | #### Campos de cada fechamento em `data` | Campo | Tipo | Descrição | |---|---|---| | `accounting_date` | string | Data contábil do fechamento (`YYYY-MM-DD`). | | `gross_quota_value` | float | Cota bruta, antes da taxa de performance. | | `gross_net_worth` | float | Patrimônio líquido bruto, antes da taxa de performance. | | `status` | string | Status do fechamento (ex.: `pending_distribution`, `closed`). | | `before_amortization_quota_value` | float | Cota após a taxa de performance e antes das amortizações. | | `before_amortization_net_worth` | float | Patrimônio líquido após a taxa de performance e antes das amortizações. | | `quota_value` | float | Cota final do dia, após as amortizações. | | `total_net_worth` | float | Patrimônio líquido final do dia, após as amortizações. | | `closed_quota_value` | float | Cota travada do fechamento. | | `closed_net_worth` | float | Patrimônio líquido travado do fechamento. | | `performance_fee_current_value` | float | Valor provisionado de taxa de performance. | Os campos além de `accounting_date`, `gross_quota_value` e `gross_net_worth` só aparecem quando já calculados para o dia. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ----------------------------------------------------------------- | | 400 | `QTA000026` | Sem `accounting_date` e sem o par `from_date`/`to_date` | | 400 | `QIT000004` | O fundo não é da gestora | | 404 | `QTA000002` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta paginada do Mapa de Evolução de Cotas URL: /documentation/iaas/passivo/consultas/consultar_mapa_de_evolucao_de_cotas Retorna, por dia, a evolução da cota de uma série de emissão (patrimônio, valor de cota, movimentações e rentabilidade), a partir das carteiras confirmadas do fundo. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler Carteiras | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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: 50, máximo: 100) | | `page` | `int` | Não | Página atual (default: 0) | :::caution Atenção Envie `reference_date` (um dia) **ou** o par `start_date` e `end_date` (um intervalo), nunca os dois. Os resultados vêm da data mais recente para a mais antiga. ::: 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%) | Os campos de rentabilidade só aparecem quando calculados para o dia. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------------------------- | | 400 | `CMP000018` | Nenhum filtro de data enviado | | 400 | `CMP000019` | `reference_date` junto com `start_date`/`end_date`, ou só uma das datas do par | | 400 | `CMP000017` | `start_date` posterior a `end_date` | | 400 | `CMP000021` | A série não pertence ao fundo informado | | 400 | `QIT000004` | O fundo não é da gestora | | 403 | `CMP000032` | Consultoria: o fundo não é da gestora que concedeu o acesso | | 404 | `CMP000001` | Classe de fundo não encontrada | | 404 | `CMP000020` | Série de emissão não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta paginada de Séries de Emissão URL: /documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao Lista as séries de emissão dos fundos da gestora, com paginação. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /quota/issuance_series MÉTODO GET STATUS 200 ## Query Params | Parâmetro | Descrição | | ---------------------------- | ------------------------------------------------------------------------------------------ | | `page` | Página, a partir de 0 (default 0) | | `limit` | Itens por página (default 20, máximo 500) | | `issuance_serie_key` | Chave única da série de emissão | | `fund_class_document_number` | CNPJ do fundo da série | | `fund_class_name` | Parte do nome do fundo (sem diferenciar maiúsculas) | | `only_active` | `true` retorna só séries com cotas em circulação e status diferente de `settled` e `pending_first_integralization` (default `false`) | | `not_in_status` | Lista de status de série a excluir do resultado | Caso 01: Retorno com uma série de emissão ```json { "data": [ { "issuance_serie_key": "UUID", "name": "SERIE 1", "serie": 1, "status": "active", "internal_code": "FUNDOEX-SR1", "remuneration_type": "residual", "original_quota_value": 1.0, "current_quota_value": 1.0518, "current_number_of_quotas": 500000.0, "current_net_worth": 525900.0, "current_principal_value": 500000.0, "performance_fee_current_value": 0.0, "minimum_share_capital": 0.0, "operation_period_configuration": {}, "sub_class": { "name": "COTA SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "name": "FUNDO EXEMPLO", "short_name": "FUNDO EX", "fund_class_key": "UUID", "document_number": "11.222.333/0001-81", "accounting_date": "2025-01-10", "sub_type": "regular", "tax_classification": "long_term", "condominum_type": "open_ended", "prevent_payment": false, "manager": { "manager_key": "UUID", "document_number": "11.222.333/0001-81", "manager_name": "GESTORA EXEMPLO" }, "administrator": { "name": "QI DTVM", "administrator_key": "UUID", "document_number": "11.222.333/0001-81" } } }, "water_mark_events": [] } ], "limit": 20, "page": 0, "is_last_page": true } ``` ## Issuance Serie | Campo | Tipo | Descrição | | -------------------------------- | ------ | ------------------------------------------------------------------------- | | `issuance_serie_key` | string | Chave única da série | | `name` | string | Nome da série | | `serie` | number | Número da série | | `status` | string | `created`, `pending_first_integralization`, `active` ou `settled` | | `internal_code` | string | Código interno da série | | `remuneration_type` | string | `yield_curve` ou `residual` | | `original_quota_value` | number | Valor original da cota | | `current_quota_value` | number | Valor atual da cota (patrimônio ÷ cotas; o original se não houver cotas) | | `current_number_of_quotas` | number | Cotas em circulação | | `current_net_worth` | number | Patrimônio líquido atual | | `current_principal_value` | number | Principal atual | | `performance_fee_current_value` | number | Taxa de performance provisionada | | `minimum_share_capital` | number | Valor mínimo de aplicação | | `operation_period_configuration` | object | Prazos de cotização e pagamento de aplicação e resgate | | `interest_rate_type`, `pre_fixed`, `post_fixed` | — | Remuneração da série, quando houver | | `isin_code`, `external_id` | string | Quando preenchidos | | `sub_class` | object | Subclasse (`name`, `sub_class_key`, `subordination_level`) e `fund_class` | | `water_mark_events` | array | Eventos de marca d'água (taxa de performance) | O objeto `fund_class` tem os mesmos campos de [Consulta paginada de Fundos](/documentation/iaas/passivo/consultas/consultar_todos_fundos). ## Erros Esta consulta não tem erros de regra de negócio: filtros sem correspondência devolvem `data` vazio. Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta paginada de Fundos URL: /documentation/iaas/passivo/consultas/consultar_todos_fundos Lista as classes de fundo da gestora, com paginação. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /quota/fund_classes MÉTODO GET STATUS 200 ## Query Params | Parâmetro | Descrição | | ----------------- | ----------------------------------------------------------------------- | | `page` | Página, a partir de 0 (default 0) | | `limit` | Itens por página (default 50, máximo 500) | | `name` | Parte do nome ou do nome curto do fundo (sem diferenciar maiúsculas) | | `document_number` | CNPJ do fundo | | `fund_class_key` | Chave única do fundo | Caso 01: Retorno com apenas um fundo ```json { "data": [ { "name": "FUNDO EXEMPLO", "short_name": "FUNDO EX", "document_number": "11.222.333/0001-81", "fund_class_key": "UUID", "accounting_date": "2025-01-10", "sub_type": "regular", "tax_classification": "long_term", "condominum_type": "open_ended", "prevent_payment": false, "manager": { "manager_key": "UUID", "document_number": "11.222.333/0001-81", "manager_name": "GESTORA EXEMPLO" }, "administrator": { "name": "QI DTVM", "administrator_key": "UUID", "document_number": "11.222.333/0001-81" } } ], "limit": 50, "page": 0, "is_last_page": true } ``` ## Fund Class | Campo | Tipo | Descrição | | ----------------------------- | ------- | --------------------------------------------------------------- | | `fund_class_key` | string | Chave única do fundo | | `name` | string | Nome do fundo | | `short_name` | string | Nome curto do fundo | | `document_number` | string | CNPJ do fundo | | `accounting_date` | string | Data contábil atual do fundo | | `sub_type` | string | Subtipo do fundo: `regular` ou `cash` | | `tax_classification` | string | Classificação tributária | | `condominum_type` | string | Tipo de condomínio: `open_ended` (aberto) ou `close_ended` (fechado) | | `prevent_payment` | boolean | Indica se os pagamentos do fundo estão bloqueados | | `manager` | object | Gestora: `manager_key`, `document_number`, `manager_name` | | `administrator` | object | Administrador: `administrator_key`, `name`, `document_number` (quando houver) | | `integralization_account_key` | string | Conta de integralização (quando houver) | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | --------------------------------------------- | | 400 | `QIT000004` | A gestora da integração não foi encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. :::caution Atenção Este recurso está disponível apenas para integrações que exercem o papel de **Distribuidor**. Use a chave de API e o host do perfil Distribuidor: veja [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Input / Output: Como ***input*** devem ser enviadas as informações da subscrição, o UUID da **oferta de cotas** que o investidor subscreveu, o **método de assinatura** e, dependendo do método, o conteúdo necessário para validação. Segue abaixo exemplo. Como ***output*** será entregue o objeto completo do **boletim de subscrição** criado, incluindo a ***subscription_note_key***, que identifica o boletim. O boletim é criado já no status `active` (ou `sold_off`, se `remaining_subscription_note_value` for zero). ## 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": 500.0, "original_subscription_note_value": 50000.00, "start_date": "2026-01-15", "maturity_date": "2026-12-31", "quota_offering_key": "UUID", "transaction_type": "ted", "signature_method": "opt_in", "opt_in_hash" : "OPT_IN_HASH" } ``` | Campo | Tipo | Descrição | Obrigatório | |-------------------------------------|--------|------------------------------------------------------------------------------------------------------------|-------------| | `original_subscription_note_value` | number | Valor do boletim. Mínimo 0. Não pode exceder o valor restante da oferta | Sim | | `quota_offering_key` | string | UUID da oferta de cotas. A oferta deve estar `active`, com valor restante e sem aditamento pendente | Sim | | `transaction_type` | string | `ted` ou `b3` | Sim | | `signature_method` | string | Método de assinatura usado. Com `opt_in`, envie `opt_in_hash`; com qualquer outro método, envie `document_b64` | Sim | | `opt_in_hash` | string | Hash do opt-in (até 250 caracteres) | Não | | `document_b64` | string | Boletim assinado codificado em base64 | Não | | `number_of_quotas` | number | Quantidade de cotas do boletim | Não | | `remaining_subscription_note_value` | number | Saldo restante do boletim. Não pode ser maior que `original_subscription_note_value` | Não | | `start_date` | string | Data inicial (`YYYY-MM-DD`). Se omitida, usa a data atual (UTC) | Não | | `maturity_date` | string | Data de vencimento (`YYYY-MM-DD`). Não pode estar no passado | Não | :::caution Atenção Durante o processo de integração será exigido um meio de autenticação da hash enviada. ::: ## Response A resposta tem o mesmo formato da resposta de [Solicitar Boletim de Subscrição](/documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao#response). ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------------------------------- | | 400 | `QOF000020` | `maturity_date` está no passado | | 400 | `QOF000026` | O valor do boletim é maior que o valor restante da oferta | | 400 | `QOF000046` | `transaction_type` inválido | | 400 | `QOF000047` | A classificação do investidor não permite subscrever a oferta | | 400 | `QOF000068` | `signature_method` inválido | | 400 | `QOF000069` | `signature_method` é `opt_in` e `opt_in_hash` não foi enviado | | 400 | `QOF000072` | `signature_method` não é `opt_in` e `document_b64` não foi enviado | | 400 | `QOF000150` | `remaining_subscription_note_value` é maior que `original_subscription_note_value` | | 400 | `QIT000004` | A integração não é a distribuidora do investidor | | 404 | `QOF000017` | Investidor não encontrado | | 404 | `QOF000019` | Oferta de cotas não encontrada | | 404 | `QOF000039` | A oferta não está ativa, está vencida ou não tem valor restante | | 409 | `QOF000152` | A oferta tem um aditamento aguardando aprovação | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Recuperando Informações sobre Boletim de Subscrição URL: /documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao --- Lista os **boletins de subscrição** de um investidor ou de uma classe de fundo, de forma paginada. ## Request ### Boletins de um investidor :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/subscription_notes MÉTODO GET STATUS 200 A gestora recebe apenas os boletins de ofertas de fundos que ela gere. | Query param | Descrição | |------------------------------|-------------------------------------------------------------------------------------------------| | `limit` | Itens por página. Padrão 50, máximo 500 | | `page` | Página, começando em 0. Padrão 0 | | `status` | Filtra por status. Aceita mais de um valor, separados por vírgula | | `issuance_serie_key` | Filtra pela série de emissão | | `fund_class_document_number` | Filtra pelo CNPJ da classe de fundo | | `financial_application_key` | Filtra pela aplicação financeira | | `quotation_date` | Com `status=sold_off`, retorna os boletins esgotados nessa data (`YYYY-MM-DD`) | ### Boletins de uma classe de fundo :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ENDPOINT /quota_offering_control/fund_class/FUND_CLASS_KEY/subscription_notes MÉTODO GET STATUS 200 | Query param | Descrição | |----------------------------|-------------------------------------------------------------------------------| | `limit` | Itens por página. Padrão 50, máximo 500 | | `page` | Página, começando em 0. Padrão 0 | | `status` | Filtra por status. Aceita mais de um valor, separados por vírgula | | `investor_key` | Filtra pelo investidor | | `investor_document_number` | Filtra pelo CPF/CNPJ do investidor | ## Responses 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", "subscription_note_template_key":"UUID", "subscription_note_generation_type":"internal / external", "regulatory_type":"exclusive_fund", "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" }, "status_events":[ { "status":"active", "event_datetime":"YYYY-MM-DD HH:MM:SS" } ] }, "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":"active", "transaction_type":"b3 / ted", "signature_method":"certifiqi / qi_sign / opt_in / external", "original_subscription_note_value":0.00, "issued_number_of_quotas":0.00000000, "remaining_subscription_note_value":0.00, "total_assignment_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" } ], "status_events":[ { "status":"created", "event_datetime":"YYYY-MM-DD HH:MM:SS" }, { "status":"active", "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 | ## 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 | Status do boletim. Ver **[Subscription Note Status](#subscription-note-status)** | | `signature_method` | string | `certifiqi` / `qi_sign` / `opt_in` / `external` | | `total_assignment_value` | float | Valor total cedido do boletim | | `status_events` | array | Histórico de status (`status`, `event_datetime`) | | `transaction_type` | string | `ted` / `b3` | | `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. Ausente quando não preenchida | | `original_number_of_quotas`| float | Quantidade original de cotas. Ausente quando não preenchida | ## Subscription Note Status | Enumerador | Descrição | |-----------------------------|-----------------------------------------------| | `created` | Criado | | `pending_batch_close` | Aguardando fechamento do lote | | `send_to_generate_document` | Enviado para geração do documento | | `pending_document` | Aguardando documento | | `pending_manual_inputs` | Aguardando dados manuais (geração externa) | | `pending_signature` | Aguardando assinatura | | `active_without_signature` | Ativo sem assinatura | | `active` | Ativo | | `sold_off` | Esgotado | | `processing_cancellation` | Em cancelamento | | `canceled` | Cancelado | | `processing_expired` | Em expiração | | `expired` | Expirado | ## Quota Offering O objeto `quota_offering` tem os mesmos campos da resposta de [Informações das ofertas](/documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas#quota-offering), inclusive os objetos aninhados `issuance_serie`, `sub_class` e `fund_class`. ## 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. Só aparece quando `type` é `consume_value` | | `number_of_quotas` | float | Número de cotas da aplicação financeira. Só aparece quando `type` é `update_quotas` | ## 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 | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ----------------------------------------------------------------------- | | 400 | `QIT000004` | A classe de fundo não é gerida pela gestora | | 404 | `QOF000007` | Classe de fundo não encontrada | | 404 | `QOF000017` | Investidor não encontrado | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Recuperando Informações sobre as Ofertas URL: /documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas --- Lista as **ofertas de cotas** de uma classe de fundo, de forma paginada. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /quota_offering_control/fund_class/FUND_CLASS_KEY/quota_offerings MÉTODO GET STATUS 200 ## Query Params | Parâmetro | Descrição | |----------------------|------------------------------------------------------------------------------------------------------------| | `limit` | Itens por página. Padrão 50, máximo 500 | | `page` | Página, começando em 0. Padrão 0 | | `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 | | `showOffers` | `active`: só ofertas ativas com valor restante. `closed`: ofertas fechadas ou com vencimento no passado | ## Responses Caso 01: Fundo com uma Oferta ```json { "data":[ { "quota_offering_key":"UUID", "status":"active", "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", "subscription_note_template_key":"UUID", "subscription_note_generation_type":"internal / external", "regulatory_type":"exclusive_fund", "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" }, "status_events":[ { "status":"active", "event_datetime":"YYYY-MM-DD HH:MM:SS" } ] } ], "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 | ## Quota Offering | Campo | Tipo | Descrição | |-----------------------------------|----------|-----------------------------------------------------------------------------------------| | `quota_offering_key` | string | Chave única de identificação da oferta | | `status` | string | `created` / `active` / `processing_closing` / `pending_closing_at_cvm` / `pending_closing_at_anbima` / `pending_divulgation` / `closed` | | `subscription_note_generation_type` | string | `internal` (documento gerado pela QI) / `external` | | `subscription_note_template_key` | string | Chave do modelo do boletim de subscrição | | `regulatory_type` | string | Tipo regulatório da oferta | | `status_events` | array | Histórico de status (`status`, `event_datetime`) | | `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. Ausente quando não preenchido | | `lead_coordinator` | JSON | Dados do coordenador líder. Ausente quando não preenchido | | `maturity_date` | string | Data de vencimento. Ausente quando não preenchida | | `original_number_of_quotas` | float | Quantidade original de cotas. Ausente quando não preenchida | 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 | Número sequencial da série de emissão dentro da sub classe (1, 2, 3...). Não se repete na mesma sub classe | ## 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 | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------------------- | | 400 | `QIT000004` | A classe de fundo não é gerida pela gestora | | 404 | `QOF000007` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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**. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | A oferta precisa ser de um fundo da gestora. URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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 | | `number_of_quotas` | number | Quantidade de cotas do boletim. Mínimo 0 | Não | | `start_date` | string | Data inicial do boletim (`YYYY-MM-DD`). Se omitida, usa a data atual (UTC) | Não | | `maturity_date` | string | Data de vencimento do boletim (`YYYY-MM-DD`). Não pode estar no passado | 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": "send_to_generate_document", "original_number_of_quotas": 500, "original_subscription_note_value": 50000.00, "issued_number_of_quotas": 0, "remaining_subscription_note_value": 50000.00, "total_assignment_value": 0.00, "start_date": "YYYY-MM-DD", "transaction_type": "ted", "signature_method": "certifiqi", "investor": { "distributor": { "distributor_key": "UUID", "document_number": "11.222.333/0001-81", "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" }, { "status": "send_to_generate_document", "event_datetime": "YYYY-MM-DD HH:MM:SS" } ] } ``` A descrição detalhada dos objetos **[Quota Offering](/documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas#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)**. O boletim é criado no status `send_to_generate_document` quando a oferta gera o documento internamente (`subscription_note_generation_type: internal`) e em `pending_manual_inputs` quando a geração é externa. `maturity_date` e `original_number_of_quotas` só aparecem na resposta quando preenchidos. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ---------------------------------------------------------------------------------------------------- | | 400 | `QIT000004` | A oferta não é de um fundo da gestora | | 400 | `QOF000020` | `maturity_date` está no passado | | 400 | `QOF000026` | O valor do boletim é maior que o valor disponível da oferta | | 400 | `QOF000043` | Cadastro do investidor não encontrado | | 400 | `QOF000046` | `transaction_type` diferente de `ted` ou `b3` | | 400 | `QOF000047` | A classificação do investidor não permite subscrever a oferta | | 400 | `QOF000076` | O investidor já tem dois boletins ativos nessa oferta | | 400 | `QOF000082` | O cadastro do investidor está desatualizado | | 400 | `QOF000090` | O investidor já tem um boletim ativo sem assinatura na série da oferta | | 400 | `QOF000103` | O investidor não possui grupo de signatários (ou o `signer_group_key` não existe) | | 400 | `QOF000104` | A oferta é exclusiva e o investidor não está entre os investidores permitidos | | 400 | `QOF000130` | O investidor está com o cadastro não operacional | | 404 | `QOF000017` | Investidor não encontrado | | 404 | `QOF000019` | Oferta de cotas não encontrada | | 404 | `QOF000039` | A oferta não está ativa, está vencida ou não tem valor restante | | 404 | `QOF000053` | `transaction_type` é `b3` e a classe de fundo não tem conta B3 cadastrada | | 404 | `QOF000073` | `signature_method` não encontrado | | 409 | `QOF000025` | O investidor já tem um boletim aguardando assinatura na série da oferta | | 409 | `QOF000152` | A oferta tem um aditamento aguardando aprovação | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Recuperando Cotas Públicas URL: /documentation/iaas/passivo/fundos/cotas_publicas Retorna os valores de cota aprovados e públicos das séries de emissão, por data de referência. É uma consulta pública: não exige chave de API nem assinatura da requisição. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------------ | --------------------------------- | | Público | `api.qidtvm.com.br` | Nenhuma (não exige chave de API) | O host público atende apenas **produção**. URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /public_dash/mark_to_market/fund_quota/mark_to_markets MÉTODO GET STATUS 200 ### Query Params | Parâmetro | Tipo | Descrição | |-----------------------------|----------|---------------------------------------------------------------------------------------| | `internal_codes` | list | Lista de códigos internos da série de emissão (separados por vírgula ou com o parâmetro repetido) | | `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 | Itens por página: de 1 a 400 (default 10) | | `page` | int | Página, a partir de 0 (default 0) | Só são retornados valores de cota com status aprovado e marcados como públicos. :::caution 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": "11.222.333/0001-81", "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": "11.222.333/0001-81", "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 | ## Erros | Status | Código | Quando acontece | | ------ | ------ | ------------------------------------------------------------------ | | 400 | — | `limit` fora do intervalo de 1 a 400, `page` negativo ou data em formato inválido | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 nos ambientes de 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. | :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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. ```text 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). ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------- | | 400 | `QIT000004` | O fundo não é da gestora da integração | | 404 | `QTA000002` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consultar Pedido de Resgate por chave URL: /documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave Retorna um pedido de resgate de um investidor pela chave. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /quota/investor/INVESTOR_KEY/redemption_request/REDEMPTION_REQUEST_KEY MÉTODO GET STATUS 200 A gestora só consulta pedidos de resgate de fundos dela. ## Responses Caso 01: Consulta bem-sucedida ```json { "redemption_request_key": "UUID", "redemption_request_type": "gross_redemption_value", "status": "quoted", "quotation_date": "2025-01-15", "payment_date": "2025-01-16", "payment_method": "regular", "request_datetime": "2025-01-14T13:05:00Z", "redemption_request_data": { "gross_redemption_value": 1000.0 }, "processed_value": 1000.0, "ir_value": 2.78, "iof_value": 0.0, "investor": { "investor_key": "UUID", "name": "INVESTIDOR EXEMPLO", "person_type": "natural_person", "document_number": "969.698.790-03", "distributor": { "distributor_key": "UUID", "document_number": "11.222.333/0001-81", "name": "DISTRIBUIDORA EXEMPLO", "account_data": {} } }, "issuance_serie": { "issuance_serie_key": "UUID", "name": "SERIE 1", "sub_class": { "name": "COTA SÊNIOR", "sub_class_key": "UUID", "subordination_level": 1, "fund_class": { "name": "FUNDO EXEMPLO", "fund_class_key": "UUID", "document_number": "11.222.333/0001-81" } } }, "payments": [ { "payment_key": "UUID", "origin_key": "UUID", "total_value": 997.22, "payment_type": "redemption.investor", "payment_date": "2025-01-16", "status": "paid" } ], "status_events": [ { "status": "pending_quote", "event_datetime": "2025-01-14T13:05:00Z" }, { "status": "quoted", "event_datetime": "2025-01-15T21:00:00Z" } ] } ``` ### Redemption Request {#redemption_request} | Campo | Tipo | Descrição | | ------------------------- | ------ | ---------------------------------------------------------------------------- | | `redemption_request_key` | string | Chave única do pedido de resgate | | `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 de cotização | | `payment_date` | string | Data de pagamento | | `payment_method` | string | `regular` ou `b3` | | `request_datetime` | string | Data e hora da criação do pedido (UTC) | | `redemption_request_data` | object | Valores enviados na criação (ex.: `gross_redemption_value`, `net_value`) | | `processed_value` | float | Valor processado do resgate | | `ir_value` | float | IR do resgate | | `iof_value` | float | IOF do resgate | | `investor` | object | Investidor: `investor_key`, `name`, `person_type`, `document_number` e `distributor` | | `issuance_serie` | object | Série de emissão, com `sub_class` e `sub_class.fund_class` | | `payments` | array | Pagamentos gerados (investidor, IR, IOF): `payment_key`, `origin_key`, `total_value`, `payment_type`, `payment_date`, `status`, `status_events` | | `status_events` | array | Histórico de status: `status` e `event_datetime` (UTC) | | `cancellation_data` | object | Dados do cancelamento, só quando o pedido foi cancelado | ### 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 posição remanescente | | `net_value_redemption` | Resgate por valor líquido | ### Redemption Request Status {#redemption_request_status} | Enumerador | Descrição | | ----------------------------------- | ---------------------------------------------- | | `created` | Criado | | `pending_manager_approval` | Aguardando aprovação da gestora | | `pending_quote` | Pendente de cotização | | `processing_quotation` | Cotização em processamento | | `pending_quotation_date_input` | Aguardando definição da data de cotização | | `processing_issuance_serie_impacts` | Processando impactos na série | | `quoted` | Cotizado | | `canceled` | Cancelado | | `reprocessed` | Reprocessado | ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ----------------------------------------------------- | | 400 | `QIT000004` | O pedido de resgate não é de um fundo da gestora | | 404 | `QTA000036` | Pedido de resgate não encontrado para o investidor | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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** de uma **classe de fundo** da gestora (`fund_class_key`), com paginação e filtros opcionais. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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`. | | `status` | array de strings | opcional | Um ou mais status do pedido. Repita o parâmetro para enviar mais de um. | | `quotation_date` | string | opcional | Filtra pela data de cotização (`YYYY-MM-DD`). | | `investor_name` | string | opcional | Parte do nome do investidor (sem diferenciar maiúsculas). | | `investor_document_number` | string | opcional | Filtra pelo documento do investidor, no mesmo formato em que foi cadastrado (com pontuação). | | `request_from_datetime` | string (date-time) | opcional | Pedidos com data/hora de solicitação maior ou igual ao valor, no formato `YYYY-MM-DDTHH:MM:SSZ` (UTC). | | `request_to_datetime` | string (date-time) | opcional | Pedidos com data/hora de solicitação menor ou igual ao valor, no formato `YYYY-MM-DDTHH:MM:SSZ` (UTC). | ```text title="Exemplo de chamada" GET /quota/fund_class/{fund_class_key}/redemption_requests?page=0&limit=50&investor_document_number=969.698.790-03 ``` ## Response STATUS 200 Cada item de `data` é o objeto **Redemption Request** completo, descrito em [Consultar Pedido de Resgate por chave](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request) — lá estão também os [tipos](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request_type) e os [status](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request_status). ```json title="Response Body (resumido)" { "data": [ { "redemption_request_key": "UUID", "redemption_request_type": "number_of_quotas", "status": "quoted", "quotation_date": "2024-06-15", "payment_date": "2024-06-18", "payment_method": "regular", "request_datetime": "2024-06-10T14:00:00Z", "redemption_request_data": { "number_of_quotas": 500.0 }, "processed_value": 5250.5, "ir_value": 0.0, "iof_value": 0.0 } ], "limit": 20, "page": 0, "is_last_page": true } ``` | Campo | Tipo | Descrição | | -------------- | ------- | ---------------------------------- | | `data` | array | Pedidos de resgate | | `limit` | integer | Itens por página | | `page` | integer | Página retornada | | `is_last_page` | boolean | `true` quando não há mais páginas | Um valor de `status` que não existe não gera erro: a consulta apenas não encontra pedidos. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------ | | 400 | `QIT000001` | Data ou data/hora em formato inválido | | 400 | `QIT000004` | O fundo não é da gestora | | 404 | `QTA000002` | Classe de fundo não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. A lista é ordenada por fundo, subclasse, série e data de cotização (mais recente primeiro). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------- | | Gestora | `manager-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /quota/investor/{investor_key}/redemption_requests MÉTODO GET Para a gestora, a consulta retorna apenas pedidos em fundos dela, e só de investidores aos quais ela está vinculada. ### 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`. | | `status` | array de strings | opcional | Um ou mais status do pedido. Repita o parâmetro para enviar mais de um. | | `quotation_date` | string | opcional | Filtra pela data de cotização no formato `YYYY-MM-DD`. | | `fund_class_document_number` | string | opcional | Filtra pelo CNPJ da classe de fundo. | | `request_from_datetime` | string (date-time) | opcional | Pedidos com data/hora de solicitação maior ou igual ao valor, no formato `YYYY-MM-DDTHH:MM:SSZ` (UTC). | | `request_to_datetime` | string (date-time) | opcional | Pedidos com data/hora de solicitação menor ou igual ao valor, no formato `YYYY-MM-DDTHH:MM:SSZ` (UTC). | ```text 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 Cada item de `data` é o objeto **Redemption Request** completo, descrito em [Consultar Pedido de Resgate por chave](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request) — lá estão também os [tipos](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request_type) e os [status](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave#redemption_request_status). ```json title="Response Body (resumido)" { "data": [ { "redemption_request_key": "UUID", "redemption_request_type": "number_of_quotas", "status": "quoted", "quotation_date": "2024-06-15", "payment_date": "2024-06-18", "payment_method": "regular", "request_datetime": "2024-06-10T14:00:00Z", "redemption_request_data": { "number_of_quotas": 500.0 }, "processed_value": 5250.5, "ir_value": 0.0, "iof_value": 0.0 } ], "limit": 20, "page": 0, "is_last_page": true } ``` | Campo | Tipo | Descrição | | -------------- | ------- | ---------------------------------- | | `data` | array | Pedidos de resgate | | `limit` | integer | Itens por página | | `page` | integer | Página retornada | | `is_last_page` | boolean | `true` quando não há mais páginas | Um valor de `status` que não existe não gera erro: a consulta apenas não encontra pedidos. ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------ | | 400 | `QIT000001` | Data ou data/hora em formato inválido | | 400 | `QIT000004` | A gestora não está vinculada ao investidor | | 404 | `QTA000021` | Investidor não encontrado | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Criar Pedido de Resgate URL: /documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate Cria um pedido de resgate de cotas de um investidor em uma série de emissão. Fundos de condomínio fechado não aceitam pedido de resgate. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------------------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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", "gross_redemption_value": 1000.0, "payment_method": "regular", "disbursement_account_key": "UUID", "quotation_date": "2025-01-15" } ``` :::caution Atenção O campo **redemption_request_type** define qual campo de valor deve ser enviado. Envie **somente** esse campo; mandar um campo de outro tipo devolve `QTA000025`. - `gross_redemption_value`: envie `gross_redemption_value`. - `remaining_application_value`: envie `remaining_application_value`. - `number_of_quotas`: envie `number_of_quotas`. - `net_value_redemption`: envie `net_value`. O campo **disbursement_account_key** indica uma conta específica do investidor para o pagamento. Sem ele, a conta principal do investidor é usada. ::: ### Body params | Campo | Tipo | Descrição | Obrigatório | | ----------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------- | | `issuance_serie_key` | string | Chave única 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 | Condicional | | `net_value` | float | Valor líquido do resgate, já descontados IR e IOF | Condicional | | `remaining_application_value` | float | Valor restante da aplicação | Condicional | | `number_of_quotas` | float | Quantidade de cotas a resgatar | Condicional | | `disbursement_account_key` | string | Chave da conta bancária do investidor que receberá o pagamento | Não | | `quotation_date` | string | Data de cotização do resgate (`yyyy-mm-dd`). Precisa ser dia útil e respeitar os prazos da série | Não | | `payment_method` | string | Método de pagamento: `regular` **(default)** ou `b3` | Não | | `reference_date` | string | Data de referência do resgate (`yyyy-mm-dd`) | Não | | `redemption_request_key` | string | Chave (UUID) a usar no pedido, se você quiser defini-la | Não | Campos fora desta lista são recusados com `QIT000001`. ### 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 A resposta traz o pedido de resgate criado, no mesmo formato da [consulta por chave](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave). Guarde o `redemption_request_key`. ```json title='Response Body (resumido)' { "redemption_request_key": "UUID", "redemption_request_type": "gross_redemption_value", "status": "pending_quote", "quotation_date": "2025-01-15", "payment_date": "2025-01-16", "payment_method": "regular" } ``` ## Erros | Status | Código | Quando acontece | | ------ | ----------- | --------------------------------------------------------------------------------------------------- | | 400 | `QTA000025` | Falta o campo de valor do tipo escolhido, ou foi enviado o campo de outro tipo | | 400 | `QTA000190` | Resgate por valor líquido de até R$ 10,00 (exceto investidor isento) | | 400 | `QTA000241` | Já existe um pedido de resgate por valor remanescente no mesmo dia | | 400 | `QTA000242` | Valor disponível insuficiente por causa de cotas bloqueadas | | 400 | `QTA000176` | `quotation_date` não é dia útil | | 400 | `QTA000182` | `quotation_date` anterior à data contábil do fundo | | 400 | `QTA000186` | `quotation_date` anterior à data mínima de cotização da série | | 400 | `QTA000296` | Investidor do tipo `nominee` | | 400 | `QIT000004` | A gestora não está vinculada ao investidor | | 404 | `QTA000015` | Série de emissão não encontrada | | 404 | `QTA000021` | Investidor não encontrado | | 404 | `QTA000180` | O fundo é de condomínio fechado e não aceita pedido de resgate | | 404 | `QTA000239` | O patrimônio do investidor não cobre todos os resgates pedidos | | 404 | `QTA000243` | O investidor não tem aplicação resgatável nessa série | | 422 | `QTA000357` | Movimentação bloqueada: a série está com valor de cota zerado ou negativo | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. :::caution 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**. A adesão é criada já no status `active`. ## 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" } ``` | Campo | Tipo | Descrição | Caracteres | Obrigatório | |----------------------|--------|---------------------------------------------------------------------------------------------|------------|-------------| | `issuance_serie_key` | string | Chave da série de emissão a qual o investidor aderiu | 36 | Sim | | `signature_method` | string | Método de assinatura usado: `opt_in` ou `external` | até 100 | Sim | | `opt_in_hash` | string | Hash do opt-in. Obrigatório quando `signature_method` é `opt_in` | até 500 | Não | | `document_b64` | string | Termo assinado codificado em base64. Obrigatório quando `signature_method` é `external` | - | Não | | `signer_group_key` | string | Chave do grupo de signatários do investidor. Se omitido, usa o grupo padrão do investidor | 36 | Não | :::caution 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" } ``` ## Erros | Status | Código | Quando acontece | | ------ | ----------- | --------------------------------------------------------------------------------------- | | 400 | `IAD000027` | A classificação do investidor não permite aderir à série | | 400 | `IAD000037` | `signature_method` é `opt_in` e `opt_in_hash` não foi enviado | | 400 | `IAD000038` | `signature_method` é `external` e `document_b64` não foi enviado | | 400 | `IAD000039` | Já existe uma adesão do investidor para essa série de emissão | | 400 | `IAD000051` | O investidor não possui grupo de signatários (ou o `signer_group_key` não existe) | | 400 | `IAD000054` | O investidor está não operacional | | 400 | `QIT000011` | A integração não é a distribuidora do investidor | | 404 | `IAD000012` | Investidor não encontrado | | 404 | `IAD000018` | Série de emissão não encontrada | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. ### 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**. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ------------------------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Adesões | A série de emissão precisa ser de um fundo da gestora (ou, para a consultoria, de um fundo em que ela tenha essa permissão). URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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", "signer_group_key": "UUID" } ``` ### 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. Se omitido: `qi_sign` para pessoa física e `certifiqi` para pessoa jurídica | - | Não | | `signer_group_key` | string | Chave do grupo de signatários do investidor. Se omitido, usa o grupo de signatários padrão do investidor | 36 | 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 - Se todos os documentos exigidos pela série já existirem e estiverem vigentes, a adesão é criada direto no status `active`. - Caso contrário, a adesão é criada no status `pending_documents` e permanece assim até que os documentos exigidos sejam gerados e assinados. - Se o investidor já tiver uma adesão `active`, `pending_documents` ou `pending_batch_close` para a mesma série de emissão, a requisição é rejeitada com `IAD000014`. ::: ## Erros | Status | Código | Quando acontece | | ------ | ----------- | ------------------------------------------------------------------------------------------------ | | 400 | `IAD000027` | A classificação do investidor (geral, qualificado, profissional) não permite aderir à série | | 400 | `IAD000042` | O cadastro do investidor está pendente de atualização | | 400 | `IAD000045` | O investidor não possui suitability ativo | | 400 | `IAD000051` | O investidor não possui grupo de signatários (ou o `signer_group_key` informado não existe) | | 400 | `IAD000054` | O investidor está não operacional | | 400 | `QIT000011` | A série de emissão não pertence a um fundo da gestora | | 403 | `IAD000049` | A consultoria não tem a permissão de criar adesões no fundo da série | | 404 | `IAD000012` | Investidor não encontrado (na `manager-api`, hoje a resposta vem como `IAD000010`) | | 404 | `IAD000018` | Série de emissão não encontrada | | 404 | `IAD000040` | `signature_method` não encontrado | | 409 | `IAD000014` | O investidor já tem adesão ativa ou aguardando assinatura para essa série de emissão | | 409 | `IAD000057` | O investidor já possui um vínculo com essa série de emissão | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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, os lançamentos do período 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. | Os lançamentos listados são os de data contábil **posterior** à Data de Início e até a Data Final, inclusive. Os lançamentos da própria Data de Início já estão no saldo inicial. :::caution É 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. Numa solicitação avulsa, sem isso a solicitação é recusada com a mensagem "Não existe contabil na data ...". Numa entrega por rotina essa checagem não acontece na solicitação: a geração falha e o relatório fica com `status` `failed`. ::: :::caution 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` | A data do nome é a `reference_date` da solicitação, e não a `end_date`. Se a solicitação não informar `reference_date`, vale a data da geração do arquivo, no horário de Brasília. ## 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. | Em entregas configuradas em inglês, os rótulos, os cabeçalhos da tabela, os nomes das contas e as descrições vêm traduzidos. :::caution 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** — lançamentos de mesma data, contrapartida, descrição, tipo e lado (débito ou crédito) vêm somados em uma única linha. 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` | string | `"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 quatro 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; - **contratos** (`contract`, `financing_contract`, `debt_acknowledgment`) — uma linha por parcela do contrato; - **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](/downloads/manual_relatorios_qi_tech.pdf) — revisão 3, outubro 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 | `"11.222.333/0001-81"` | 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 | `"22.222.222/0001-91"` | 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 | `"33.333.333/0001-91"` | 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. Vazio para contratos. | | `borrower_document` | string | `"969.698.790-03"` | 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 do **ativo** na data de aquisição, em reais. Repetido em todas as parcelas da mesma operação. Para operações de crédito e contratos, é o valor contábil: a soma das parcelas trazidas a valor presente pela taxa nominal da operação (`nominal_rate`) na data de aquisição. Ele difere do valor pago pelo fundo quando houve ágio ou deságio na aquisição; o valor pago é a soma de `installment_purchase_value` das parcelas. Para direitos creditórios descontados e títulos privados, é o valor pelo qual o ativo foi adquirido. | | `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. Para títulos privados, repete o `maturity_date`. | | `issue_date` | texto de data | `2026-07-28` | Data de emissão do contrato. Para direitos creditórios descontados e contratos, 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. | | `asset_key` | string | `"1a2b3c40-0001-4aaa-9111-000000000101"` | Chave interna do ativo gerada pela QI Tech (UUID). | | `asset_external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo. Em operações de crédito, `external_id` pode trazer o identificador da parcela; `asset_external_id` é sempre o do ativo. | :::info Colunas adicionais 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. Com a opção `original_face_value`, traz também a coluna `original_face_value` (valor de face original da parcela; vazia para direitos creditórios descontados e títulos privados). ::: --- # 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**; - **contratos** — uma linha por **parcela**. :::tip Também em PDF Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](/downloads/manual_relatorios_qi_tech.pdf) — revisão 3, outubro 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`, `check`, `promissory_note`. Contratos: `contract`, `financing_contract`, `debt_acknowledgment`. Um tipo fora dessas listas faz o relatório falhar. | | `fund_class_key` | só para direitos creditórios descontados e contratos | 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` | :::info 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`). Para contratos, saem os contratos com status `failed` ou `canceled`. - 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 | `"11.222.333/0001-81"` | 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 | `"22.222.222/0001-91"` | 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 | `"33.333.333/0001-91"` | CNPJ do **cedente**. Mesma observação da coluna anterior. | | `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor ou do sacado. Vazio para contratos. | | `borrower_document` | string | `"969.698.790-03"` | 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 e contrato). | | `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** (para contratos, a data de aquisição da cessão). | | `purchase_date` | data | `2026-07-29` | Data de aquisição. Nesta visão, traz a **data da cessão** (para contratos, a data de aquisição da cessão). | | `total_duration` | número | `30` | Prazo total, em dias. | | `present_duration` | número | `30` | Nesta visão, repete o `total_duration`. | | `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"`. Para operações de crédito e direitos creditórios descontados, vem da configuração de cessão; para contratos, do cadastro do contrato. | | `asset_external_id` **ou** `invoice_number` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Operação de crédito e contrato: 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 nos arquivos de operações de crédito e de contratos** — no de direitos creditórios descontados a coluna não é emitida. | | `installment_number` | string | `"1"` | Número da parcela. **Só existe no arquivo de contratos**, sempre como última coluna. | ## 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. | | `disbursement_target_document_number` | CPF ou CNPJ do destinatário do desembolso. | | `disbursement_date` | Data do desembolso. | | `borrower_birthdate` | Data de nascimento do devedor (pessoa natural). | | `benefit_type` | Tipo de benefício da primeira garantia da operação. Habilitada pela opção `benefit_number`. | :::info Como pedir as colunas opcionais A habilitação é feita pela QI DTVM 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` | :::caution 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"` | Tipo do documento: `ccb`, `duplicata_mercantil`, `duplicata_servicos`, `discounted_contract`, `cte`, `check`, `promissory_note`, `contract`, `invoice` (nota fiscal do recebível), `legal_fees_contract`, `disbursement_receipt` ou `vehicle_reservation_receipt`. | | `document_url` | string | `"https://"` | Link de download direto do arquivo. O download chega com o nome `{document_type}-{asset_external_id}.pdf` (caracteres fora de `A-Z`, `a-z`, `0-9`, `.`, `_` e `-` viram `_`). 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. | Os movimentos considerados são os de data contábil **posterior** à Data de Início e até a Data Final, inclusive. Os lançamentos da própria Data de Início já estão no saldo inicial. :::caution É 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. Numa solicitação avulsa, sem isso a solicitação é recusada com a mensagem "Não existe contabil na data ...". Numa entrega por rotina essa checagem não acontece na solicitação: a geração falha e o relatório fica com `status` `failed`. ::: :::caution 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` | A data do nome é a `reference_date` da solicitação, e não a `end_date`. Se a solicitação não informar `reference_date`, vale a data da geração do arquivo, no horário de Brasília. ## Conteúdo da Planilha ### Cabeçalho do Fundo Apresentado nas primeiras linhas da planilha, com o rótulo na coluna A e o valor na coluna B. Os rótulos abaixo são os textos literais da planilha, com os dois-pontos: | 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` | Em entregas configuradas em inglês, os rótulos, os cabeçalhos da tabela e os nomes das contas vêm traduzidos. :::info 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. Além das contas e grupos do plano de contas, a tabela traz duas linhas de total: `TOTAL DO ATIVO` (`3.9.9.99.99-3`, soma dos grupos 1 e 3) e `TOTAL DO PASSIVO` (`9.9.9.99.99-5`, soma dos grupos 4, 6, 7, 8 e 9). | 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). | | `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 os 31 primeiros caracteres do nome do fundo — o limite do Excel para nome de aba) | | 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. | | `Identificador do Pix` | string | `"E99999999202607291200ABCDEFGHIJK"` | Identificador fim a fim (`end_to_end_id`) da transação Pix. Vazio quando a movimentação não é um Pix. | | `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` | :::caution 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 | `"11.222.333/0001-81"` | 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 DTVM (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-transacao). | | `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. | | `outgoing_ted_fee` | Tarifa de TED enviada. | | `outgoing_pix_fee` | Tarifa de Pix enviado. | | `incoming_pix_fee` | Tarifa de recebimento de Pix. Apesar do prefixo `incoming`, é uma saída de caixa. | | `incoming_reversal` | Estorno recebido de uma transação enviada. | | `incoming_pix_reversal` | Devolução recebida de um Pix enviado. | | `outgoing_pix_block` | Bloqueio de valor relacionado a Pix. | | `incoming_pix_unblock` | Desbloqueio de valor bloqueado por Pix. | --- # 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 três 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; - **títulos** (`commercial_paper`, `cri`, `cra`, `debenture`) — uma linha por parcela do cronograma do título, ou uma única linha quando o título não tem cronograma de 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](/downloads/manual_relatorios_qi_tech.pdf) — revisão 3, outubro 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 Entrega de abertura Quando o relatório é entregue no momento de **abertura**, a data de referência da entrega é o **dia útil imediatamente anterior** ao dia do fechamento. Essa mesma data vale para o conteúdo do arquivo (todas as naturezas de ativo), para o nome do arquivo e para o `reference_date` do [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega). ::: ## 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 | `"11.222.333/0001-81"` | CNPJ da classe de fundo. | | `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora do ativo. | | `originator_document_number` | string | `"22.222.222/0001-91"` | CNPJ do originador. | | `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente. | | `assignor_document_number` | string | `"33.333.333/0001-91"` | CNPJ do cedente. | | `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor (tomador do crédito) ou do sacado. | | `borrower_document_number` | string | `"969.698.790-03"` | CPF ou CNPJ do devedor/sacado. | | `asset_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"` | Tipo do ativo. Determina qual natureza originou a linha. Para títulos: `commercial_paper`, `cri`, `cra` ou `debenture`. | | `has_assignor_coobligation` | booleano | `False` | Indica se há coobrigação do cedente. Para títulos, sempre `False`. | | `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 da linha. Para operação de crédito, é o identificador externo da **parcela** quando ela tem um; caso contrário, o do ativo. Para as demais naturezas, é o identificador externo do ativo. | | `asset_external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo. Igual em todas as linhas de um mesmo 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 e para títulos, é 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`. Para títulos, `pre_fixed` ou `post_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 `-`; para títulos, `0`. | | `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`. | :::info Como cruzar as linhas de um mesmo ativo As parcelas de uma operação de crédito repetem `asset_key`, `asset_external_id` e `contract_number`, e variam em `installment_number`, `installment_maturity_date`, `installment_purchase_value`, `principal_value` e `face_value` — e também em `external_id`, quando as parcelas têm identificador externo próprio. Use `asset_key` ou `asset_external_id` para agrupar. 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 três naturezas de ativo: - **operações de crédito** (ex: CCB); - **direitos creditórios descontados** (ex: duplicatas); - **títulos** (`commercial_paper`, `cri`, `cra`, `debenture`). 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](/downloads/manual_relatorios_qi_tech.pdf) — revisão 3, outubro 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`. Sem `end_date`, é o único dia do relatório; com `end_date`, é o primeiro dia do intervalo. | | `end_date` | não | Data final do intervalo, no formato `AAAA-MM-DD`, igual ou posterior a `reference_date`. Quando informada, o relatório traz os eventos de `reference_date` até `end_date`, incluindo os dois dias. | :::info Intervalo de datas O intervalo está disponível na solicitação pelo Portal do Gestor: em **Carteira > Gerar Relatório**, escolha **Liquidados e baixados** e informe **Data de Início** e **Data de Fim**. O arquivo chega por e-mail com os eventos do intervalo inteiro. Nas rotinas de entrega, o relatório traz sempre um único dia: a data de referência da entrega. ::: ## 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`, com a `reference_date` — num intervalo, o primeiro dia. | ## O que o relatório traz - Os eventos de pagamento cuja data contábil é a data de referência — ou, com `end_date`, qualquer data de `reference_date` a `end_date`, incluindo as duas. - 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. Num intervalo, a coluna `reference_date` traz a data contábil de cada evento, e não a data de referência pedida. :::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 Entrega de abertura Quando o relatório é entregue no momento de **abertura**, a data de referência da entrega é o **dia útil imediatamente anterior** ao dia do fechamento. Essa mesma data vale para o conteúdo do arquivo (todas as naturezas de ativo), para o nome do arquivo e para o `reference_date` do [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega). ::: ## 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 | `"11.222.333/0001-81"` | CNPJ da classe de fundo. | | `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora do ativo. | | `originator_document_number` | string | `"22.222.222/0001-91"` | CNPJ do originador. | | `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente. | | `assignor_document_number` | string | `"33.333.333/0001-91"` | CNPJ do cedente. | | `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor (tomador do crédito) ou do sacado. | | `borrower_document_number` | string | `"969.698.790-03"` | CPF ou CNPJ do devedor/sacado. | | `asset_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"` | Tipo do ativo. Determina qual natureza originou a linha. Para títulos: `commercial_paper`, `cri`, `cra` ou `debenture`. | | `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"` | Para operação de crédito, identificador externo da **parcela** paga, conforme registrado no evento de pagamento — vem `-` quando o evento não traz esse identificador. Para as demais naturezas, identificador externo do ativo. | | `asset_external_id` | string | `"10a20b30-0003-4bbb-9222-000000000203"` | Identificador externo do ativo. Use este campo, e não `external_id`, para cruzar com os outros relatórios por 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. Títulos: `-`. | | `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"`, `"extension"`, `"unperformed"`, `"reactivation"`, `"installment_payment_reversal"`, `"asset_payment_reversal"`, `"bankslip"` | Natureza do evento que originou o pagamento — por exemplo, liquidação, substituição, recompra, prorrogação 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 e para títulos, 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, `-`. Para títulos, é a parcela registrada no evento de pagamento. | | `end_to_end_id` | string | `"-"` | Identificador *end-to-end* da transação de pagamento, quando registrado no evento; 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 DTVM. 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](/downloads/example_reports.zip) O pacote contém um arquivo de cada relatório, com o mesmo layout dos arquivos gerados em produção e dados fictícios. Todos descrevem o mesmo fundo (`FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA`) na mesma data de referência (`2026-07-29`). Os relatórios de posição — composições de carteira, cotas, caixa e XMLs ANBIMA — fecham entre si: patrimônio líquido, saldo de caixa e posição por classe de ativo são os mesmos em todos eles. O balancete e o razão contábil usam um conjunto próprio de lançamentos, só para ilustrar o layout. ## 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** é o nome-base de relatórios cadastrado para a classe de fundo, em minúsculas e sem acentos (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. Se você precisa de um prefixo diferente, fale com o time de integração. Entregas configuradas em inglês recebem o sufixo `_EN` antes da extensão. Há quatro exceções ao padrão: o `wallet_composition_by_composition` é entregue como `wallet_composition` (sem o sufixo do modelo); o `xml_5_by_composition` segue o nome do padrão ANBIMA, `FD{CNPJ do fundo, só dígitos}_{AAAAMMDD}.xml`; 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 `reference_date` informada na rotina; quando a rotina não informa `reference_date`, é a data de geração do arquivo, no horário de Brasília. A [Conciliação Consolidada](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets) aceita, opcionalmente, um intervalo (`reference_date` / `end_date`); o nome do arquivo leva a `reference_date`, o primeiro dia do intervalo. ::: ## 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 | :::info Delimitador e separador decimal são configuráveis Se o seu processo exigir `;` como delimitador ou `,` como separador decimal, a QI DTVM pode configurar isso por fundo na entrega. Sem configuração específica, valem os padrões da tabela acima. As exceções são o `quota_mec` em CSV, que usa `;` por definição do relatório, e o `assignment_documents`, que usa sempre `,` como delimitador e `.` como separador decimal. ::: ## 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. | Os relatórios do momento de abertura têm como data de referência o **dia útil anterior** à data contábil que está sendo aberta — é essa data que aparece no nome do arquivo. 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 entregues no destino definido na configuração de cessão. 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 DTVM 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`. O valor não é conferido na solicitação: qualquer outro formato, ou `csv` com mais de uma classe de fundo, faz a geração do relatório falhar. | | `issuance_serie_key` | não | Restringe o arquivo a uma única série de emissão. | :::caution É 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. Nos dois formatos, XLSX e CSV, as datas vêm no formato `DD/MM/AAAA` e os campos sem valor vêm como `0`. :::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_quotas`, `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 | `"11.222.333/0001-81"` | 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. | | `Total de Cotas` | número | `10000.00000` | Quantidade total de cotas da série, calculada como `PL de Fechamento / Cota de Fechamento`. É uma quantidade de cotas, não um valor 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). | :::caution 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. ::: :::caution 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. ::: :::info CPF e CNPJ destes PDFs têm dígito verificador válido Para não reprovar em validações de lastro que conferem dígito verificador, os CPFs e CNPJs impressos nestes PDFs têm DV válido, e as chaves de acesso de NF-e e CT-e também. Todos são fictícios. Consequência: o `borrower_document` do `assignment_assets_wallet_composition` do pacote de exemplos 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 Chame `POST /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment`. 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 Chame `POST .../assignment/{assignment_external_id}/asset`, uma vez por ativo. 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 ``` Envie o arquivo com `POST .../assignment/{assignment_external_id}/asset/{asset_external_id}/document`: ```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 [Envio do Lastro do Ativo](/documentation/iaas/negociacao_recebiveis/asset/documents). :::info 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 Chame `PUT .../assignment/{assignment_external_id}` com o status de encerramento: ```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 entregue no destino definido na configuração de cessão, com o nome: ```text {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. ::: :::caution 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.** O prazo conta a partir 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 nome do arquivo baixado não identifica o formato com segurança.** O download vem com `Content-Disposition: attachment; filename="{document_type}-{asset_external_id}.pdf"` (acentos são removidos e os demais caracteres fora de `A-Z a-z 0-9 . _ -` viram `_`). Não infira o tipo pelo nome nem pelo `Content-Type` — use a coluna `document_type` do CSV. **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** — `Erro: Credenciais não configuradas corretamente.` —, 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. :::info "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, contratos, 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. | :::caution É 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' = {reference_date}"`, com a data informada no lugar de `{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` | :::info 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 **ágio ainda não diferido em emissões ou em direitos creditórios descontados**: nas seções `EMISSÕES` e `DC DESCONTADOS` o `Valor D0 (R$)` é apurado pelo valor contábil, enquanto em `OPERAÇÕES DE CRÉDITO` e `CONTRATOS` ele parte do 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 (as duas colunas trazem o mesmo valor). | | 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. | | Valor esperado de resgate (R$) | Valor de recompra previsto na operação compromissada. Vazio nos títulos que não são compromissadas. | | % 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 vêm em um segundo bloco, também intitulado `EMISSÕES`, com colunas equivalentes em outra ordem: o `Identificador` é o número do contrato, não há a coluna `PDD (%)` e o percentual da seção se chama `% de EMISSÕES`. | 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 justo 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, cheques e notas promissórias). 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`, `CHEQUE`, `NOTA PROMISSÓRIA`. | | 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. | ### `CONTRATOS` Contratos de crédito, contratos de financiamento e confissões de dívida. 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 | `CONTRATO DE CRÉDITO`, `CONTRATO DE FINANCIAMENTO`, `CONFISSÃO DE DÍVIDA`. | | Unidades atuais | Quantidade de contratos em estoque. | | Valor D0 (R$) | Valor justo da posição, líquido de PDD. | | PDD (R$) | Provisão para devedores duvidosos (negativa). | | 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 nos contratos.** | | % de Contratos | Participação da linha no total de contratos. | | % 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`, `FIAGRO`. | | 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 `Tipo de a receber`, `Total a diferir`, `Valor diferido`, `Valor restante`, `Inicio do diferimento`, `Fim do diferimento` e `Data do pagamento`. Aqui o `% do PL` é calculado sobre o `Valor restante`, e é positivo. ### `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. Quando o saldo inicial é zero, a célula traz o valor-sentinela `999999999` (exibido em formato percentual), e não uma variação real. | 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 DTVM 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 | :::caution É 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-e-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 DTVM — 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 DTVM 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. ::: ## Parâmetros da rotina Na entrega pela rotina do fundo, o arquivo é gerado para a `fund_class_key` e a `reference_date` da entrega. Dois parâmetros opcionais podem ser configurados pelo time de integração na rotina — eles **não** são aceitos no download sob demanda pela API: | Parâmetro | Descrição | |-----------|-----------| | `type_fund_code_anbima` | 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` | 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 | Tipo 5: `FD{CNPJ do fundo, só dígitos}_{AAAAMMDD}.xml`, o nome do padrão ANBIMA (sem CNPJ cadastrado, cai no padrão `{nome_resumido_fundo}_xml_5_by_composition_{AAAA-MM-DD}.xml`, que é o do pacote de exemplos). Tipo 401: `{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 `POST /composition/fund_class/{fund_class_key}/report`, informando `report_type` igual a `xml_5_by_composition` ou `xml_401_by_composition`. A resposta traz o arquivo em base64 no campo `document_b64`. Contrato, perfis que têm acesso e erros em [Baixar a Carteira](/documentation/iaas/composicao_carteira/baixar_carteira). ```json title="Request Body" { "composition_type": "final_quota", "report_type": "xml_5_by_composition", "reference_date": "2026-07-29" } ``` :::caution Carteira de validação não gera XML Os dois XMLs não são gerados para a carteira `pre_quota` (resposta **404**, `CMP000026`). A carteira precisa estar em `confirmed`, `pending_confirmation` ou `reproved_by_agent`; em outro status, a resposta é **400** (`CMP000015`). ::: ## 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 Insere um ativo da carteira do fundo num lote em `pending_assets_insertion`. Faça uma requisição por ativo. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/ASSIGNMENT_EXTERNAL_ID/asset MÉTODO POST `ASSIGNMENT_EXTERNAL_ID` é o `external_id` do **lote**, informado na [criação do lote](/documentation/iaas/venda_ativos/assignment/criacao_recompra). O `external_id` do corpo é o do **ativo**. ```json title='Request Body' { "external_id": "7c2d5a10-3f4e-4b8a-9d61-0e2f4a6b8c90", "sale_value": 1234.56 } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `external_id` | string | Identificador do ativo, o mesmo com que ele foi encarteirado. Envie este **ou** `contract_number`. | Até 50 | | `contract_number` | string | Número do contrato do ativo, alternativa ao `external_id`. Aceito para `ccb`, `structured_cci`, `duplicata_servicos`, `duplicata_mercantil` e `cte`. | Até 50 | | `borrower_document_number` | string | Documento do devedor, para desambiguar a busca do ativo | 11 a 18 | | `sale_value` | number | Valor pelo qual o ativo será baixado. Envie este **ou** `calculation_method`. | 2 casas decimais | | `calculation_method` | string | Calcula o valor de venda em vez de informá-lo. Único valor aceito: `current_fair_value` (valor justo contábil atual do ativo). | Até 255 | :::info Regras - O ativo precisa estar **ativo** na carteira do fundo e ser do mesmo tipo de ativo da configuração do lote. - Envie exatamente um entre `external_id` e `contract_number`, e exatamente um entre `sale_value` e `calculation_method`. - Em lotes `assignment_resolution`, o `sale_value` precisa ser igual ao valor de aquisição do ativo (`TRR000053`). ::: ## Response STATUS 201 ```json title='Response Body' { "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10", "asset_resolve_key": "e4a1c9d2-7b3f-4e8a-a5c6-1d2e3f4a5b6c", "asset_status": "pending_wallet_sale" } ``` | `asset_status` | Quando | |-|-| | `pending_wallet_sale` | O preço de venda diverge até 5% do valor justo contábil do ativo. O ativo segue no fluxo. | | `pending_validation` | O preço de venda diverge mais de 5% do valor justo contábil. O ativo fica retido até uma confirmação, que não está disponível na API: alinhe com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). | :::tip Reenvio e duplicidade Em caso de erro, reenvie a requisição. Duplicidade (`TRR000042`) significa que o ativo já está num lote não descartado: não o insira de novo. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ::: ## Erros | Status | Código | Quando acontece | |-|-|-| | 400 | `QIT000001` | Corpo fora do contrato: campo desconhecido ou formato inválido | | 400 | `TRR000050` | Nem `sale_value` nem `calculation_method` foram enviados | | 400 | `TRR000051` | `sale_value` e `calculation_method` enviados juntos | | 400 | `TRR000052` | `calculation_method` diferente de `current_fair_value` | | 400 | `TRR000071` | Nem `external_id` nem `contract_number` foram enviados | | 400 | `TRR000070` | `external_id` e `contract_number` enviados juntos | | 400 | `TRR000072` | O tipo de ativo do lote não aceita `contract_number`: use `external_id` | | 400 | `TRR000021` | O lote não está em `pending_assets_insertion` (já foi encerrado ou descartado) | | 400 | `TRR000029` | Mais de um ativo encontrado: informe `borrower_document_number` ou use `external_id` | | 400 | `TRR000053` | Lote `assignment_resolution` com `sale_value` diferente do valor de aquisição | | 403 | `TRR000049` | O agente não tem acesso a esse fundo ou a esse lote | | 404 | `TRR000006` | Não existe fundo com essa `fund_class_key` | | 404 | `TRR000020` | Lote não encontrado com esse `external_id` | | 404 | `TRR000028` | Ativo não encontrado ativo na carteira do fundo com esse `external_id` | | 404 | `TRR000073` | Ativo não encontrado com esse `contract_number` | | 409 | `TRR000042` | O ativo já está num lote e não foi descartado | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Criação de um lote de recompra URL: /documentation/iaas/venda_ativos/assignment/criacao_recompra Cria o lote (`assignment`) que vai agrupar os ativos a serem recomprados ou vendidos. O lote nasce em `pending_assets_insertion`. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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": "11.222.333/0001-81" } } ``` ### 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. Precisa ser igual à data contábil atual do fundo. | YYYY-MM-DD | | `assignment_configuration_key` | string | Chave da configuração de recompra, fornecida pela QI Tech. Envie esta **ou** `assignment_type`. | 36 | | `assignment_type` | string | Tipo do lote, quando você usa a configuração padrão do fundo para esse tipo: `assignment_repurchase`, `wallet_sale` ou `assignment_resolution`. Envie este **ou** `assignment_configuration_key`. | Até 50 | | `source_account` * | objeto | Conta que fará o pagamento ao fundo | - | :::info Configuração do lote Envie exatamente um entre `assignment_configuration_key` e `assignment_type`. Sem nenhum dos dois a API devolve `TRR000017`; com os dois, `TRR000016`. ::: ## Objeto de source account | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `document_number` * | string | CPF ou CNPJ, com máscara, de quem fará o pagamento ao fundo. Precisa ser um documento válido. | 14 a 18 | ## Response STATUS 201 ```json title='Response Body' { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignment_status": "pending_assets_insertion" } ``` :::tip Reenvio e duplicidade Em caso de erro, reenvie a requisição. Duplicidade (`TRR000015`) significa que o recurso já existe: consulte-o em vez de recriar. Pela `assignor-api`, a consulta é `GET /trade_resolve/fund_class/{fund_class_key}/assignment/{external_id}`; a `manager-api` e a `consultant-api` não expõem essa consulta, então trate `TRR000015` como lote já criado e siga para a [inserção dos ativos](/documentation/iaas/venda_ativos/asset/criacao_recompra). Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ::: ## Erros | Status | Código | Quando acontece | |-|-|-| | 400 | `QIT000001` | Corpo fora do contrato: campo obrigatório ausente, campo desconhecido, formato inválido | | 400 | `TRR000014` | `assignment_date` diferente da data contábil do fundo | | 400 | `TRR000002` | `source_account.document_number` não é um CPF ou CNPJ válido | | 400 | `TRR000016` | `assignment_configuration_key` e `assignment_type` enviados juntos | | 400 | `TRR000017` | Nem `assignment_configuration_key` nem `assignment_type` foram enviados | | 400 | `TRR000019` | A configuração de recompra não está ativa | | 403 | `TRR000049` | O agente não tem acesso a esse fundo ou a essa configuração de recompra | | 404 | `TRR000006` | Não existe fundo com essa `fund_class_key` | | 404 | `TRR000013` | Configuração de recompra não encontrada para o fundo (ou o fundo não tem configuração padrão para o `assignment_type`) | | 404 | `TRR000018` | `assignment_type` não existe | | 409 | `TRR000015` | Já existe um lote com esse `external_id` no fundo | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Encerrar inserção de ativos URL: /documentation/iaas/venda_ativos/assignment/fechamento_recompra Encerra a inserção de ativos de um lote em `pending_assets_insertion`. O lote precisa ter ao menos um ativo não descartado. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Liberada pelo time de integração | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/ASSIGNMENT_EXTERNAL_ID MÉTODO PUT ```json title='Request Body' { "assignment_status": "completed_assets_insertion", "number_of_assets": 2, "total_value": 2469.12 } ``` ### Body Params | Campo | Tipo | Descrição | |-|-|-| | `assignment_status` * | string | Único valor aceito: `completed_assets_insertion` | | `number_of_assets` | number | Quantidade de ativos não descartados que você espera no lote. Se enviada e divergir, a API recusa o encerramento (`TRR000067`). | | `total_value` | number | Soma dos `sale_value` dos ativos não descartados que você espera no lote. Se enviada e divergir, a API recusa o encerramento (`TRR000066`). | ## Response STATUS 200 ```json title='Response Body' { "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignment_status": "completed_assets_insertion" } ``` Em lotes com termo externo, `assignment_status` volta como `pending_signed_term_submission`. Veja [Termo de Recompra](/documentation/iaas/venda_ativos/inicio#4-termo-de-recompra). ## Erros | Status | Código | Quando acontece | |-|-|-| | 400 | `QIT000001` | Corpo fora do contrato: `assignment_status` ausente ou campo desconhecido | | 400 | `TRR000033` | O lote não está em `pending_assets_insertion` | | 400 | `TRR000021` | `assignment_status` diferente de `completed_assets_insertion` | | 400 | `TRR000034` | O lote não tem nenhum ativo não descartado | | 400 | `TRR000067` | `number_of_assets` diferente da quantidade de ativos do lote | | 400 | `TRR000066` | `total_value` diferente da soma dos ativos do lote | | 403 | `TRR000049` | O agente não tem acesso a esse fundo ou a esse lote | | 404 | `TRR000006` | Não existe fundo com essa `fund_class_key` | | 404 | `TRR000020` | Lote não encontrado com esse `external_id`. Pelo `assignor-api`, o mesmo caso volta como `TRR000013`. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 DTVM. 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 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: ```text /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 (a data contábil atual do fundo) e o documento de quem 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 (ou pelo número do contrato). 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 antes de entrar na baixa. Divergências de até 5% seguem direto para `pending_wallet_sale`. A confirmação não está disponível na API. Enquanto houver ativo em `pending_validation`, o lote não avança depois do encerramento. 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 lote só pode ser descartado até esta etapa, e o descarte do lote não está disponível na API: solicite a [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). **[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** — quando todos os ativos estão prontos para a baixa, a QI Tech gera o termo (`pending_documents_generation`) e coleta as assinaturas das partes (`pending_documents_signature`). Nenhuma ação do integrador é necessária. - **Termo externo** — o lote passa para `pending_signed_term_submission` e precisa receber o termo já assinado. O envio desse termo **não está disponível** na `manager-api`, na `consultant-api` nem na `assignor-api`: antes de operar com termo externo, combine o envio com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). 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, o lote passa a `pending_wallet_sale`, os ativos são baixados da carteira e, quando todos os ativos são concluídos, o lote é encerrado em `completed`. ## Webhook Quando o termo **interno** é assinado e o lote passa a `pending_payment`, a QI Tech envia o webhook `trade_resolve.assignment_status_change` aos agentes cadastrados na configuração do lote. É o único status que emite webhook: lotes com termo externo não recebem este evento. O cadastro é feito pela QI Tech: solicite em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). Para validar a assinatura, veja [Autenticação de webhooks](/documentation/iaas/introducao/autenticacao_webhooks). ```json title='Webhook Body' { "webhook_type": "trade_resolve.assignment_status_change", "webhook_datetime": "2024-04-02T10:15:00Z", "data": { "assignment_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "assignment_new_status": "pending_payment", "signed_term_url": "https://URL_TEMPORARIA_DO_TERMO" } } ``` | Campo | Descrição | |-|-| | `assignment_external_id` | `external_id` do lote | | `assignment_new_status` | Novo status do lote: `pending_payment` | | `signed_term_url` | Link para baixar o termo assinado. Expira em 24 horas. | --- # Recuperando Informações da Conta URL: /documentation/iaas/visibildade_de_caixa/get_accounts Lista as contas do fundo, com saldo, status e os tipos de transferência que cada uma aceita. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler contas | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /cash_account/fund_class/FUND_CLASS_KEY/accounts MÉTODO GET ### Query Params | Campo | Tipo | Descrição | |---------|------|-----------| | `limit` | int | Itens por página. Padrão: `10`. Máximo: `50`. | | `page` | int | Número da página (começando por zero). Padrão: `0`. | ### 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, "blocked_balance":0, "owner":{ "name":"FUNDO DE INVESTIMENTO EM DIREITOS CREDITORIOS", "document_number":"11.222.333/0001-81" }, "owner_document_number":"11.222.333/0001-81", "account_configuration":{ "pix":true, "wire_transfer":true, "statement":true }, "billings":[] }, { "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, "blocked_balance":0, "owner":{ "name":"FUNDO DE INVESTIMENTO EM DIREITOS CREDITORIOS", "document_number":"11.222.333/0001-81" }, "owner_document_number":"11.222.333/0001-81", "account_configuration":{ "pix":true, "wire_transfer":true, "statement":true }, "billings":[] } ], "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 | | `blocked_balance` | int | Saldo bloqueado, em centavos | - | | `account_configuration` | JSON | Funcionalidades habilitadas na conta: `pix`, `wire_transfer` (TED) e `statement` (extrato), cada uma `true`/`false` | - | | `billings` | array | Tarifas da conta. Nesta listagem vem sempre vazia | - | | `authorized_agents` | JSON | Agentes autorizados a operar a conta. Presente quando houver | - | :::caution **Atenção** O saldo é disponibilizado em centavos, ex.: 1234 = R$ 12,34. ::: ### 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 | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `CSH000005` | A `fund_class_key` não existe. | | 403 | `CSH000048` | O fundo não pertence ao seu perfil. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Recuperando Transações de uma Conta URL: /documentation/iaas/visibildade_de_caixa/get_transactions Lista as transações (extrato) de uma conta do fundo. Também é a forma de confirmar uma [transferência entre contas do fundo](/documentation/iaas/visibildade_de_caixa/post_internal_transfer). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ----------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Ler contas | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ### Request ENDPOINT /cash_account/fund_class/FUND_CLASS_KEY/account/ACCOUNT_KEY/transactions MÉTODO GET :::info Gestora e consultoria A rota acima vale para os dois agentes: a conta precisa estar vinculada ao fundo informado em `FUND_CLASS_KEY`. A consultoria precisa ter, nesse fundo, permissão de consulta às contas, concedida pela gestora. A gestora também pode consultar sem o fundo, em `/cash_account/account/ACCOUNT_KEY/transactions`. Essa forma não está disponível para a consultoria. ::: ### Path Params | Parâmetro | Descrição | |------------------|------------------------------------------------------------------------| | `FUND_CLASS_KEY` | Chave da classe de fundo à qual a conta está vinculada | | `ACCOUNT_KEY` | Chave da conta, como retornada em **[Recuperando Informações da Conta](/documentation/iaas/visibildade_de_caixa/get_accounts)** | ### 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": "11.222.333/0001-81" }, "owner_document_number": "11.222.333/0001-81", "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": "11.222.333/0001-81" }, "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": "11.222.333/0001-81" }, "owner_document_number": "11.222.333/0001-81", "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 | | `counter_part_document_number` | string | Documento da contraparte | | `limit` | int | Itens por página. Padrão: `10`. Máximo: `50`. | | `page` | int | Número da página recuperada (começando por zero) | ### 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 em centavos, ex.: 1234 = R$ 12,34. ::: ### 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 | ### 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 | ## Erros | Código | HTTP | Causa | Como resolver | |-----------|------|-------|---------------| | CIT000018 | 401 | A consultoria não tem vínculo ativo com o fundo informado, ou não tem permissão de consulta às contas nele. | Solicitar à gestora a permissão no fundo. | | CSH000048 | 403 | A conta não está vinculada ao fundo informado, ou o fundo não pertence ao agente. | Usar o `FUND_CLASS_KEY` do fundo dono da conta, conforme a listagem de contas do fundo. | | CSH000006 | 404 | Conta não encontrada para o `ACCOUNT_KEY` informado. | Verificar se o `ACCOUNT_KEY` está correto. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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 sejam feitas as devidas liberações, tanto em sandbox quanto em produção. ## 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | ------------- | ----------------- | | Gestora | `manager-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /transfer/fund_class/{fund_class_key}/internal_transfer MÉTODO POST ### Path Params | Campo | Tipo | Descrição | |------------------|--------|------------------------------------------------| | `fund_class_key` | string | Chave única identificadora do fundo na QI DTVM | ```json title='Request Body' { "amount": 15000, "description": "Transferência para a conta de cobrança", "origin_key": "3f2b8c1d-4e5a-4b6c-8d7e-9f0a1b2c3d4e", "origin_type": "manual_transfer", "source_account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44", "target_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b", "transfer_type": "pix" } ``` ### Body Params | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `amount` | integer | obrigatório | Valor a ser transferido, em centavos (ex.: `15000` = R$ 150,00). Deve ser maior que zero. | | `description` | string | obrigatório | Descrição da transferência. Até 255 caracteres. | | `origin_key` | string | obrigatório | Seu identificador (UUID) desta transferência. Uma segunda transferência com o mesmo `origin_key` é recusada (`TSF000022`) enquanto a primeira não estiver cancelada. | | `origin_type` | string | obrigatório | Envie `manual_transfer`. | | `target_account_key` | string | obrigatório | Chave da conta a ser creditada (destino). | | `source_account_key` | string | opcional | Chave da conta a ser debitada (origem). Quando omitida, é usada a conta principal do fundo. | | `transfer_type` | string | opcional | `pix` ou `wire_transfer` (TED), limitado ao que a conta de origem suporta (veja `account_configuration` em [Recuperando Informações da Conta](/documentation/iaas/visibildade_de_caixa/get_accounts)). Padrão: `wire_transfer`. | As duas contas precisam pertencer ao fundo, estar abertas e ser diferentes entre si. ## Response STATUS 201 ```json title='Response Body' { "internal_transfer_key": "1d4c2b7a-8e9f-4a0b-b1c2-d3e4f5a6b7c8", "internal_transfer_status": "pending_validation" } ``` | Campo | Tipo | Descrição | |---|---|---| | `internal_transfer_key` | string | Identificador da transferência na QI Tech. | | `internal_transfer_status` | string | Status da transferência no momento da criação: `pending_validation`. | ## Como confirmar a transferência Esta transferência **não envia webhook** e não há endpoint para consultar seu status. Para confirmar que ela foi efetivada, consulte o extrato das contas em [Recuperando Transações de uma Conta](/documentation/iaas/visibildade_de_caixa/get_transactions): o débito aparece na conta de origem e o crédito na conta de destino, com a `description` que você enviou. Em caso de erro, reenvie a requisição: uma transferência já criada é recusada com `TSF000022`, e assim você não transfere duas vezes. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ## Erros | Status | Código | Quando acontece | |---|---|---| | 409 | `TSF000022` | Já existe transferência com este `origin_key`. Não reenvie. | | 400 | `TSF000008` | `amount` igual ou menor que zero. | | 400 | `TSF000012` | `origin_type` inválido. | | 400 | `TSF000030` | `transfer_type` inválido. | | 400 | `TSF000035` | A conta de origem não aceita este `transfer_type`. | | 400 | `TSF000049` | O caixa do fundo já foi fechado no dia. | | 400 | `TSF000020` | Uma das contas não pertence ao fundo. | | 400 | `TSF000018` | Uma das contas não está aberta. | | 400 | `TSF000036` | Conta de origem igual à de destino. | | 404 | `TSF000005` | A `fund_class_key` não existe. | | 403 | `TSF000034` | O fundo não pertence à sua gestora. | | 400 | `QIT000001` | Corpo inválido (campo obrigatório ausente, tipo errado ou campo não aceito). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Criando Pedido de Estorno URL: /documentation/iaas/visibildade_de_caixa/post_transaction_reversal Cria um pedido de estorno (devolução) de um valor recebido na conta do fundo. O pedido passa por validação da QI Tech antes do pagamento, e o pagamento é notificado pelo [webhook de estorno](/documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal). :::info Disponível em | Perfil | Host | Permissão exigida | | ------- | -------------- | ----------------- | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /transaction_reversal/fund_class/{fund_class_key}/transaction_reversal MÉTODO POST ### Path Params | Campo | Tipo | Descrição | |------------------|--------|------------------------------------------------| | `fund_class_key` | string | Chave única identificadora do fundo na QI DTVM | ```json title='Request Body' { "amount": 125.25, "description": "Estorno - transferência indevida", "reversal_type": "pix", "reference_date": "2025-01-01", "source_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "transaction_key": "4208d7d1-9077-4d00-aa4a-a4368b954867", "origin_key": "0f8b6c2e-3d1a-4e5f-9a7b-2c4d6e8f0a1b" } ``` ### Body Params | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `amount` | number | obrigatório | Valor a ser estornado, em reais, com até duas casas decimais. Mínimo `0.01`. | | `description` | string | obrigatório | Descrição do estorno. Até 100 caracteres. | | `reversal_type` | string | obrigatório | Tipo de estorno: `pix`, `wire_transfer` (TED) ou `reversal_conciliation`. | | `reference_date` | string | obrigatório | Data de referência no formato `YYYY-MM-DD`. Não pode ser anterior à data contábil atual do fundo. | | `source_account_key` | string | condicional | Chave (UUID) da conta do fundo de onde sai o estorno. Informe este campo **ou** `source_account`. | | `source_account` | **[Account](#account)** | condicional | Dados da conta do fundo de onde sai o estorno. Alternativa a `source_account_key`. | | `transaction_key` | string | condicional | Chave (UUID) da transação recebida que será estornada. O valor é devolvido à conta que o enviou. A transação precisa estar pendente de conciliação. | | `target_account` | **[Account](#account)** | condicional | Conta de destino do estorno, quando não se usa `transaction_key`. | | `target_pix_key` | string | condicional | Chave Pix de destino. Aceita somente com `reversal_type: pix`. | | `origin_key` | string | opcional | Seu identificador (UUID) do pedido. Um segundo pedido com o mesmo `origin_key` é recusado (`TRV000033`). | | `reference_key` | string | opcional | Chave de referência da transferência a estornar no banco de origem (UUID). | | `conciliation_field` | string | opcional | Campo para conciliação em múltiplas expectativas. | | `end_to_end_id` | string | opcional | Identificador end-to-end do Pix a estornar. | | `external_key` | string | opcional | Chave única da transação a estornar no banco de origem (UUID). | | `bank_slip_settlement_group_key` | string | opcional | Chave única da liquidação de boleto a estornar no banco de origem (UUID). | :::caution Atenção - Origem: informe **exatamente um** entre `source_account_key` e `source_account`. - Destino: informe **exatamente um** entre `transaction_key`, `target_account` e `target_pix_key`. Nenhum ou mais de um devolve erro 400. ::: ### Account | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `account_number` | string | Número da conta | Até 20 | | `account_digit` | string | Dígito da conta | 1 | | `account_branch` | string | Agência da conta | Até 4 | | `financial_institution` | **[Financial Institution](#financial_institution)** | Instituição financeira | - | | `owner` | **[Owner](#owner)** | Titular da conta | - | ### 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 titular | Até 255 | | `document_number` | string | CPF ou CNPJ do titular, com pontuação | 14 ou 18 | ## Response STATUS 201 A resposta ecoa os campos enviados e acrescenta os dados abaixo. ```json title='Response Body' { "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1", "amount": 125.25, "status": "pending_validation", "reversal_type": "pix", "origin_type": "manual", "reference_date": "2025-01-01", "description": "Estorno - transferência indevida", "source_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "source_account": { "owner": { "name": "Nome do Fundo", "document_number": "11.222.333/0001-81" }, "account_digit": "8", "account_branch": "0001", "account_number": "1234567", "financial_institution": { "ispb": "32402502", "code": "329", "name": "QI Sociedade de Crédito Direto" } }, "target_account": { "owner": { "name": "Nome do Remetente", "document_number": "969.698.790-03" }, "account_digit": "1", "account_branch": "0001", "account_number": "7654321", "financial_institution": { "ispb": "32402502", "code": "329", "name": "QI Sociedade de Crédito Direto" } }, "fund_class": { "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487", "name": "Nome do Fundo", "document_number": "11.222.333/0001-81", "accounting_date": "2025-01-01", "manager": { "name": "EXEMPLO CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "22.333.444/0001-81" } }, "transaction_key": "4208d7d1-9077-4d00-aa4a-a4368b954867", "origin_key": "0f8b6c2e-3d1a-4e5f-9a7b-2c4d6e8f0a1b" } ``` | Campo | Tipo | Descrição | |---|---|---| | `transaction_reversal_key` | string | Identificador do estorno na QI Tech (UUID). | | `status` | string | `pending_validation` (aguarda validação da QI Tech) ou `pending_expectation_confirmation` (já aprovado, em processamento). O [webhook de estorno](/documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal) é enviado quando o estorno é pago (`paid`) ou quando é descartado depois de aprovado. Um pedido reprovado na validação passa a `discarded` sem webhook. | | `source_account`, `target_account` | object | Contas de origem e de destino resolvidas. | | `fund_class` | object | Dados do fundo. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 409 | `TRV000033` | Já existe pedido com este `origin_key`. Não reenvie: o estorno já foi solicitado. | | 400 | `TRV000020` | `reference_date` anterior à data contábil do fundo. | | 400 | `TRV000019` | `reversal_type` inválido. | | 400 | `TRV000009` | `amount` com mais de duas casas decimais. | | 400 | `TRV000015` / `TRV000016` | Conta de origem ausente, ou informada de mais de uma forma. | | 400 | `TRV000017` / `TRV000018` | Destino ausente, ou informado de mais de uma forma. | | 404 | `TRV000013` | A conta de origem não foi encontrada. | | 404 | `TRV000021` | A `transaction_key` não foi encontrada na conta de origem. | | 400 | `TRV000022` | A transação não está pendente de conciliação (já foi conciliada ou estornada). | | 400 | `TRV000023` | A transação não tem os dados da conta de quem enviou; informe `target_account`. | | 400 | `TRV000025` | `target_pix_key` enviado com `reversal_type` diferente de `pix`. | | 404 | `TRV000026` | A chave Pix de destino não foi encontrada. | | 404 | `TRV000005` | A `fund_class_key` não existe. | | 403 | `TRV000012` | O fundo não está associado ao seu cadastro de cedente. | | 400 | `QIT000001` | Corpo inválido (campo obrigatório ausente, tipo errado ou campo não aceito). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Webhooks URL: /documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal Webhooks do tipo `transaction_reversal.transaction_reversal_status_change`, enviados à gestora do fundo e ao cedente associado. Para validar a assinatura, veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks). Só dois eventos geram webhook: o estorno pago e o estorno descartado depois de aprovado. Um pedido reprovado na validação da QI Tech passa a `discarded` sem webhook. ## Estorno pago STATUS paid Enviado quando o pagamento do estorno é confirmado. ```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": "11.222.333/0001-81", "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": "11.222.333/0001-81" }, "financial_institution": { "code": "329", "ispb": "32402502", "name": "QI Sociedade de Crédito Direto" } }, "target_account":{ "owner": { "name": "Nome fictício", "document_number": "969.698.790-03" }, "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" } ``` ## Estorno descartado STATUS discarded Enviado quando um estorno já aprovado é descartado antes do pagamento. O payload é o mesmo do estorno pago, com `status` igual a `discarded`. ## Campos de `data` | Campo | Tipo | Descrição | |---|---|---| | `transaction_reversal_key` | string | Identificador do estorno na QI Tech (UUID). | | `amount` | number | Valor do estorno, em reais. | | `status` | string | `paid` ou `discarded`. | | `description` | string | Descrição informada no pedido. | | `reference_date` | string | Data de referência do estorno (`YYYY-MM-DD`). | | `fund_class_document_number` | string | CNPJ do fundo. | | `fund_class_key` | string | Chave do fundo. | | `source_account` | object | Conta de origem do estorno. | | `target_account` | object | Conta de destino do estorno. | | `external_key` | string | Identificador do pagamento do estorno. Só no estorno pago, quando houver. | | `conciliation_field` | string | Campo de conciliação enviado no pedido. Presente quando houver. | | `transaction_key` | string | Transação estornada. Presente quando houver. | | `reference_key` | string | Chave de referência. Presente quando houver. | | `origin_key` | string | O `origin_key` enviado no pedido. Presente quando houver. |