Citește datele de facturare
Citește prin API ediția, abonamentul, facturile și profilul de facturare ale organizației tale și ce nu poate schimba o cheie API.
Ghidul arată cum citești prin API datele de facturare ale organizației tale: ediția și abonamentul, facturile și profilul de facturare. O cheie API poate doar să citească datele de facturare. Cumpărarea, schimbarea sau anularea unui abonament și editarea profilului de facturare se fac în panou.
De ce ai nevoie
Secțiune intitulată „De ce ai nevoie”- O cheie API cu scope-ul
billing:read(scope-uri). Nu există scopebilling:write. - Un utilizator care are voie să vadă facturarea. O poate citi doar administratorul organizației: o cheie a
unui revânzător sau a unui client primește
403.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
1. Citește ediția și abonamentul
Secțiune intitulată „1. Citește ediția și abonamentul”GET /api/v1/billing răspunde cu starea facturării organizației.
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": []
}
}
editionestefree,prosauenterprise.stateestefree,activesaugrace. Îngraceo plată a eșuat: ediția rămâne până lagrace_until(iargrace_days_leftnumără zilele), apoi organizația revine la Free. Nu se șterge nimic.billable_serverseste numărul serverelor înrolate și nerevocate; abonamentul facturează cel puțin unul.subscriptiondescrie abonamentul plătit, dacă există.cancel_at_period_endarată că o anulare este programată; ediția durează până lacurrent_period_end.packageslistează stocarea de backup și releul de e-mail adăugate de tine.profile_completearată dacă profilul de facturare are ce îi trebuie unei plăți.
2. Listează facturile
Secțiune intitulată „2. Listează facturile”GET /api/v1/billing/invoices listează facturile emise de Stripe, începând cu cele mai noi. Este
paginat cu limit și 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/…"
}
statusestedraft,open,paid,uncollectiblesauvoid.- Sumele (
subtotal,tax,total,amount_paid,amount_refunded, precum șiamountșiunit_amountdinlines) sunt numere întregi, în cea mai mică unitate a monedeicurrency. Împarte la 100 ca să le afișezi și afișează-le cu moneda facturii. linesare câte o intrare pentru fiecare taxare, cuquantity,proration(o taxare sau un credit pentru o parte din perioadă) și TVA-ul liniei:vat_rate,vat_amountșivat_category(un cod UNCL5305:S,AE,O,ZsauE;vat_exemption_codecând TVA-ul nu se aplică).hosted_invoice_urldeschide pagina facturii la Stripe, iarinvoice_pdf_urldescarcă PDF-ul; ambele sunt adrese ale paginilor Stripe, deci deschide-le într-un browser în loc să le trimiți cheia ta API.
3. Citește profilul de facturare
Secțiune intitulată „3. Citește profilul de facturare”GET /api/v1/billing/profile este cumpărătorul de pe facturi: firma, adresa și identificatorii fiscali.
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 este none, pending (verificarea în VIES nu a fost încă posibilă; TVA-ul se percepe ca fără cod
de TVA până reușește) sau valid. Când organizația nu a salvat niciodată un profil, răspunsul este 404.
Ca la orice GET, răspunsurile poartă un ETag: trimite-l înapoi în If-None-Match și un răspuns neschimbat
este 304. Vezi ETag-uri.
Ce nu poate face o cheie
Secțiune intitulată „Ce nu poate face o cheie”Plata, schimbarea planului sau a pachetelor, anularea, reluarea, portalul clientului și salvarea profilului de
facturare cer o sesiune autentificată. Cu o cheie API răspund 403 api_key_not_allowed, oricare ar fi
scope-urile cheii. Fă-le din pagina Facturare a panoului.
| Status | Cod | Ce înseamnă |
|---|---|---|
401 |
invalid_api_key |
Cheia lipsește, a expirat sau a fost revocată. |
403 |
Cheia nu are scope billing:read, sau utilizatorul nu este administrator. |
|
403 |
api_key_not_allowed |
Operația cere o sesiune autentificată (vezi mai sus). |
404 |
Nu s-a salvat încă niciun profil de facturare. |
Erorile sunt problem details: decide după code.
Evenimente
Secțiune intitulată „Evenimente”Evenimentul invoice.ready este rezervat facturării și nu se trimite încă (lista evenimentelor).
Până atunci, citește facturile periodic.
Legături utile
Secțiune intitulată „Legături utile”- Facturare și ediții: ediții, pachete, TVA, plăți eșuate și rambursări. Sumele sunt pe pagina de prețuri.
- Referința API: fiecare operație
billing, cu câmpurile ei. - Convențiile API: erori, paginare și ETag-uri.
- Autentificare și chei API: scope-uri și folosirea cheilor.