Sari la conținut

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.

  • O cheie API cu scope-ul billing:read (scope-uri). Nu există scope billing: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_…"

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": []
  }
}
  • edition este free, pro sau enterprise.
  • state este free, active sau grace. În grace o plată a eșuat: ediția rămâne până la grace_until (iar grace_days_left numără zilele), apoi organizația revine la Free. Nu se șterge nimic.
  • billable_servers este numărul serverelor înrolate și nerevocate; abonamentul facturează cel puțin unul.
  • subscription descrie abonamentul plătit, dacă există. cancel_at_period_end arată că o anulare este programată; ediția durează până la current_period_end. packages listează stocarea de backup și releul de e-mail adăugate de tine.
  • profile_complete arată dacă profilul de facturare are ce îi trebuie unei plăți.

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/…"
}
  • status este draft, open, paid, uncollectible sau void.
  • Sumele (subtotal, tax, total, amount_paid, amount_refunded, precum și amount și unit_amount din lines) sunt numere întregi, în cea mai mică unitate a monedei currency. Împarte la 100 ca să le afișezi și afișează-le cu moneda facturii.
  • lines are câte o intrare pentru fiecare taxare, cu quantity, proration (o taxare sau un credit pentru o parte din perioadă) și TVA-ul liniei: vat_rate, vat_amount și vat_category (un cod UNCL5305: S, AE, O, Z sau E; vat_exemption_code când TVA-ul nu se aplică).
  • hosted_invoice_url deschide pagina facturii la Stripe, iar invoice_pdf_url descarcă PDF-ul; ambele sunt adrese ale paginilor Stripe, deci deschide-le într-un browser în loc să le trimiți cheia ta API.

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.

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.

Evenimentul invoice.ready este rezervat facturării și nu se trimite încă (lista evenimentelor). Până atunci, citește facturile periodic.