Facturación y Suscripciones =========================== El módulo de facturación de NoxPanel permite gestionar suscripciones, consultar facturas, registrar métodos de pago y controlar el perfil de facturación de tu organización. Soporta pagos vía **Stripe** y **PayPal**. .. note:: Para acceder al módulo de facturación necesitas el permiso ``can_access_billing``. Si no ves la sección, contacta con tu administrador. .. image:: /_static/screenshots/07_billing.jpg :alt: Panel de facturación :width: 100% :align: center | Acceso ------ El dashboard de facturación se encuentra en ``/billing/``. Desde allí puedes: - Ver el resumen de tus **suscripciones activas** - Consultar el historial de **facturas** - Gestionar tus **métodos de pago** - Editar tu **perfil de facturación** (datos fiscales) - Ver **pagos realizados** y su estado Descripción General ------------------- El sistema de facturación se organiza en torno a los siguientes conceptos: **Plan de Precios (PricingPlan)** Define el precio, período de facturación y tipo de recurso. Los planes pueden ser por horas, diarios, mensuales o anuales, y aplicarse a hosting compartido, VPS o addons. **Suscripción (Subscription)** Enlaza tu tenant con un plan. Cada recurso contratado (sitio web, VM, etc.) genera una suscripción asociada. **Factura (Invoice)** Documento fiscal generado automáticamente al final de cada período de facturación. Incluye subtotal, IVA y total. **Pago (Payment)** Registro de cada transacción realizada vía Stripe, PayPal, transferencia bancaria o manual. .. code-block:: text Flujo de facturación: Plan → Suscripción → Uso → Factura → Pago ↓ Webhook (Stripe/PayPal) Funcionalidades --------------- Consultar Suscripciones ~~~~~~~~~~~~~~~~~~~~~~~ Desde el dashboard de facturación puedes ver todas tus suscripciones y su estado: .. list-table:: :header-rows: 1 :widths: 20 50 * - Estado - Descripción * - **Activa** - Suscripción en funcionamiento normal * - **Pausada** - Temporalmente suspendida (no se factura) * - **Cancelada** - Suscripción finalizada * - **Pago Pendiente** - Factura vencida sin pagar * - **Periodo de Prueba** - En período de prueba gratuito .. code-block:: bash # Ejemplo — listar suscripciones vía API curl -X GET https://tu-dominio.com/billing/api/subscriptions/ \ -H "Authorization: Bearer " # Respuesta ejemplo: # [ # { # "id": "a1b2c3d4-...", # "plan": {"name": "Hosting Básico", "price": "9.9900", "billing_period": "monthly"}, # "status": "active", # "resource_name": "ejemplo.com", # "current_period_start": "2026-02-01", # "current_period_end": "2026-03-01" # } # ] Ver Facturas ~~~~~~~~~~~~ Las facturas se generan automáticamente y siguen el formato ``INV-AAAA-NNNN`` (por ejemplo, ``INV-2026-0042``). Cada factura incluye: * **Datos del emisor y receptor** (snapshot inmutable) * **Líneas de factura** — Detalle de cada recurso facturado * **Subtotal**, **IVA** y **Total** * **Estado**: Borrador, Pendiente, Pagada, Vencida, Anulada o Reembolsada * **Período de facturación** .. code-block:: bash # Listar facturas curl -X GET https://tu-dominio.com/billing/api/invoices/ \ -H "Authorization: Bearer " # Ver detalle de una factura curl -X GET https://tu-dominio.com/billing/api/invoices// \ -H "Authorization: Bearer " .. note:: Las facturas pagadas son inmutables. Los datos fiscales se capturan en el momento de la emisión para garantizar la integridad del documento. Métodos de Pago ~~~~~~~~~~~~~~~ Puedes registrar y gestionar diferentes métodos de pago: * **Tarjeta de crédito/débito** — Vía Stripe (Visa, Mastercard, etc.) * **PayPal** — Cuenta PayPal vinculada * **SEPA Direct Debit** — Domiciliación bancaria europea * **Transferencia Bancaria** — Pago manual .. code-block:: bash # Listar métodos de pago curl -X GET https://tu-dominio.com/billing/api/payment-methods/ \ -H "Authorization: Bearer " # Ejemplo de respuesta: # [ # { # "id": 1, # "method_type": "card", # "label": "Visa ****4242", # "is_default": true, # "details": {"brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2028} # }, # { # "id": 2, # "method_type": "paypal", # "label": "usuario@gmail.com", # "is_default": false # } # ] Para añadir una tarjeta de crédito, el flujo redirige a **Stripe Checkout**. Para PayPal, se utiliza el flujo de vinculación de cuenta de PayPal. .. tip:: Marca un método de pago como **predeterminado** para que se utilice automáticamente en los cobros recurrentes. Perfil de Facturación ~~~~~~~~~~~~~~~~~~~~~ El perfil de facturación contiene los datos fiscales de tu organización que aparecerán en las facturas: * **Razón social** — Nombre legal de la empresa * **NIF/CIF/VAT** — Identificación fiscal * **Dirección** — Dirección completa (línea 1, línea 2, ciudad, provincia, código postal, país) * **Email de facturación** — Dirección donde se envían las facturas * **Moneda preferida** — EUR, USD, etc. * **Cobro automático** — Activar/desactivar pagos automáticos .. code-block:: bash # Consultar perfil de facturación curl -X GET https://tu-dominio.com/billing/api/profiles/ \ -H "Authorization: Bearer " # Actualizar perfil curl -X PATCH https://tu-dominio.com/billing/api/profiles// \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "legal_name": "Mi Empresa S.L.", "tax_id": "B12345678", "address_line1": "Calle Principal 42", "city": "Madrid", "postal_code": "28001", "country": "ES", "billing_email": "facturas@miempresa.com", "currency": "EUR", "auto_pay": true }' .. warning:: Asegúrate de completar el perfil de facturación antes de contratar servicios. Los datos fiscales se capturan en cada factura emitida y no pueden modificarse retroactivamente. Historial de Pagos ~~~~~~~~~~~~~~~~~~ Puedes consultar todos los pagos realizados, incluyendo: * **Importe y moneda** * **Pasarela utilizada** (Stripe, PayPal, transferencia, manual) * **Estado** (Pendiente, Completado, Fallido, Reembolsado, Cancelado) * **Fecha de pago** * **Factura asociada** .. code-block:: bash # Listar pagos curl -X GET https://tu-dominio.com/billing/api/payments/ \ -H "Authorization: Bearer " Callbacks y Webhooks ~~~~~~~~~~~~~~~~~~~~ Al realizar un pago vía Stripe o PayPal, serás redirigido automáticamente a: * ``/billing/payment/success/`` — Si el pago se completa correctamente * ``/billing/payment/cancel/`` — Si cancelas el proceso de pago Los webhooks de Stripe y PayPal actualizan automáticamente el estado de facturas y pagos en segundo plano. Notas ----- * Todos los endpoints de la API de facturación están bajo ``/billing/api/``. * La autenticación requiere un token JWT válido. * Las facturas siguen un formato numerado secuencial (``INV-AAAA-NNNN``) para cumplir con los requisitos legales. * El IVA se aplica automáticamente según la tasa configurada en el plan (por defecto 21%). * Los pagos via Stripe y PayPal se procesan de forma segura; NoxPanel nunca almacena datos de tarjeta completos. * Si tienes una factura vencida, tu suscripción puede pasar a estado **"Pago Pendiente"** hasta que se regularice. * Para exportar facturas a tu sistema ERP/CRM, utiliza la API REST para obtener los datos en formato JSON. .. seealso:: - :doc:`quickstart` — Guía de inicio rápido - :doc:`hosting` — Gestión de hosting compartido - :doc:`vps` — Gestión de servidores VPS - :doc:`tickets` — Sistema de soporte