ElVendedorDocs

Licencias y pagos

Cómo se solicita, aprueba, activa, valida y renueva una licencia, qué cuesta por punto de venta y cómo diagnosticar los errores de activación.

Para implementadores5 min de lecturaActualizado el 16 de noviembre de 2026

El backend es la autoridad de licencias: reemplaza a WordPress/DLM. Cada equipo se activa con un token propio y solo cachea el estado para operar sin red. Al terminar sabrás emitir una licencia, activar equipos, explicar un bloqueo y diagnosticar el error exacto.

Modelo: una licencia por negocio

Pieza Qué guarda
licenses Clave, negocio, estado (pending, active, suspended, expired, cancelled), vencimiento y límite de activaciones (null = ilimitado).
license_activations Un equipo por fila: device_id, etiqueta, rol, plataforma y el hash del token (el token nunca se guarda en claro).
license_events Auditoría: pedido, activación, confirmación, extensión, suspensión, anulación, expiración.

No confundas los dos conteos: la licencia limita equipos activados, mientras que el precio se calcula por POS activo (punto de venta con al menos una venta en la ventana configurada).

Catálogo y precios

Concepto Precio
Plan base (0 puntos de venta activos) 650 CUP/mes
Cada punto de venta activo 3000 CUP/mes (1 POS = 3000, 2 = 6000, 3 = 9000…)

Cada regla del tarifario lleva billing_mode: flat (precio fijo del tramo) o per_pos (precio × POS activos). Una solicitud sin sesión ni negocio también cotiza el plan base: nunca se cotiza una licencia a 0.

Cada licencia puede llevar un precio mensual fijado a mano (source: manual, currency, monthly_price), con prioridad sobre el tarifario. Al quitarlo (monthly_price: null) vuelve a source: rule.

Flujo de una licencia

Los cuatro endpoints son públicos (la app puede activarse antes de tener sesión), con 30 peticiones por minuto por IP. Si la petición lleva token, el negocio del usuario se usa para atar la licencia.

Método Ruta Uso
POST /api/v1/licensing/requests Pedir una licencia; devuelve datos de pago.
POST /api/v1/licensing/activate Activar el equipo y obtener el token.
POST /api/v1/licensing/validate Estado autoritativo de la activación.
POST /api/v1/licensing/deactivate Liberar la ranura del equipo.

1. Solicitud. Cuerpo con months (1–12), device_id, contact (name, phone, email) y notes. La licencia nace pending y la respuesta 201 trae license_key, status, monthly_price, price, currency, estimated_expires_at, payment, offline_grace_days.

2. Aprobación y pago. Un administrador confirma el pago desde el backoffice (solicitudes pendientes). Eso activa la licencia y sincroniza businesses.license_expires_at.

3. Activación. Cuerpo con license_key, device_id, más label, role, platform, app_version y activation_token (opcionales). Responde 201 con activation_token, activation, license y signature. El token se muestra una sola vez: guárdalo en el equipo.

4. Validación. Cuerpo con activation_token y, opcionalmente, app_version y platform. Responde 200 con valid: true, license, activation y signature; o 403 con valid: false y reason. Es el endpoint a consultar en lugar del caché local.

5. Desactivación. Cuerpo con activation_token y reason opcional. Responde deactivated y es idempotente.

El alta es idempotente por device_id: reinstalar no consume otra ranura. Si el equipo reenvía su token, se conserva; si no, se rota.

Estados, vencimiento y renovación

Estado Significado Cómo se llega
pending Solicitada, sin pago confirmado. Al pedirla; no activa equipos.
active Vigente y usable. Confirmación del pago.
suspended Cortada por decisión administrativa. Suspensión en backoffice.
expired Fecha de vencimiento pasada. Comando diario licensing:expire.
cancelled Anulada; libera las activaciones. Anulación en backoffice.

Acciones de backoffice: extender (corre la expiración desde la fecha vigente, o desde hoy si venció), suspender/reactivar/anular y revocar dispositivo (libera la ranura). Las licencias nuevas copian LICENSING_DEFAULT_ACTIVATIONS_LIMIT (3); cambiarlo no altera las ya emitidas.

php artisan licensing:expire

Si el cliente no puede validar (sin red)

  • El cliente móvil revalida cada 12 h; si no hay red, aplica una gracia de 7 días (LICENSING_OFFLINE_GRACE_DAYS) desde expires_at.
  • Una suspensión o anulación que llegue del servidor corta de inmediato: la gracia cubre falta de red, no un veredicto explícito.
  • El móvil adopta el estado del bootstrap y de cada business_profile en el pull.
  • El escritorio no tiene flujo propio de activación: muestra el estado que llega por bootstrap.current_business.license y sigue en solo-local sin perder datos.
  • El gate de escrituras de sync viene apagado (LICENSING_ENFORCE_SYNC_GATE=false). Encendido, el dueño con licencia no vigente recibe 403 con error.code = "license_invalid" en sync/push; los negocios sin licencia y los roles operativos nunca se bloquean.

Diagnóstico de errores

HTTP error Causa Qué hacer
404 license_not_found La clave no existe. Verifica la clave emitida; no la reescribas a mano.
409 activation_limit_reached Se agotaron las ranuras (activations_limit, active_devices). Revoca un dispositivo o amplía el límite.
409 license_already_assigned La clave pertenece a otro negocio. Revisa el negocio de la licencia antes de reasignarla.
403 license_not_usable Vencida, suspendida o anulada. Extiende o reactiva desde backoffice.
429 — Más de 30 peticiones por minuto por IP. Espacia reintentos; no automatices en bucle.
403 license_invalid (en sync/push) Gate de escrituras encendido y licencia no vigente. Renueva; si es masivo, apaga el gate mientras investigas.

Límites conocidos

  • La firma del estado no se verifica en el cliente: el enforcement real es el gate del servidor. Si se exige verificación offline fuerte, hay que planificarlo con el backend.
  • El token de activación vive en localStorage del cliente, no en almacenamiento seguro del sistema.
  • requests es público y no deduplica por dispositivo: un cliente puede generar varias licencias pending. El backoffice debe ignorar las que no tengan pago.

Pendiente de validación

Los datos de pago (LICENSING_PAYMENT_*) son configuración del backend: confírmalos con quien administre el servicio antes de publicarlos a un cliente.

Siguiente paso

↑↓ para navegar · Enter para abrir · Esc para cerrar