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.
Qué necesitas
Sección titulada «Qué necesitas»- Una clave de API con el scope
billing:read(scopes). No existe un scopebilling: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_…"
1. Lee la edición y la suscripción
Sección titulada «1. Lee la edición y la suscripción»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": []
}
}
editionesfree,prooenterprise.stateesfree,activeograce. Engraceha fallado un pago: la edición se mantiene hastagrace_until(ygrace_days_leftcuenta los días), y después la organización vuelve a Free. No se elimina nada.billable_serverses el número de servidores inscritos y no revocados; la suscripción factura al menos uno.subscriptiondescribe la suscripción de pago, si la hay.cancel_at_period_endindica que hay una cancelación programada; la edición dura hastacurrent_period_end.packageslista el almacenamiento de copias de seguridad y el relé de correo que añadiste.profile_completeindica si el perfil de facturación tiene lo que necesita un pago.
2. Lista las facturas
Sección titulada «2. Lista las facturas»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/…"
}
statusesdraft,open,paid,uncollectibleovoid.- Los importes (
subtotal,tax,total,amount_paid,amount_refunded, yamountyunit_amountenlines) son números enteros en la unidad más pequeña decurrency. Divide entre 100 para mostrarlos y muéstralos con la moneda de la factura. linestiene una entrada por cada cargo, conquantity,proration(un cargo o un abono de parte del periodo) y el IVA de la línea:vat_rate,vat_amountyvat_category(un código UNCL5305:S,AE,O,ZoE;vat_exemption_codecuando no se aplica el IVA).hosted_invoice_urlabre la página de la factura en Stripe einvoice_pdf_urldescarga el PDF; ambas son direcciones de páginas de Stripe, así que ábrelas en un navegador en lugar de enviarles tu clave de API.
3. Lee el perfil de facturación
Sección titulada «3. Lee el perfil de facturación»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.
Lo que una clave no puede hacer
Sección titulada «Lo que una clave no puede hacer»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.
Errores
Sección titulada «Errores»| 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.
Eventos
Sección titulada «Eventos»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.
Relacionado
Sección titulada «Relacionado»- Facturación y ediciones: ediciones, paquetes, IVA, pagos fallidos y reembolsos. Los importes están en la página de precios.
- Referencia de la API: cada operación
billing, con sus campos. - Convenciones de la API: errores, paginación y ETags.
- Autenticación y claves de API: scopes y manejo de las claves.