Panoramica
Gli amministratori della fatturazione autorizzati possono ispezionare la cronologia completa dei record di fatturazione (GET /api/v1/billing/history), il dettaglio delle singole voci (invoice line item type) e gli stati di regolamento dei pagamenti in Impostazioni -> Fatturazione -> Fatture (/settings/billing/invoices). Grazie a Billing API (/api/v1/billing/invoices* e GET /api/v1/billing/tax-profile/datev-export), Passinstance genera fatture fiscali in PDF conformi alla normativa IVA per ogni rinnovo dell'abbonamento, conguaglio proporzionale di metà ciclo e addebito per componenti aggiuntivi modulari, consentendo inoltre l'esecuzione immediata del pagamento o l'annullamento delle fatture aperte.
Ciclo di vita della generazione e del saldo delle fatture
Importante: I metadati di fatturazione aziendale (
companyName,address,taxIdevatNumbertramitePUT /api/v1/billing/settingsePUT /api/v1/billing/tax-profile) vengono fissati in modo immutabile su ciascuna fattura al momento della finalizzazione. Mantenga aggiornati i Suoi dati fiscali in Impostazioni aziendali prima della data di rinnovo.
Stato della fattura (invoice status), ciclo di vita e tipologie di voci
Le fatture tracciano sia un ciclo di vita amministrativo (invoice lifecycle state: DRAFT | OPEN | CLOSED | VOID) sia uno stato di regolamento del pagamento (invoice status), mentre le singole righe di dettaglio utilizzano invoice line item type (BASE_SUBSCRIPTION | ADD_ON | ACTIVE_PASSES_INCLUDED | ACTIVE_PASSES_OVERAGE | USAGE_EMAIL | USAGE_SMS | CREDIT_NOTE | ADJUSTMENT | TAX):
| invoice status | Significato contabile | Azione consigliata per l'operatore |
|---|---|---|
PAID | Il pagamento è stato acquisito e saldato correttamente tramite il metodo di pagamento predefinito del workspace. | Scarichi la ricevuta fiscale ufficiale in PDF tramite /download per il Suo registro contabile. |
PENDING / PARTIALLY_PAID | La fattura è stata finalizzata (OPEN) ed è in attesa dell'acquisizione del pagamento o del saldo parziale. | Verifichi lo strumento di pagamento predefinito in Metodi di pagamento e avvii POST /api/v1/billing/invoices/:id/pay. |
OVERDUE | Il pagamento automatico non è andato a buon fine oltre la finestra di addebito iniziale (ad es. carta scaduta o richiesta verifica 3DS). | Aggiorni la carta o il mandato in /settings/billing/payment-method e riprovi con POST /api/v1/billing/invoices/:id/pay. |
CANCELLED / VOID | La fattura è stata cancellata (POST /api/v1/billing/invoices/:id/cancel) o annullata prima della riscossione. | Nessun pagamento dovuto; conservi il record per completezza di audit, se necessario. |
Riferimento API per la gestione delle fatture (Billing API)
| Endpoint | Verbo HTTP | Descrizione |
|---|---|---|
/api/v1/billing/invoices | GET | Elenca le fatture del workspace con paginazione (?page=1&limit=20). |
/api/v1/billing/invoices/:id | GET | Recupera il dettaglio completo della fattura, incluse le voci (invoice line item type), le aliquote fiscali, le note IVA e i tentativi di pagamento. |
/api/v1/billing/invoices/:id/download | GET | Trasmette la fattura fiscale dettagliata ufficiale come allegato application/pdf. |
/api/v1/billing/invoices/:id/pay | POST | Salda o ritenta la riscossione di una fattura in sospeso o scaduta utilizzando il metodo di pagamento attivo del workspace. |
/api/v1/billing/invoices/:id/cancel | POST | Annulla una fattura aperta non ancora pagata. |
/api/v1/billing/history | GET | Restituisce la cronologia degli eventi di fatturazione e pagamento del workspace. |
1. Ispezione dettagliata delle voci di fattura e dell'IVA (GET /api/v1/billing/invoices/:id)
GET /api/v1/billing/invoices/inv_01933220-5a11-7e00-9c44-887766554433 HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Payload di risposta (200 OK)
{
"id": "inv_01933220-5a11-7e00-9c44-887766554433",
"invoiceNumber": "PI-2026-004891",
"status": "PAID",
"lifecycle": "CLOSED",
"currency": "EUR",
"issuedAt": "2026-11-16T09:00:00.000Z",
"paidAt": "2026-11-16T09:00:04.000Z",
"customerDetails": {
"companyName": "Phenix Hospitality GmbH",
"vatNumber": "DE301928374",
"address": "Friedrichstrasse 114A, 10117 Berlin, DE"
},
"lineItems": [
{
"kind": "BASE_SUBSCRIPTION",
"description": "Growth Plan (2,000 Active Passes) — Monthly",
"quantity": 1,
"unitAmountCents": 12000,
"amountCents": 12000
},
{
"kind": "ADD_ON",
"description": "Custom Vanity Domain & Branded Email Add-On",
"quantity": 1,
"unitAmountCents": 2900,
"amountCents": 2900
}
],
"subtotalCents": 14900,
"taxRatePercent": 19.0,
"taxCents": 2831,
"totalCents": 17731
}
2. Streaming delle fatture fiscali in PDF (GET /api/v1/billing/invoices/:id/download)
GET /api/v1/billing/invoices/inv_01933220-5a11-7e00-9c44-887766554433/download HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-PI-2026-004891.pdf"
3. Nuovo tentativo di pagamento su una fattura aperta o scaduta (POST /api/v1/billing/invoices/:id/pay)
Aggiorni lo strumento di pagamento predefinito in Impostazioni -> Fatturazione -> Metodo di pagamento (/settings/billing/payment-method), quindi avvii la riscossione (non è richiesto alcun corpo della richiesta):
POST /api/v1/billing/invoices/inv_01933299-1b22-7c00-8d11-223344556677/pay HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"invoiceId": "inv_01933299-1b22-7c00-8d11-223344556677",
"status": "PAID",
"paidAt": "2026-11-16T10:36:45.000Z",
"amountPaidCents": 17731
}
Documentazione correlata
-
Configuri i metadati fiscali aziendali e i numeri di Partita IVA in Impostazioni aziendali.
-
Aggiunga o aggiorni carte di credito, PayPal o Mobile Money in Metodi di pagamento.
-
Esporti i dati del workspace e i log di conformità in Esportazione dati e reportistica.
