Présentation
Les administrateurs de facturation autorisés peuvent inspecter l'historique complet de facturation (GET /api/v1/billing/history), le détail des lignes (invoice line item type) et les statuts de règlement des paiements sous Settings -> Billing -> Invoices (/settings/billing/invoices). Propulsé par Billing API (/api/v1/billing/invoices* et GET /api/v1/billing/tax-profile/datev-export), Passinstance génère des factures fiscales PDF conformes à la TVA pour chaque renouvellement d'abonnement, ajustement au prorata en cours de cycle et frais d'options modulaires, tout en permettant l'exécution immédiate du paiement ou l'annulation des factures ouvertes.
Cycle de vie de génération et de règlement des factures
Important : Les métadonnées de facturation de l'entreprise (
companyName,address,taxIdetvatNumberviaPUT /api/v1/billing/settingsetPUT /api/v1/billing/tax-profile) sont figées sur chaque facture au moment de sa finalisation. Maintenez vos coordonnées fiscales à jour dans les Paramètres de l'entreprise avant votre date de renouvellement.
Statut de facture (invoice status), cycle de vie et types de lignes
Les factures suivent à la fois un cycle de vie administratif (invoice lifecycle state : DRAFT | OPEN | CLOSED | VOID) et un statut de règlement de paiement (invoice status), tandis que les lignes détaillées utilisent invoice line item type (BASE_SUBSCRIPTION | ADD_ON | ACTIVE_PASSES_INCLUDED | ACTIVE_PASSES_OVERAGE | USAGE_EMAIL | USAGE_SMS | CREDIT_NOTE | ADJUSTMENT | TAX) :
| invoice status | Signification comptable | Action recommandée pour l'opérateur |
|---|---|---|
PAID | Le paiement a été capturé et réglé avec succès via le moyen de paiement par défaut de l'espace de travail. | Téléchargez le reçu fiscal PDF officiel via /download pour votre grand livre comptable. |
PENDING / PARTIALLY_PAID | La facture a été finalisée (OPEN) et attend la capture du paiement ou le règlement du solde partiel. | Vérifiez votre instrument de paiement par défaut dans Moyens de paiement et déclenchez POST /api/v1/billing/invoices/:id/pay. |
OVERDUE | Le paiement automatisé a échoué au-delà de la fenêtre de prélèvement initiale (par ex., carte expirée ou défi 3DS requis). | Mettez à jour la carte ou le mandat dans /settings/billing/payment-method et relancez POST /api/v1/billing/invoices/:id/pay. |
CANCELLED / VOID | La facture a été annulée (POST /api/v1/billing/invoices/:id/cancel) ou invalidée avant son encaissement. | Aucun paiement n'est dû ; conservez l'enregistrement pour l'exhaustivité de vos audits si nécessaire. |
Référence de l'API de gestion des factures (Billing API)
| Point de terminaison | Verbe HTTP | Description |
|---|---|---|
/api/v1/billing/invoices | GET | Liste les factures paginées de l'espace de travail (?page=1&limit=20). |
/api/v1/billing/invoices/:id | GET | Récupère la ventilation détaillée de la facture, y compris les lignes (invoice line item type), les taux de taxe, les mentions de TVA et les tentatives de paiement. |
/api/v1/billing/invoices/:id/download | GET | Diffuse la facture fiscale officielle détaillée sous forme de pièce jointe application/pdf. |
/api/v1/billing/invoices/:id/pay | POST | Règle ou relance l'encaissement d'une facture en attente ou en retard à l'aide du moyen de paiement actif de l'espace de travail. |
/api/v1/billing/invoices/:id/cancel | POST | Annule une facture ouverte impayée. |
/api/v1/billing/history | GET | Renvoie l'historique chronologique des événements de facturation et de paiement de l'espace de travail. |
1. Inspection détaillée des lignes de facture et de la TVA (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>
Charge utile de réponse (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. Téléchargement des factures fiscales PDF en flux continu (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. Relance du paiement sur une facture ouverte ou en retard (POST /api/v1/billing/invoices/:id/pay)
Mettez à jour votre instrument de paiement par défaut sous Settings -> Billing -> Payment Method (/settings/billing/payment-method), puis déclenchez l'encaissement (aucun corps de requête n'est requis) :
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
}
Documentation connexe
-
Configurez les métadonnées fiscales de l'entreprise et les numéros de TVA dans Paramètres de l'entreprise.
-
Ajoutez ou mettez à jour vos cartes bancaires, PayPal ou Mobile Money dans Moyens de paiement.
-
Exportez les données de l'espace de travail et les journaux de conformité dans Exportations de données et rapports.
