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.
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:expireSi 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) desdeexpires_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_profileen el pull. - El escritorio no tiene flujo propio de activación: muestra el estado que llega por
bootstrap.current_business.licensey 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 recibe403conerror.code = "license_invalid"ensync/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
localStoragedel cliente, no en almacenamiento seguro del sistema. requestses público y no deduplica por dispositivo: un cliente puede generar varias licenciaspending. 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
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte