Documentação

Español

Português
English

Español

Português
English

Appearance

Crear / Editar Contrato ​

Requisitos previos de acceso

  • Permiso (módulo): manageContracts
  • Licencia/Feature: Ninguna (para débito automático en fiat: DIGITAL_BANKING)
  • Contenedor del menú: GENERAL → grupo Contratos (accedido desde la Lista de contratos)

Qué es / cuándo usar ​

Formulario en dos pasos (stepper) para registrar un contrato de cobro recurrente con un cliente: en el paso General se definen el título, descripción, tipo de pago (fiat o token), valor total, vigencia, documento adjunto, cliente y tipo de contrato; en el paso Pagos, el sistema genera automáticamente las cuotas mensuales dividiendo el valor total por la vigencia, y permite ajustar la fecha de cada cuota. Úselo para formalizar mensualidades, suscripciones, planes de pago en cuotas y cualquier cobro recurrente vinculado a un usuario.

Requisitos previos ​

  • Permiso: manageContracts (la ruta y los botones de guardar solo existen con este módulo). Permiso doble — enum CPM en el backend + módulo dinámico en la BD.
  • Licencia/Feature: Ninguna para crear. Para que el débito automático en fiat funcione después, DIGITAL_BANKING debe estar habilitada.
  • Dependencias de otras pantallas:
    • Es necesario tener al menos un Tipo de contrato registrado — ver Tipos de contrato.
    • Para pago en token, el token de cobro debe existir en [Gestionar Tokens].
    • El correo electrónico del cliente debe pertenecer a un usuario existente — el formulario lo valida antes de permitir avanzar.

Paso a paso ​

  1. En la Lista de contratos, haga clic en Nuevo (o en el lápiz para editar).
  2. Paso General: complete el título, descripción, tipo de pago, valor total, fechas de vigencia, adjunte el documento e ingrese el correo electrónico del cliente.
  3. Haga clic en el enlace validar si el usuario existe junto al correo — es obligatorio. Una marca verde confirma; sin ella el avance queda bloqueado.
  4. Seleccione el Tipo de contrato (y el Token de cobro, si el pago es en token).
  5. Avance a Pagos: revise las cuotas generadas automáticamente; ajuste fechas si es necesario (modo edición).
  6. Haga clic en Guardar y confirme en el bottom-sheet.

Campos — paso General ​

CampoQué es¿Requerido?Efecto en el sistema/backend
TítuloNombre del contratoSíGuarda title. Inmutable en edición (campo deshabilitado en modo edición).
DescripciónTexto libre del acuerdo (hasta 4000 caracteres)SíGuarda description. Inmutable en edición.
Tipo de pagoFiat o TokenSí (default Fiat)Guarda paymentType. Define cómo ocurrirá el débito: fiat debita la cuenta digital; token debita la billetera del cliente. Inmutable en edición.
Token de cobroToken utilizado cuando el pago = tokenCondicional (solo si Token)Guarda paymentTokenId. En fiat, el campo se limpia automáticamente (paymentTokenId = '').
Valor totalMonto total del contratoSíGuarda totalValue como BigNumber (máscara de moneda/token). En fiat, formateado con 2 decimales; en token, con la precisión del token. Inmutable en edición.
Fecha inicialInicio de la vigenciaSíGuarda initialDate. No puede ser en el pasado (el filtro del datepicker bloquea fechas anteriores a hoy).
Fecha finalFin de la vigenciaSíGuarda endDate. Junto con la inicial define el número de cuotas mensuales. Inmutable en edición.
DocumentoArchivo del contrato (PDF/imagen)SíSe sube vía API de archivos; guarda document.{name,url}. Límite de 10 MB y tipos restringidos — un archivo inválido muestra error.
Correo del clienteIdentifica al usuario destinatario del cobroSíValidado por getUserBasicInfo; solo con la marca verde (emailChecked) el formulario se desbloquea. Guarda customerEmail. Inmutable en edición.
Tipo de contratoCategoría del contratoSíGuarda contractTypeId. Alimentado por Tipos de contrato.

Campos — paso Pagos ​

CampoQué es¿Requerido?Efecto en el sistema/backend
Lista de cuotasCuotas mensuales generadas automáticamenteGenerado por el sistemaEn la creación, el total se divide por (número de meses entre las fechas) + 1; cada cuota recibe amount y competence (una por mes). Estado inicial: pendiente.
Fecha de la cuota (competencia)Cuándo vence/será debitada la cuotaEditable (cuotas pendientes)Editar abre el modal de fecha; llama a updateContractPayment. Solo las cuotas en pendiente tienen el lápiz.
Valor de la cuotaValor de cada cuotaCalculadototalValue / (monthDiff + 1) (BigNumber). Mostrado con el símbolo de la moneda (fiat) o ID del token.
Estado de la cuotapendiente / pagada / vencida / canceladaSistemaActualizado por el scheduler de cobro o por pago manual.

Acciones y modales ​

  • Siguiente / Anterior: navegación del stepper. En modo creación el stepper es lineal: el paso General solo habilita el avance cuando todos los campos obligatorios están completos y el correo fue validado.
  • Validar usuario: valida el correo del cliente; obligatorio para continuar. El ícono de limpiar restablece la validación.
  • Editar fecha de cuota: abre modal de selección de nueva fecha; al confirmar, guarda y recarga la pantalla.
  • Guardar: abre bottom-sheet de confirmación. En la creación llama a createContract; en edición llama a updateContract. Éxito → vuelve al listado con snackbar.

Reglas de negocio / consideraciones ​

Atención

  • En edición, la mayoría de los campos son de solo lectura. Solo son modificables el tipo de contrato y las fechas de las cuotas pendientes. Título, descripción, valor, tipo de pago, token, fechas de vigencia, documento y cliente quedan bloqueados después de la creación. Para cambiar lo esencial, cree un nuevo contrato.
  • La validación del correo es obligatoria: sin la marca verde, el avance queda bloqueado. Un correo que no corresponde a un usuario existente impide la creación.
  • Generación de cuotas: el número de cuotas es meses_entre_fechas + 1. Una vigencia del 01/ene al 01/jun genera 6 cuotas; defina las fechas teniendo esto en cuenta.
  • La fecha inicial en el pasado está bloqueada — no es posible registrar un contrato con inicio retroactivo mediante el datepicker.
  • Valores financieros: total y cuotas son BigNumber — sin redondeo. La división puede generar decimales periódicos; verifique los decimales según fiat (2) o token (precisión del token).
  • Débito automático & cobro: una vez creado y aceptado por el cliente, el scheduler diario (08:00) debita las cuotas vencidas. En fiat, transfiere desde la cuenta digital del cliente a la cuenta principal (requiere DIGITAL_BANKING); en token, realiza una transacción de billetera. Sin saldo, la cuota pasa a vencida y el cliente/admin reciben un correo.
  • Idempotencia: el débito de la cuota usa el id de la cuota como externalId en la transacción de billetera — reprocesar la misma cuota es seguro y no duplica el débito.

Ejemplos ​

Escenario 1 — Mensualidad en fiat con débito automático (12 cuotas)
  1. General: Título "Plan Anual Premium", descripción del servicio, Tipo de pago = Fiat, Valor total = R$ 1.200,00, vigencia 01/07 al 01/06 del año siguiente (genera 12 cuotas de R$ 100,00).
  2. Adjunte el PDF firmado, ingrese el correo del cliente y haga clic en validar (marca verde).
  3. Seleccione el Tipo de contrato "Suscripción".
  4. Pagos: revise las 12 cuotas mensuales de R$ 100,00 con competencia el día 01 de cada mes.
  5. Guarde. En la Lista, active el Débito automático.
  6. Resultado: después de que el cliente acepte en la app, cada día 01 (procesado a las 08:00) el sistema debita R$ 100,00 de la cuenta digital. Sin saldo → la cuota pasa a vencida y se envían notificaciones.
Escenario 2 — Contrato pagado en token (billetera)
  1. General: Tipo de pago = Token, seleccione el Token de cobro (ej.: USDT), Valor total = 600 (precisión del token), vigencia de 6 meses → 6 cuotas de 100.
  2. Adjunte el documento, valide el correo del cliente, seleccione el tipo de contrato.
  3. Pagos: 6 cuotas de 100 USDT.
  4. Guarde y active el débito automático.
  5. Resultado: el cobro verifica el saldo del token en la billetera del cliente y realiza una transacción de billetera (no toca la cuenta digital). Saldo insuficiente → cuota vencida.
Escenario 3 — Ajustar la fecha de una cuota específica
  1. Abra el contrato en modo edición (o en Detalles).
  2. En la cuadrícula de cuotas, localice una cuota pendiente (solo estas tienen el lápiz).
  3. Haga clic en editar, elija la nueva fecha de competencia y confirme.
  4. Resultado: updateContractPayment guarda la nueva competencia; la pantalla se recarga. Las cuotas pagadas o vencidas no pueden tener la fecha modificada.

Pantallas relacionadas ​