Skip to main content

Regras de Negócio — Aditamento

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:

CampoSignificado
present_valueValor presente do título na data base.
differenceDiferença entre o fluxo proposto e o valor presente.
toleranceDiferença máxima aceita.
passedtrue 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 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.

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, 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.

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​