Crear plan
POST /api/subscriptions/plans
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Registra un plan de suscripción.
Quién puede usarlo: solo usuarios de tipo administrador (type = admin). Con el token de un vendedor responde 403.
Formato de respuesta: estándar {success, data, message?} (registro único). Responde 201 con el plan creado (incluye su id).
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
name |
string (máx. 255) | Sí | Nombre del plan. |
description |
string (máx. 255) | Sí | Descripción. |
cat_period_id |
integer | Sí | Periodicidad: id de Listar periodos (1 mensual, 2 anual, 3 diario, 4 semanal, 5 quincenal, 6 bimestral, 7 trimestral, 8 semestral). |
unlimited |
boolean | No | true = plan ilimitado (sin cantidad de periodos). Por defecto false. |
quantity_period |
integer (1 a 1000) | Sí si no es ilimitado | Cantidad de cobros. Se ignora en un plan ilimitado. |
trial_days |
integer (0 a 365) | No | Días de prueba gratis. 0 o null = sin prueba. |
status |
boolean | No | Activo. Por defecto true. |
currency_type_id |
string | No | Moneda (PEN, USD). Por defecto PEN. |
items |
array (1 a 50) | Sí | Productos que se cobran cada periodo. |
items[].item_id |
integer | Sí | Id del producto o servicio. |
items[].quantity |
number (> 0) | Sí | Cantidad. |
items[].unit_price |
number (≥ 0) | Sí | Precio de venta unitario. Si es gravado, incluye IGV. |
items[].affectation_igv_type_id |
string | No | 10 gravado (por defecto, o la afectación de venta del producto), 20 exonerado, 30 inafecto. |
items[].apply_in_period |
string | No | all = se cobra en todos los periodos (por defecto). first = solo en el primer cobro (solo planes ilimitados). |
Reglas:
- Los importes de cada producto y los totales del plan los calcula el servidor desde
quantity,unit_pricey la afectación (IGV 18%). - Al menos un producto debe tener
apply_in_period: all.firstsolo se admite en planes ilimitados. - Los cambios del plan no modifican las suscripciones existentes: cada suscripción guarda el monto y los productos del plan al momento de suscribirse.
Errores:
403si el usuario no es administrador.422{success: false, message: {campo: [errores]}}si falla la validación de campos. (faltaname,description,cat_period_id,quantity_perioden un plan no ilimitado oitems; producto inexistente; cantidad 0; ningún producto conapply_in_period: all;firsten un plan con cantidad de periodos).401sin token o con un token inválido.
Cuerpo
Content-Type: application/json
{
"name": "Plan Mensual Gold",
"description": "Acceso ilimitado al gimnasio y clases grupales",
"cat_period_id": 1,
"quantity_period": 12,
"trial_days": 7,
"items": [
{
"item_id": 845,
"quantity": 1,
"unit_price": 118,
"affectation_igv_type_id": "10"
}
]
}
Respuestas
201 — Creado
{
"success": true,
"data": {
"id": 3,
"name": "Plan Mensual Gold",
"description": "Acceso ilimitado al gimnasio y clases grupales",
"status": true,
"cat_period_id": 1,
"period": {
"id": 1,
"code": "M",
"name": "Mensual"
},
"unlimited": false,
"quantity_period": 12,
"trial_days": 7,
"currency_type_id": "PEN",
"total_taxed": 100.0,
"total_exonerated": 0.0,
"total_unaffected": 0.0,
"total_igv": 18.0,
"total_value": 100.0,
"total": 118.0,
"items": [
{
"id": 77,
"item_id": 845,
"description": "MEMBRESÍA GIMNASIO",
"internal_id": "MEM-001",
"quantity": 1.0,
"unit_price": 118.0,
"unit_value": 100.0,
"affectation_igv_type_id": "10",
"total_value": 100.0,
"total_igv": 18.0,
"total": 118.0,
"apply_in_period": "all"
}
],
"subscriptions_count": 0,
"can_delete": true,
"checkout_url": "https://empresa.dominio/full_suscription/plans/3"
},
"message": "Plan registrado con éxito"
}
422 — Validación
{
"success": false,
"message": {
"quantity_period": [
"La cantidad de periodos es obligatoria si el plan no es ilimitado."
],
"items": [
"Se requiere al menos un producto."
]
}
}
403 — Usuario no administrador
{
"success": false,
"message": "Solo un administrador puede gestionar este recurso."
}
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.