Saltar al contenido
Facturador

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) es trial_start_date + trial_days.
  • Se crea la primera orden de cobro (pending) por el monto del plan, con vencimiento en start_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).
  • 409 si el plan está inactivo o no tiene productos.
  • 401 sin 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.