Endpoints de Facturación

El módulo de facturación expone endpoints bajo /billing/api/ diseñados para integrarse fácilmente con sistemas ERP/CRM. Todos los campos económicos (tax_id, subtotal, tax_amount, total, currency, line_items) siguen un formato estándar parseable por cualquier sistema externo.

Facturas — `/billing/api/invoices/`

El endpoint principal para consultar y gestionar facturas. Cada factura incluye datos fiscales completos e inmutables (snapshot al momento de generación).

Métodos
Método	Endpoint	Descripción
`GET`	`/billing/api/invoices/`	Listar facturas (paginado)
`POST`	`/billing/api/invoices/`	Crear factura (admin)
`GET`	`/billing/api/invoices/{id}/`	Detalle de factura con líneas
`PUT`	`/billing/api/invoices/{id}/`	Actualizar factura (solo borrador)
`DELETE`	`/billing/api/invoices/{id}/`	Anular factura
`POST`	`/billing/api/invoices/{id}/mark_paid/`	Marcar como pagada (admin)
`POST`	`/billing/api/invoices/{id}/create_stripe_checkout/`	Crear sesión de pago Stripe
`POST`	`/billing/api/invoices/{id}/create_paypal_order/`	Crear orden de pago PayPal

Filtros disponibles 

?status=pending — Filtrar por estado (draft, pending, paid, overdue, cancelled, refunded)
?tenant=1 — Filtrar por ID de tenant
?date_from=2026-01-01 — Facturas desde una fecha
?date_to=2026-01-31 — Facturas hasta una fecha

Ejemplo — Listar facturas pendientes:

curl -X GET "https://panel.example.com/billing/api/invoices/?status=pending" \
  -H "Authorization: Bearer $TOKEN"

Respuesta (lista):

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "number": "INV-2026-0015",
      "tenant": 1,
      "status": "pending",
      "issue_date": "2026-02-01",
      "due_date": "2026-02-15",
      "subtotal": "49.90",
      "tax_rate": "21.00",
      "tax_amount": "10.48",
      "total": "60.38",
      "currency": "EUR"
    }
  ]
}

Respuesta (detalle con line_items):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "number": "INV-2026-0015",
  "tenant": 1,
  "status": "pending",
  "issue_date": "2026-02-01",
  "due_date": "2026-02-15",
  "paid_date": null,
  "period_start": "2026-01-01",
  "period_end": "2026-01-31",
  "subtotal": "49.90",
  "tax_rate": "21.00",
  "tax_amount": "10.48",
  "total": "60.38",
  "currency": "EUR",
  "billing_name": "Empresa Ejemplo S.L.",
  "billing_tax_id": "B12345678",
  "billing_address": "Calle Mayor 1, 08001 Barcelona, ES",
  "notes": "",
  "items": [
    {
      "id": 1,
      "description": "Hosting Plan M - Enero 2026",
      "quantity": "1.0000",
      "unit_price": "29.9500",
      "total": "29.95",
      "resource_type": "hosting_site",
      "resource_id": 1,
      "period_start": "2026-01-01",
      "period_end": "2026-01-31"
    },
    {
      "id": 2,
      "description": "Base de datos adicional",
      "quantity": "1.0000",
      "unit_price": "9.9500",
      "total": "9.95",
      "resource_type": "addon",
      "resource_id": null,
      "period_start": "2026-01-01",
      "period_end": "2026-01-31"
    },
    {
      "id": 3,
      "description": "VPS Basic - 720 horas",
      "quantity": "720.0000",
      "unit_price": "0.0139",
      "total": "10.00",
      "resource_type": "vps",
      "resource_id": 5,
      "period_start": "2026-01-01",
      "period_end": "2026-01-31"
    }
  ],
  "payments": [],
  "stripe_invoice_id": "",
  "paypal_invoice_id": "",
  "created_at": "2026-02-01T00:05:00Z",
  "updated_at": "2026-02-01T00:05:00Z"
}

Note

Los campos billing_name, billing_tax_id y billing_address son snapshots inmutables tomados del perfil de facturación al momento de generar la factura. Esto garantiza que la factura sea legalmente válida incluso si el cliente cambia sus datos fiscales posteriormente.

Suscripciones — `/billing/api/subscriptions/`

Gestión de suscripciones activas que enlazan tenants con planes de precios.

Métodos
Método	Endpoint	Descripción
`GET`	`/billing/api/subscriptions/`	Listar suscripciones
`POST`	`/billing/api/subscriptions/`	Crear suscripción
`GET`	`/billing/api/subscriptions/{id}/`	Detalle de suscripción
`POST`	`/billing/api/subscriptions/{id}/cancel/`	Cancelar suscripción
`POST`	`/billing/api/subscriptions/{id}/pause/`	Pausar suscripción
`POST`	`/billing/api/subscriptions/{id}/resume/`	Reanudar suscripción

Respuesta de suscripción:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "tenant": 1,
  "plan": 2,
  "status": "active",
  "custom_price": null,
  "resource_type": "hosting_site",
  "resource_id": 1,
  "resource_name": "example.com - Plan M",
  "started_at": "2026-01-01T00:00:00Z",
  "current_period_start": "2026-02-01T00:00:00Z",
  "current_period_end": "2026-02-28T23:59:59Z",
  "cancelled_at": null,
  "stripe_subscription_id": "",
  "paypal_subscription_id": ""
}

Registros de Uso — `/billing/api/usage/`

Endpoint de solo lectura para consultar registros de consumo (VPS por horas, almacenamiento adicional, etc.).

Métodos
Método	Endpoint	Descripción
`GET`	`/billing/api/usage/`	Listar registros de uso
`GET`	`/billing/api/usage/{id}/`	Detalle de un registro

Respuesta:

{
  "id": 100,
  "subscription": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "resource_type": "vm",
  "resource_id": 5,
  "resource_name": "vps-basic-01",
  "period_start": "2026-02-01T00:00:00Z",
  "period_end": "2026-02-01T01:00:00Z",
  "quantity": "1.0000",
  "unit": "hours",
  "unit_price": "0.0139",
  "total": "0.0139",
  "invoiced": false
}

Planes de Precios — `/billing/api/plans/`

Catálogo de planes de precios configurables. Lectura para todos los autenticados, escritura solo para administradores.

Métodos
Método	Endpoint	Descripción
`GET`	`/billing/api/plans/`	Listar planes activos
`GET`	`/billing/api/plans/{slug}/`	Detalle de un plan (por slug)
`POST`	`/billing/api/plans/`	Crear plan (admin)
`PUT`	`/billing/api/plans/{slug}/`	Actualizar plan (admin)
`DELETE`	`/billing/api/plans/{slug}/`	Desactivar plan (admin)

Respuesta de plan:

{
  "id": 2,
  "name": "Hosting Plan M",
  "slug": "hosting-plan-m",
  "description": "Hosting compartido con 10 sitios, 5 BBDDs, 10GB",
  "resource_type": "hosting",
  "billing_period": "monthly",
  "price": "29.9500",
  "setup_fee": "0.00",
  "currency": "EUR",
  "hosting_package": 2,
  "tax_rate": "21.00",
  "is_active": true
}

Pagos — `/billing/api/payments/`

Registro de pagos recibidos (Stripe, PayPal, transferencia, manual). Solo lectura.

Métodos
Método	Endpoint	Descripción
`GET`	`/billing/api/payments/`	Listar pagos
`GET`	`/billing/api/payments/{id}/`	Detalle de un pago

Respuesta de pago:

{
  "id": "c8d9e0f1-2345-6789-abcd-ef0123456789",
  "invoice": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant": 1,
  "amount": "60.38",
  "currency": "EUR",
  "gateway": "stripe",
  "status": "completed",
  "gateway_payment_id": "pi_3Abc123Def456Ghi",
  "paid_at": "2026-02-05T15:30:00Z",
  "notes": ""
}

Integración ERP/CRM 

El formato JSON de las facturas está diseñado para importación directa en sistemas ERP y CRM. Campos clave para la integración:

Campos para ERP
Campo	Uso en ERP
`number`	Número de factura único (INV-YYYY-NNNN)
`billing_tax_id`	NIF/CIF/VAT del cliente
`billing_name`	Razón social del cliente
`billing_address`	Dirección fiscal completa
`subtotal`	Base imponible
`tax_rate`	Porcentaje de IVA aplicado
`tax_amount`	Cuota de IVA
`total`	Total factura (subtotal + IVA)
`currency`	Moneda ISO 4217 (EUR, USD, etc.)
`items[]`	Líneas de factura con desglose

Endpoints de Facturación

Facturas — /billing/api/invoices/

Filtros disponibles

Suscripciones — /billing/api/subscriptions/

Registros de Uso — /billing/api/usage/

Planes de Precios — /billing/api/plans/

Pagos — /billing/api/payments/

Integración ERP/CRM