Ir al contenido

Lee los datos de facturación

Lee a través de la API la edición, la suscripción, las facturas y el perfil de facturación de tu organización, y lo que una clave no puede cambiar.

Esta guía muestra cómo leer con la API los datos de facturación de tu organización: la edición y la suscripción, las facturas y el perfil de facturación. Una clave de API solo puede leer los datos de facturación. Contratar, cambiar o cancelar una suscripción y editar el perfil de facturación se hace en el panel.

  • Una clave de API con el scope billing:read (scopes). No existe un scope billing:write.
  • Un usuario que pueda ver la facturación. Solo la pueden leer los administradores de la organización: la clave de un revendedor o de un cliente recibe 403.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"

GET /api/v1/billing responde con el estado de la facturación de la organización.

curl -fsS "$PLUSPANEL_URL/api/v1/billing" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY"
{
  "edition": "pro",
  "state": "active",
  "managed": true,
  "billable_servers": 3,
  "profile_complete": true,
  "subscription": {
    "plan": "pro_monthly",
    "status": "active",
    "servers": 3,
    "current_period_end": "2026-12-01T00:00:00Z",
    "cancel_at_period_end": false,
    "packages": []
  }
}
  • edition es free, pro o enterprise.
  • state es free, active o grace. En grace ha fallado un pago: la edición se mantiene hasta grace_until (y grace_days_left cuenta los días), y después la organización vuelve a Free. No se elimina nada.
  • billable_servers es el número de servidores inscritos y no revocados; la suscripción factura al menos uno.
  • subscription describe la suscripción de pago, si la hay. cancel_at_period_end indica que hay una cancelación programada; la edición dura hasta current_period_end. packages lista el almacenamiento de copias de seguridad y el relé de correo que añadiste.
  • profile_complete indica si el perfil de facturación tiene lo que necesita un pago.

GET /api/v1/billing/invoices lista las facturas que emitió Stripe, las más recientes primero. Está paginado con limit y cursor.

curl -fsS -G "$PLUSPANEL_URL/api/v1/billing/invoices" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" \
  --data-urlencode "limit=12" \
  | jq '.items[] | {number, status, issued_at, currency, total, hosted_invoice_url}'
{
  "number": "PP-2026-0042",
  "status": "paid",
  "issued_at": "2026-11-01T00:00:12Z",
  "currency": "eur",
  "total": 0,
  "hosted_invoice_url": "https://invoice.stripe.com/…"
}
  • status es draft, open, paid, uncollectible o void.
  • Los importes (subtotal, tax, total, amount_paid, amount_refunded, y amount y unit_amount en lines) son números enteros en la unidad más pequeña de currency. Divide entre 100 para mostrarlos y muéstralos con la moneda de la factura.
  • lines tiene una entrada por cada cargo, con quantity, proration (un cargo o un abono de parte del periodo) y el IVA de la línea: vat_rate, vat_amount y vat_category (un código UNCL5305: S, AE, O, Z o E; vat_exemption_code cuando no se aplica el IVA).
  • hosted_invoice_url abre la página de la factura en Stripe e invoice_pdf_url descarga el PDF; ambas son direcciones de páginas de Stripe, así que ábrelas en un navegador en lugar de enviarles tu clave de API.

GET /api/v1/billing/profile es el comprador que aparece en las facturas: la empresa, su dirección y sus identificadores fiscales.

curl -fsS "$PLUSPANEL_URL/api/v1/billing/profile" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" \
  | jq '{legal_name, country, vat_id, vat_status, complete}'

vat_status es none, pending (la comprobación en VIES aún no fue posible; el IVA se cobra como si no hubiera número de IVA hasta que tenga éxito) o valid. Cuando la organización nunca ha guardado un perfil, la respuesta es 404.

Como todo GET, estas respuestas llevan un ETag: envíalo de vuelta en If-None-Match y una respuesta sin cambios es 304. Consulta ETags.

El pago, el cambio de plan o de paquetes, la cancelación, la reanudación, el portal del cliente y guardar el perfil de facturación necesitan una sesión iniciada. Con una clave de API responden 403 api_key_not_allowed, sean cuales sean los scopes de la clave. Hazlo desde la página Facturación del panel.

Estado Código Qué significa
401 invalid_api_key La clave falta, ha caducado o se ha revocado.
403 La clave no tiene scope billing:read, o el usuario no es administrador.
403 api_key_not_allowed La operación necesita una sesión iniciada (ver arriba).
404 Todavía no se ha guardado ningún perfil de facturación.

Los errores son problem details: decide según code.

El evento invoice.ready está reservado para la facturación y todavía no se envía (lista de eventos). Hasta entonces, lee las facturas de forma periódica.