Negociação e acordos

Um acordo consolida uma ou mais dívidas do cliente em um parcelamento, com ou sem desconto, dentro das condições que você autorizou. Ele pode nascer de dois jeitos: proposto pelo operador (dashboard ou API) ou aceito pelo próprio devedor no portal de autoatendimento.

Anatomia de um acordo

Campo	Significado
Valor original	Soma dos valores atualizados das cobranças incluídas
Desconto	Valor abatido (limitado pela oferta/campanha ativa)
Valor final	Original − desconto: é o que será pago
Parcelas	Quantidade e valor de cada parcela mensal
Primeira parcela	Data de vencimento da parcela 1
Termos aceitos	Texto dos termos no momento do aceite
IP do aceite	Endereço IP registrado como evidência do aceite

Ciclo de vida

proposed ──► accepted ──► active ──► completed
    │            │           ├──► defaulted ──► active (regularizado)
    └──► cancelled ◄─────────┘

• Proposto (proposed) — a proposta existe, aguardando aceite. Só propostas podem ser aceitas.
• Aceito (accepted) — aceite registrado (com data, IP e termos); as parcelas são geradas neste momento.
• Ativo (active) — acordo em pagamento.
• Concluído (completed) — todas as parcelas quitadas. Estado final.
• Inadimplente (defaulted) — acordo quebrado; pode ser regularizado (volta a active) ou cancelado. A quebra é marcada manualmente (não há detecção automática) — veja Parcelas e quebra.
• Cancelado (cancelled) — encerrado sem conclusão; as parcelas pendentes são canceladas junto. Estado final.

Veja os efeitos da quebra em Parcelas e quebra.

Fluxo do operador

1. Em Acordos → Novo Acordo, escolha o cliente, o valor, o desconto, o número de parcelas (até 120 via API) e a data da primeira parcela. O acordo nasce proposed.
2. Quando o cliente confirmar, use Aceitar Acordo: o sistema muda o status para accepted, registra data e IP do aceite e gera as parcelas automaticamente.

:::note Aceite é idempotente Só um acordo proposed pode ser aceito. Aceitar um acordo que já saiu desse estado — porque já foi aceito ou porque duas requisições correram ao mesmo tempo — retorna 409 (CONFLICT) sem efeito colateral: as parcelas nunca são geradas em dobro. :::

Fluxo do portal (autoatendimento)

No portal, o devedor seleciona as cobranças, simula o parcelamento e aceita. Aqui está a proteção mais importante do fluxo:

:::info Validação server-side da proposta O desconto e o parcelamento nunca são aceitos do navegador. No aceite, o servidor confere a proposta contra a oferta de negociação ativa (campanha ou oferta da régua): desconto acima do autorizado ou parcelas além do teto são rejeitados com erro, e a tentativa fica registrada no log de acesso como proposta adulterada. Sem nenhuma oferta ativa, não há desconto e o parcelamento é limitado a 12 vezes. :::

No portal, a primeira parcela vence em 10 dias e o parcelamento vai até o teto da oferta (máximo absoluto de 24 vezes). O aceite registra IP, termos e uma interação na timeline do cliente.

Efeito na régua de cobrança

O motor trata acordo aceito como saída com sucesso da régua: a cobrança passa ao status negotiated, o enrollment é concluído com o motivo agreement_accepted e os envios pendentes são cancelados. A revalidação pré-envio garante que nenhuma mensagem de cobrança sai para uma cobrança negociada — o devedor que fechou acordo não continua sendo cobrado pela dívida original.

Eventos e integração

Os webhooks agreement.accepted (e demais eventos de acordo) notificam seus sistemas em tempo real — útil para emitir os boletos das parcelas no seu ERP ou gateway. Veja a referência da API em /api/v1/agreements.