Documentação

Português

English
Español

Português

English
Español

Appearance

Criar / Editar Contrato ​

Pré-requisitos de acesso

  • Permissão (módulo): manageContracts
  • Licença/Feature: Nenhuma (para débito automático em fiat: DIGITAL_BANKING)
  • Contêiner do menu: GERAL → grupo Contratos (acessada a partir da Lista de contratos)

O que é / quando usar ​

Formulário em duas etapas (stepper) para registrar um contrato de cobrança recorrente com um cliente: na etapa Geral define-se título, descrição, tipo de pagamento (fiat ou token), valor total, vigência, documento anexo, cliente e tipo de contrato; na etapa Pagamentos, o sistema gera automaticamente as parcelas mensais dividindo o valor total pela vigência, e permite ajustar a data de cada parcela. Use para formalizar mensalidades, assinaturas, planos de pagamento parcelado e qualquer cobrança recorrente vinculada a um usuário.

Pré-condições ​

  • Permissão: manageContracts (a rota e os botões de salvar só existem com este módulo). Permissão dupla — enum CPM no backend + módulo dinâmico no DB.
  • Licença/Feature: Nenhuma para criar. Para que o débito automático em fiat funcione depois, DIGITAL_BANKING precisa estar habilitada.
  • Dependências de outras telas:
    • É preciso ter ao menos um Tipo de contrato cadastrado — ver Tipos de contrato.
    • Para pagamento em token, o token de cobrança precisa existir em [Gerenciar Tokens].
    • O e-mail do cliente precisa pertencer a um usuário existente — o formulário valida isso antes de liberar o avanço.

Passo a passo ​

  1. Na Lista de contratos, clique em Novo (ou no lápis para editar).
  2. Etapa Geral: preencha título, descrição, tipo de pagamento, valor total, datas de vigência, anexe o documento e informe o e-mail do cliente.
  3. Clique no link validar se o usuário existe ao lado do e-mail — é obrigatório. Um check verde confirma; sem ele o avanço fica bloqueado.
  4. Selecione o Tipo de contrato (e o Token de cobrança, se o pagamento for em token).
  5. Avance para Pagamentos: confira as parcelas geradas automaticamente; ajuste datas se necessário (modo edição).
  6. Clique em Salvar e confirme no bottom-sheet.

Campos — etapa Geral ​

CampoO que éObrigatório?Efeito no sistema/backend
TítuloNome do contratoSimGrava title. Imutável em edição (campo desabilitado no modo edit).
DescriçãoTexto livre do acordo (até 4000 caracteres)SimGrava description. Imutável em edição.
Tipo de pagamentoFiat ou TokenSim (default Fiat)Grava paymentType. Define como o débito ocorrerá: fiat debita a conta digital; token debita a carteira do cliente. Imutável em edição.
Token de cobrançaToken usado quando pagamento = tokenCondicional (só se Token)Grava paymentTokenId. Em fiat o campo é limpo automaticamente (paymentTokenId = '').
Valor totalMontante total do contratoSimGrava totalValue como BigNumber (máscara de moeda/token). Em fiat formata com 2 casas; em token com a precisão do token. Imutável em edição.
Data inicialInício da vigênciaSimGrava initialDate. Não pode ser no passado (filtro do datepicker bloqueia datas anteriores a hoje).
Data finalFim da vigênciaSimGrava endDate. Junto com a inicial define o nº de parcelas mensais. Imutável em edição.
DocumentoArquivo do contrato (PDF/imagem)SimSobe via API de arquivos; grava document.{name,url}. Limite de 10 MB e tipos restritos — arquivo inválido mostra erro.
E-mail do clienteIdentifica o usuário-alvo da cobrançaSimValidado por getUserBasicInfo; só com o check verde (emailChecked) o formulário libera. Grava customerEmail. Imutável em edição.
Tipo de contratoCategoria do contratoSimGrava contractTypeId. Alimentado por Tipos de contrato.

Campos — etapa Pagamentos ​

CampoO que éObrigatório?Efeito no sistema/backend
Lista de parcelasParcelas mensais geradas automaticamenteGerado pelo sistemaNa criação, o total é dividido por (nº de meses entre as datas) + 1; cada parcela recebe amount e competence (uma por mês). Status inicial pendente.
Data da parcela (competência)Quando a parcela vence/será debitadaEditável (parcelas pendentes)Editar abre o modal de data; chama updateContractPayment. Só parcelas em pendente têm o lápis.
Valor da parcelaValor de cada parcelaCalculadototalValue / (monthDiff + 1) (BigNumber). Exibido com símbolo da moeda (fiat) ou ID do token.
Status da parcelapendente / paga / vencida / canceladaSistemaAtualizado pelo scheduler de cobrança ou por pagamento manual.

Ações e modais ​

  • Próximo / Anterior: navegação do stepper. Em modo criação o stepper é linear: a etapa Geral só libera o avanço quando todos os campos obrigatórios estão preenchidos e o e-mail foi validado.
  • Validar usuário: valida o e-mail do cliente; obrigatório para prosseguir. O ícone de limpar reseta a validação.
  • Editar data da parcela: abre modal de seleção de nova data; ao confirmar, salva e recarrega a tela.
  • Salvar: abre bottom-sheet de confirmação. Na criação chama createContract; em edição chama updateContract. Sucesso → volta à listagem com snackbar.

Regras de negócio / cuidados ​

Atenção

  • Em edição, a maioria dos campos é somente leitura. Só são alteráveis o tipo de contrato e as datas das parcelas pendentes. Título, descrição, valor, tipo de pagamento, token, datas de vigência, documento e cliente ficam bloqueados após a criação. Para mudar o essencial, crie um novo contrato.
  • Validação de e-mail é mandatória: sem o check verde, o avanço fica travado. Um e-mail que não corresponde a um usuário existente impede a criação.
  • Geração de parcelas: o número de parcelas é meses_entre_datas + 1. Vigência de 01/jan a 01/jun gera 6 parcelas; defina as datas com isso em mente.
  • Data inicial no passado é bloqueada — não é possível registrar um contrato com início retroativo pelo datepicker.
  • Valores financeiros: total e parcelas são BigNumber — sem arredondamento. A divisão pode gerar dízimas; confira as casas conforme fiat (2) ou token (precisão do token).
  • Débito automático & cobrança: após criado e aceito pelo cliente, o scheduler diário (08h) debita as parcelas vencidas. Em fiat transfere da conta digital do cliente para a conta principal (exige DIGITAL_BANKING); em token faz transação de carteira. Sem saldo, a parcela vai a vencida e cliente/admin recebem e-mail.
  • Idempotência: o débito de parcela usa o id da parcela como externalId na transação de carteira — reprocessar a mesma parcela é seguro e não duplica o débito.

Exemplos ​

Cenário 1 — Mensalidade em fiat com débito automático (12 parcelas)
  1. Geral: Título "Plano Anual Premium", descrição do serviço, Tipo de pagamento = Fiat, Valor total = R$ 1.200,00, vigência 01/07 a 01/06 do ano seguinte (gera 12 parcelas de R$ 100,00).
  2. Anexe o PDF assinado, informe o e-mail do cliente e clique em validar (check verde).
  3. Selecione o Tipo de contrato "Assinatura".
  4. Pagamentos: confira as 12 parcelas mensais de R$ 100,00 com competências do dia 01 de cada mês.
  5. Salve. Na Lista, ligue o Débito automático.
  6. Resultado: após o cliente aceitar no app, todo dia 01 (processado às 08h) o sistema debita R$ 100,00 da conta digital. Sem saldo → parcela vira vencida e notificações são enviadas.
Cenário 2 — Contrato pago em token (carteira)
  1. Geral: Tipo de pagamento = Token, escolha o Token de cobrança (ex.: USDT), Valor total = 600 (precisão do token), vigência de 6 meses → 6 parcelas de 100.
  2. Anexe o documento, valide o e-mail do cliente, selecione o tipo de contrato.
  3. Pagamentos: 6 parcelas de 100 USDT.
  4. Salve e ligue o débito automático.
  5. Resultado: a cobrança verifica o saldo do token na carteira do cliente e faz uma transação de carteira (não toca a conta digital). Saldo insuficiente → parcela vencida.
Cenário 3 — Ajustar a data de uma parcela específica
  1. Abra o contrato em edição (ou nos Detalhes).
  2. Na grade de parcelas, localize uma parcela pendente (só essas têm o lápis).
  3. Clique em editar, escolha a nova data de competência e confirme.
  4. Resultado: updateContractPayment grava a nova competência; a tela recarrega. Parcelas pagas ou vencidas não podem ter a data alterada.

Telas relacionadas ​