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.

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

{
  "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.
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:

{
  "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.

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

{
  "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.
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.
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.

Veja também

• Validar Aditamento
• Consultar Aditamento
• Cancelar Aditamento
• Tipos de Alteração