Suscripciones: antes de empezar
Cobros recurrentes: define planes, registra a los clientes que se suscriben y cobra cada periodo emitiendo el comprobante electrónico.
Flujo completo:
- Plan (
subscriptions/plans, solo administrador): productos, precio por periodo, periodicidad (cat_period_id, ver Listar periodos), cantidad de cobros o ilimitado, y días de prueba gratis. - Suscriptor (
subscriptions/subscribers): el cliente (con DNI o RUC) que se suscribe. Puede tener datos extra (usuario de Discord/GitLab, canales) y servidores asociados, y suscriptores hijos (parent_id). - Suscripción (
subscriptions): une suscriptor y plan. Guarda una copia del monto y los productos del plan y crea la primera orden de cobro (pendiente, vence en la fecha del primer cobro: hoy, la fechastart_dateque envíes o el fin de la prueba gratis). - Órdenes automáticas: cada día el sistema crea la orden del siguiente periodo de cada suscripción activa o pausada, con los días de anticipación configurados en la empresa. Las órdenes pendientes que pasan su vencimiento quedan como expiradas (
expired), y el sistema envía los recordatorios de pago programados. - Avisar (
subscriptions/orders/{id}/notify): envía al cliente por correo el mensaje de cobro con el enlace de pago (payment_url), donde puede pagar en línea. - Marcar pagada (
subscriptions/orders/{id}/pay): registra el cobro y emite el comprobante por el monto de la suscripción: boleta si el cliente tiene DNI, factura si tiene RUC. El cobro se registra en efectivo en la caja abierta del usuario que marca el pago (abre la caja antes en la sección Caja). Si el comprobante no se puede emitir, la orden no cambia. - Recibos (
subscriptions/receipts): órdenes pagadas con su comprobante. Si una orden quedó pagada sin comprobante (p. ej. pagada en línea), Emitir comprobante lo genera.
Estados de una suscripción (status): authorized activa · paused pausada (sigue generando órdenes) · cancelled cancelada (ya no genera órdenes; es definitivo) · finished finalizada (el sistema la marca al crear la última orden de un plan con cantidad de periodos).
Estados de una orden (status): pending pendiente · paid pagada · rejected rechazada (pago fallido; se puede volver a cobrar) · expired vencida sin pagar (se puede cobrar) · canceled cancelada.
Permisos: los planes los crea, edita, activa, desactiva y elimina solo un administrador (403 a un vendedor); cualquier usuario puede consultarlos. Suscriptores, suscripciones, órdenes y recibos los gestiona cualquier usuario; eliminar una suscripción es solo para administradores.
Formato: las respuestas son {success, data, message?}; los listados usan paginación por cursor {success, data[], pagination: {next_cursor, has_more}} (limit de 1 a 100 y cursor). Errores con el código HTTP real: 403 sin permiso, 404 no existe, 409 una regla de negocio impide la operación (el message explica qué hacer), 422 {success: false, message: {campo: [errores]}} validación de campos.