Aller au contenu principal

Factures

Bêta

Fonctionnalité en cours de déploiement. L'interface décrite ici est celle de la prochaine livraison : elle peut encore évoluer, et n'est pas forcément activée sur votre tenant.

À quoi ça sert​

Chaque paiement réussi produit une facture, chaque remboursement un avoir, à votre nom et avec vos mentions légales (le bloc invoicing de votre compte de paiement). Vous n'avez rien à générer : vous les lisez, les téléchargez, et les mettez à disposition de vos clients.

1. Lister et lire les factures​

curl -s "https://billing-api.dev.stackngo.fr/v1/invoices?customer_id=cus_01J9ZR1A2B3C4D5E6F7G" \
  -H "Authorization: Bearer $TOKEN"
{
  "data": [
    {
      "id": "inv_01J9ZS3E…",
      "kind": "invoice",
      "number": "ACME-2026-000042",
      "status": "paid",
      "issue_date": "2026-11-01",
      "period_start": "2026-10-01",
      "period_end": "2026-10-31",
      "currency": "EUR",
      "customer_id": "cus_01J9ZR1A2B3C4D5E6F7G",
      "payment_id": "pay_01J9ZS3D…",
      "lines": [ "…" ],
      "totals": { "subtotal": "76.50", "tax": "15.30", "total": "91.80", "taxes": [ "…" ] },
      "pdf_ready": true,
      "pdf_sha256": "9f2c…"
    }
  ],
  "next_cursor": "…"
}

Filtres : customer_id, kind (invoice ou credit_note), limit, cursor.

2. Télécharger le PDF​

curl -s -o ACME-2026-000042.pdf \
  https://billing-api.dev.stackngo.fr/v1/invoices/inv_01J9ZS3E…/pdf \
  -H "Authorization: Bearer $TOKEN"

Ce que vous obtenez​

  • Un PDF Factur-X : un PDF/A-3 lisible par un humain, qui embarque le fichier XML structuré (CII) lisible par un logiciel comptable. Profil EN16931 (complet, recommandé) ou BASIC, selon invoicing.facturxProfile.
  • Les mentions de votre compte : raison sociale, forme, SIREN, SIRET, TVA, RCS, capital, adresse, délai de paiement, pénalités de retard, mentions libres ; et celles de votre client (nom, adresse, SIREN et TVA s'ils sont fournis).
  • La TVA détaillée par catégorie et par taux.
  • Une empreinte pdf_sha256 : le PDF est produit une seule fois et ne change plus.

3. Ouvrir le portail client​

Plutôt que d'envoyer chaque PDF, donnez à votre client un lien vers son portail : ses factures et avoirs, ses abonnements et son moyen de paiement, qu'il peut remplacer.

curl -s -X POST https://billing-api.dev.stackngo.fr/v1/portal-links \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "customer_id": "cus_01J9ZR1A2B3C4D5E6F7G", "return_url": "https://shop.acme.example/compte", "ttl_seconds": 3600 }'
{ "url": "https://pay.dev.stackngo.fr/acme/…", "expires_at": "2026-10-08T11:40:00Z" }

Le lien est signé et à durée limitée (ttl_seconds de 300 s à 24 h) : générez-le au moment où votre client clique sur « Mes factures » dans votre application, et redirigez-le.

Ce que vous pouvez en attendre​

  • Numérotation continue, sans trou, au format <numberPrefix>-<année>-<numéro> ; les avoirs ont leur propre série. Avec numberingReset: yearly, la série repart à 1 chaque année.
  • Une facture émise est inaltérable : toute correction passe par un avoir.
  • Modifier votre bloc invoicing ne touche que les factures suivantes.
  • Les factures et avoirs sont conservés 10 ans.
  • Vous recevez invoice.finalized à chaque facture ou avoir émis : c'est le bon moment pour envoyer la facture à votre client.

Pas encore disponible​

  • La transmission aux plateformes de dématérialisation (PDP) pour la facturation électronique obligatoire : téléchargez vos Factur-X et transmettez-les vous-même.
  • Plusieurs devises dans une même facture.

Si ça ne marche pas​

Ce que vous voyezCauseCorrection
409 sur …/pdf, pdf_ready: falsele PDF est en cours de production, juste après le paiementréessayer quelques secondes plus tard, ou attendre invoice.finalized
404identifiant d'une facture d'un autre compte, ou faute de frappevérifier l'identifiant (inv_…)
Mention légale absente ou faussebloc invoicing incomplet au moment de l'émissioncorriger invoicing ; pour une facture déjà émise, émettre un avoir et refacturer
Le client voit « lien expiré » sur le portailttl_seconds dépasségénérer un nouveau lien à chaque visite

Voir aussi Dépannage des paiements.

Voir aussi​