Crear suscripción
POST /api/subscriptions
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Suscribe un cliente a un plan y crea su primera orden de cobro pendiente.
Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor). Los registros de suscripciones son de toda la empresa: un vendedor ve y gestiona los mismos que el administrador.
Formato de respuesta: estándar {success, data, message?} (registro único). Responde 201 con la suscripción creada.
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
customer_id |
integer | Sí | Id del suscriptor (cliente habilitado). |
plan_id |
integer | Sí | Id del plan (debe estar activo). |
start_date |
fecha Y-m-d |
No | Fecha del primer cobro. Por defecto hoy. Se ignora si el plan tiene prueba gratis. |
trial_start_date |
fecha Y-m-d |
No | Inicio de la prueba gratis (por defecto hoy). Solo si hay días de prueba. |
trial_days |
integer (0 a 365) | No | Días de prueba. Por defecto los del plan; 0 = sin prueba. |
Reglas:
- Se copian el monto, los productos, la periodicidad y la cantidad de cobros del plan: cambios posteriores del plan no la afectan.
- Con prueba gratis el primer cobro (
start_date) estrial_start_date+trial_days. - Se crea la primera orden de cobro (
pending) por el monto del plan, con vencimiento enstart_date. Las órdenes de los periodos siguientes las crea el sistema automáticamente. - La suscripción queda
authorized(activa).
Errores:
422{success: false, message: {campo: [errores]}}si falla la validación de campos. (cliente o plan inexistente, fecha con otro formato).409si el plan está inactivo o no tiene productos.401sin token o con un token inválido.
Cuerpo
Content-Type: application/json
{
"customer_id": 1520,
"plan_id": 3,
"trial_start_date": "2026-11-07"
}
Respuestas
201 — Creada
{
"success": true,
"data": {
"id": 48,
"status": "authorized",
"status_description": "Activa",
"plan_id": 3,
"plan_name": "Plan Mensual Gold",
"customer_id": 1520,
"customer": {
"id": 1520,
"name": "MARÍA FERNANDA QUISPE ROJAS",
"number": "45879632",
"identity_document_type_id": "1",
"email": "maria.quispe@correo.pe"
},
"cat_period_id": 1,
"period_name": "Mensual",
"unlimited": false,
"quantity_period": 12,
"orders_created": 1,
"start_date": "2026-11-14",
"end_date": "2027-10-14",
"trial_start_date": "2026-11-07",
"trial_days": 7,
"currency_type_id": "PEN",
"total": 118.0,
"created_at": "2026-11-07 10:15:32"
},
"message": "Suscripción registrada con éxito"
}
409 — Plan inactivo
{
"success": false,
"message": "El plan está inactivo: actívalo antes de suscribir clientes."
}
422 — Validación
{
"success": false,
"message": {
"plan_id": [
"El campo plan id seleccionado no existe."
]
}
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.