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.

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.

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:

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

# Ejemplo — listar suscripciones vía API
curl -X GET https://tu-dominio.com/billing/api/subscriptions/ \
  -H "Authorization: Bearer <token>"

# 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

# Listar facturas
curl -X GET https://tu-dominio.com/billing/api/invoices/ \
  -H "Authorization: Bearer <token>"

# Ver detalle de una factura
curl -X GET https://tu-dominio.com/billing/api/invoices/<uuid>/ \
  -H "Authorization: Bearer <token>"

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

# Listar métodos de pago
curl -X GET https://tu-dominio.com/billing/api/payment-methods/ \
  -H "Authorization: Bearer <token>"

# 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

# Consultar perfil de facturación
curl -X GET https://tu-dominio.com/billing/api/profiles/ \
  -H "Authorization: Bearer <token>"

# Actualizar perfil
curl -X PATCH https://tu-dominio.com/billing/api/profiles/<id>/ \
  -H "Authorization: Bearer <token>" \
  -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

# Listar pagos
curl -X GET https://tu-dominio.com/billing/api/payments/ \
  -H "Authorization: Bearer <token>"

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.