Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DevCarlosRodriguez/Documentacion-Arccnova-2.0/llms.txt

Use this file to discover all available pages before exploring further.

Esta guía te lleva desde la inicialización de la plataforma hasta la creación de tu primera venta. Sigue los pasos en orden: cada uno desbloquea el siguiente. Al finalizar tendrás una empresa registrada, un proyecto activo, un lote en inventario, un contacto y una venta en el sistema.
1

Prerrequisitos

Antes de levantar ArccNova v2 asegúrate de contar con lo siguiente:
DependenciaVersión mínimaNotas
.NET SDK10Runtime y SDK del backend
PostgreSQL17En producción se recomienda Aurora Serverless v2
S3 / MinIO—MinIO sirve como sustituto local de S3 en desarrollo
Cuenta Stripe—Necesaria para suscripción SaaS y pagos en línea vía Connect Express
El backend expone /healthz para verificar la conexión a la base de datos. Úsalo para confirmar que el chasis está operativo antes de continuar.
2

Inicializar la plataforma (primer SysAdmin)

El endpoint de bootstrap crea el primer usuario SysAdmin y solo puede ejecutarse una vez. Si ya existe un SysAdmin en la base de datos, la llamada devuelve 409 Conflict.
curl -X POST https://localhost:5001/api/bootstrap/init \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Administrador ArccNova",
    "email": "sysadmin@arccnova.com",
    "password": "P@ssw0rd!Seguro"
  }'
Respuesta esperada (200 OK):
{
  "success": true,
  "data": {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "sysadmin@arccnova.com",
    "role": "SysAdmin"
  }
}
Guarda las credenciales del SysAdmin en un gestor de secretos. Este usuario es el operador de la plataforma y tiene acceso a todos los tenants.
3

Crear planes de precios del SaaS

El SysAdmin define los planes que las empresas pueden contratar. Cada plan establece límites por recurso (número de proyectos, lotes, usuarios, etc.) y el precio mensual que se cobra vía Stripe.Inicia sesión como SysAdmin (ver paso 4) y luego crea los planes desde el panel de administración del sistema (/api/system/pricing-plans). Los planes son configurables en nombre, precio y límites; una vez publicados, las empresas los verán durante el registro público.
Crea al menos un plan gratuito o de prueba para facilitar el onboarding de nuevas empresas durante la fase de lanzamiento.
4

Registrar una empresa (registro público con Stripe Checkout)

El registro de empresa es público: cualquier usuario puede acceder al flujo de alta desde la página de registro de ArccNova. El proceso crea simultáneamente el usuario, la empresa (Tenant) y asigna el rol CEO al usuario registrante.El flujo internamente:
  1. El usuario llena el formulario de registro con los datos de la empresa.
  2. Se inicia una sesión de Stripe Checkout para la selección y pago del plan.
  3. Una vez confirmado el pago, ArccNova recibe el webhook de Stripe y activa la cuenta.
El SysAdmin también puede registrar empresas directamente sin pasar por Stripe Checkout usando POST /api/system/tenants, útil para onboarding manual o cuentas de demostración.
5

Iniciar sesión y obtener JWT

Una vez registrada la empresa, el CEO inicia sesión para obtener los tokens de acceso. Todas las llamadas autenticadas requieren el access_token en el header Authorization: Bearer.
curl -X POST https://localhost:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ceo@miempresa.com",
    "password": "MiPassword123!"
  }'
Respuesta esperada (200 OK):
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
    "expires_in": 3600
  }
}
Claims incluidos en el JWT:
ClaimDescripciónEjemplo
subID único del usuario (UUID)"3fa85f64-5717-4562-b3fc-2c963f66afa6"
nameNombre completo del usuario"Carlos Rodríguez"
emailCorreo electrónico"ceo@miempresa.com"
tenant_idID de la empresa activa"a1b2c3d4-..."
branch_idID del proyecto activo"e5f6g7h8-..." (vacío hasta seleccionar proyecto)
roleRol del usuario en el contexto actual"CEO"
impID del SysAdmin que impersona (solo presente en sesiones de impersonación)"7f3c..." (ausente en sesión normal)
El refresh_token permite obtener un nuevo access_token sin reautenticarse. Usa POST /api/v1/auth/refresh antes de que el token expire.
Los usuarios con rol CEO y Admin no son bloqueados por las verificaciones de contraseña del RBAC en los 18 permisos sensibles (C33/C34). El sistema les otorga paso directo en esas acciones.
6

Crear un proyecto inmobiliario (Branch)

Con la sesión activa, el CEO crea el primer proyecto de lotificación. Un Branch es un proyecto inmobiliario, no una sucursal física.
curl -X POST https://localhost:5001/api/v1/branches \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Colonia Las Palmas",
    "projectType": "Lotificacion",
    "description": "Desarrollo residencial en la zona norte",
    "countryCode": "MX",
    "stateCode": "JAL",
    "municipalityCode": "039",
    "localityCode": "0001"
  }'
Respuesta esperada (201 Created):
{
  "success": true,
  "data": {
    "branchId": "b9c1d2e3-f4a5-6789-bcde-f01234567890",
    "name": "Colonia Las Palmas",
    "projectType": "Lotificacion",
    "status": "Active"
  }
}
El único tipo de proyecto disponible en v2 es "Lotificacion". Los tipos "Construccion" y "VentaBienesRaices" no están en scope y el API los rechazará.
7

Agregar inventario: manzana y lote

El inventario se organiza en dos niveles: primero se crea la manzana (agrupador) y dentro de ella se registran los lotes individualmente.1. Crear una manzana:
curl -X POST https://localhost:5001/api/v1/properties/manzanas \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "b9c1d2e3-f4a5-6789-bcde-f01234567890",
    "name": "Manzana 27",
    "description": "Sector norte del proyecto"
  }'
2. Registrar un lote dentro de la manzana:
curl -X POST https://localhost:5001/api/v1/properties/lotes \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "manzanaId": "<id-manzana>",
    "number": "14",
    "area": 150.00,
    "price": 250000.00,
    "currency": "MXN",
    "status": "Disponible"
  }'
En v2 la captura de lotes es manual (uno por uno). La importación masiva desde Excel queda fuera del alcance de esta versión (C38).
8

Crear un contacto (cliente final)

Los contactos son los compradores de lotes. Son entidades independientes del proyecto y pueden estar asociados a ventas en múltiples proyectos.
curl -X POST https://localhost:5001/api/v1/contacts \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "María",
    "lastName": "González Pérez",
    "email": "maria.gonzalez@email.com",
    "phone": "+52 33 1234 5678",
    "curp": "GOPM850312MJCNRR07",
    "countryCode": "MX",
    "stateCode": "JAL"
  }'
Los contactos pueden tener datos de cónyuge y beneficiarios, requeridos para la generación del contrato de venta.
9

Crear una cotización y luego una reserva

El ciclo comercial comienza con una cotización (informativa, no compromete el lote) y avanza a una reserva que sí bloquea el lote.1. Crear una cotización:
curl -X POST https://localhost:5001/api/v1/sales/cotizaciones \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "loteId": "<id-lote>",
    "contactId": "<id-contacto>",
    "financingMonths": 60,
    "downPaymentPercent": 10
  }'
2. Crear una reserva a partir de la cotización:Una vez que el cliente acepta la cotización, se crea la reserva con el monto de apartado. Esto cambia el estado del lote a “Reservado”.
curl -X POST https://localhost:5001/api/v1/sales/reservas \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cotizacionId": "<id-cotizacion>",
    "depositAmount": 5000.00,
    "currency": "MXN"
  }'
10

Crear una venta a partir de la reserva

La reserva se convierte en venta cuando se formaliza el contrato. Al crear la venta se definen los planes de financiamiento (hasta 4 por venta) y se genera el contrato con las variables del expediente del cliente y del lote.
curl -X POST https://localhost:5001/api/v1/sales/ventas \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reservaId": "<id-reserva>",
    "financingPlans": [
      {
        "type": "Credito",
        "months": 60,
        "interestRatePercent": 12.0,
        "downPaymentAmount": 25000.00
      }
    ],
    "contractTemplateId": "<id-plantilla-contrato>"
  }'
Al confirmar la venta:
  • El lote pasa al estado “Vendido”.
  • Se generan las cuotas del financiamiento con amortización francesa.
  • El backend genera el PDF del contrato con QuestPDF, le calcula el hash SHA-256 y lo almacena en el bucket S3 aislado de documentos legales.
El PDF del contrato generado por el backend es el único binario descargable. No se puede regenerar ni modificar después de su creación; cualquier corrección requiere un nuevo contrato.

​
Siguientes pasos

Con la venta creada ya tienes el ciclo comercial básico funcionando. Los módulos que se abren a continuación son:
  • Collections: gestión de cuotas, cobros y mora.
  • Treasury: recibos de entrada/salida y gastos del proyecto.
  • Payments: habilitar pagos en línea del cliente final vía Stripe Connect Express.
  • Reports: reportes operativos como el corte de caja, estado de cuenta del cliente y cartera de cobranza.

Build docs developers (and LLMs) love

Get started for freeTalk to us