Skip to content
Guida del Centro assistenza · Fatturazione e pagamenti
3 min di letturaVerificato 2026-11-16

Fatture e storico pagamenti

Consulta addebiti mensili/annuali, scarica fatture PDF ufficiali e verifica i dettagli del prossimo rinnovo.

In questa guida

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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CICLO DI VITA DELLA FATTURA, STREAMING PDF E SALDO
FASE 01 EVENTO DI CICLO DI FATTURAZIONE / CONGUAGLIO
Rinnovo abbonamento, upgrade del piano (change) o sottoscrizione add-on
Acquisisce snapshot di ragione sociale, indirizzo e vatNumber/taxId
FASE 02 MACCHINA A STATI DELLA FATTURA (Billing API)
+[ PAID ] (Addebito automatico riuscito) [ PENDING / OPEN ]-+[ OVERDUE ]POST/invoices/:id/pay (In attesa di saldo) | (Usa metodo predef.)
+[ VOID / CANCELLED ] (Fattura annullata)
FASE 03 RECUPERO FATTURE E STREAMING PDF
GET/api/v1/billing/invoices (Cronologia paginata ?page=&limit=)
GET/api/v1/billing/invoices/:id (Voci, crediti, ripartizione IVA/imposte)
GET/api/v1/billing/invoices/:id/download (Stream binario application/pdf)

Importante: I metadati di fatturazione aziendale (companyName, address, taxId e vatNumber tramite PUT /api/v1/billing/settings e PUT /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 statusSignificato contabileAzione consigliata per l'operatore
PAIDIl 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_PAIDLa 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.
OVERDUEIl 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 / VOIDLa 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)

EndpointVerbo HTTPDescrizione
/api/v1/billing/invoicesGETElenca le fatture del workspace con paginazione (?page=1&limit=20).
/api/v1/billing/invoices/:idGETRecupera 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/downloadGETTrasmette la fattura fiscale dettagliata ufficiale come allegato application/pdf.
/api/v1/billing/invoices/:id/payPOSTSalda o ritenta la riscossione di una fattura in sospeso o scaduta utilizzando il metodo di pagamento attivo del workspace.
/api/v1/billing/invoices/:id/cancelPOSTAnnulla una fattura aperta non ancora pagata.
/api/v1/billing/historyGETRestituisce 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)

HTTP
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)

JSON
{
  "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)

HTTP
GET /api/v1/billing/invoices/inv_01933220-5a11-7e00-9c44-887766554433/download HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
HTTP
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):

HTTP
POST /api/v1/billing/invoices/inv_01933299-1b22-7c00-8d11-223344556677/pay HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "invoiceId": "inv_01933299-1b22-7c00-8d11-223344556677",
  "status": "PAID",
  "paidAt": "2026-11-16T10:36:45.000Z",
  "amountPaidCents": 17731
}

Documentazione correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.