Operaciones

Las citas representan sesiones agendadas de un servicio o alquiler con un cliente. Soportan ubicación flexible, recordatorios automáticos por varios canales y servicios recurrentes.

Endpoint base: /api/v1/appointments

Scopes: appointments:read, appointments:write

Campos

Debe enviarse al menos uno de service_id o rental_id; scheduled_datetime es siempre obligatorio.

Endpoints

Ejemplo — Petición

POST /api/v1/appointments/ — agendar una cita a un servicio:

{
  "service_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "customer_id": "66f1a2b3c4d5e6f7a8b9c0d2",
  "scheduled_datetime": "2026-06-10T15:00:00Z",
  "duration_minutes": 60,
  "location_type": "service_location",
  "reminder_enabled": true,
  "reminder_hours": [24, 2],
  "reminder_channels": ["email", "push"],
  "notes": "Primera sesión de consultoría"
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0d3",
    "service": { "service": "66f1a2b3c4d5e6f7a8b9c0d1", "name": "Consultoría" },
    "customer": { "customer": "66f1a2b3c4d5e6f7a8b9c0d2", "name": "Juan Pérez" },
    "scheduled_datetime": "2026-06-10T15:00:00Z",
    "duration_minutes": 60,
    "status": "scheduled",
    "location_type": "service_location",
    "notes": "Primera sesión de consultoría"
  }
}

Los contratos gestionan alquileres permanentes: inquilino, garantes, cláusulas, ajustes periódicos del alquiler (ICL, IPC, porcentaje fijo) y facturación mensual automática.

Endpoint base: /api/v1/contracts

Scopes: contracts:read, contracts:write

Campos

Endpoints

Además del CRUD estándar, los contratos exponen endpoints de ciclo de vida y facturación:

Ejemplo — Petición

POST /api/v1/contracts/ — crear un contrato de alquiler:

{
  "rental_id": "66f1a2b3c4d5e6f7a8b9c0e1",
  "start_date": "2026-06-01T00:00:00Z",
  "end_date": "2029-06-01T00:00:00Z",
  "initial_rent": 150000,
  "security_deposit": 150000,
  "billing_day": 10,
  "adjustment_type": "icl",
  "adjustment_frequency_months": 12,
  "tenant": {
    "full_name": "Juan Pérez",
    "document_type": "DNI",
    "document_number": "30123456",
    "email": "[email protected]",
    "phone": "+5491122334455"
  },
  "notes": "Contrato de alquiler de vivienda"
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0e2",
    "rental_id": "66f1a2b3c4d5e6f7a8b9c0e1",
    "contract_number": "CTR-0042",
    "start_date": "2026-06-01T00:00:00Z",
    "end_date": "2029-06-01T00:00:00Z",
    "initial_rent": 150000,
    "current_rent": 150000,
    "billing_day": 10,
    "status": "draft",
    "tenant": { "full_name": "Juan Pérez", "document_number": "30123456" }
  }
}

Los métodos de pago definen las formas de cobro disponibles en ventas y puntos de venta. Soportan jerarquía (métodos padre e hijos), orden personalizado y un porcentaje de impacto sobre el precio.

Endpoint base: /api/v1/payment_methods

Scopes: payment_methods:read, payment_methods:write

Este recurso usa un controlador propio (no el CRUD estándar). Los campos completos de cada método de pago se obtienen con un GET; abajo se documentan los campos aceptados al crear uno.

Campos

Endpoints

Ejemplo — Petición

POST /api/v1/payment_methods/ — crear un método de pago personalizado:

{
  "code": "transferencia_propia",
  "name": "Transferencia a mi banco",
  "name_en": "Bank transfer",
  "type": "other",
  "icon": "wallet",
  "description": "Transferencia bancaria a cuenta propia"
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0f1",
    "code": "transferencia_propia",
    "name": "Transferencia a mi banco",
    "type": "other",
    "icon": "wallet",
    "status": "active",
    "sort_order": 7
  }
}

El módulo de envíos integra varios proveedores (OCA, Andreani, Correo Argentino, Mercado Envíos) y un sistema de delivery propio. Permite cotizar, crear y rastrear envíos, gestionar repartidores y dispositivos de flota con seguimiento GPS.

Endpoint base: /api/v1/shipping — repartidores en /api/v1/drivers, flota en /api/v1/fleet

Scopes: shipping:read, shipping:write

Los envíos usan controladores propios (no el CRUD estándar). El cuerpo de creación de un envío depende del proveedor configurado; los campos completos de un envío se obtienen con un GET sobre el detalle.

Endpoints de envíos

Repartidores

Los repartidores son entidades propias del tenant para el delivery en campo. Al crearlos se genera un código de 8 caracteres que el repartidor usa como credencial de acceso.

Flota

Los dispositivos de flota representan vehículos con seguimiento GPS por polling. Pueden vincularse opcionalmente a un repartidor. Al crearlos se genera un código de 8 caracteres que el dispositivo usa para reportar su geolocalización.

Ejemplo — Petición

POST /api/v1/fleet/devices/ — registrar un dispositivo de flota:

{
  "name": "Camión 1",
  "plate": "AB123CD",
  "linked_driver_id": null
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Camión 1",
    "plate": "AB123CD",
    "device_code": "K7M2X9P4",
    "linked_driver_id": null,
    "status": "active"
  }
}