FACTURATION · v1.0

Factures

Créez une facture multi-lignes avec numérotation automatique et échéance, puis partagez-la à votre client. Il la règle sur une page SigmaPay hébergée, sans code côté client.

Introduction

Une facture regroupe plusieurs lignes (description, quantité, prix unitaire) et calcule automatiquement le total. Chaque facture a un numéro séquentiel (INV-0001), un statut (brouillon, envoyée, payée, en retard, annulée) et une page publique dédiée.

Cas d'usage typiques : Frais de scolarité multi-postes · Devis de prestation · Facturation récurrente manuelle · Vente avec plusieurs articles

Comme pour les liens de paiement, SigmaPay ne gère pas l'envoi automatique par email — vous récupérez l'URL de la facture et la partagez vous-même (email, SMS, WhatsApp).

Créer une facture

POST/api/v1/invoices

Champ	Type	Requis	Description
items	array	Oui	Lignes de la facture : { description, quantity, unitPrice }. Au moins une ligne.
customerName	string	Non	Nom du client affiché sur la facture.
customerEmail	string	Non	Email du client.
customerPhone	string	Non	Téléphone du client.
dueDate	string	Non	Date d'échéance ISO 8601. Passé cette date, la facture apparaît "en retard".
notes	string	Non	Notes libres affichées sur la page de paiement.
metadata	object	Non	Données libres associées à la facture.
draft	boolean	Non	Créer en brouillon (non visible du client tant que non envoyée). Défaut : false.

JavaScript

const res = await fetch('https://bluepay.myfad.org/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sigmapay_live_votre_cle',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerName: 'Aïssatou Ndiaye',
    customerEmail: 'aissatou@example.sn',
    dueDate: '2026-08-31T23:59:59Z',
    items: [
      { description: 'Frais de scolarité S1', quantity: 1, unitPrice: 1750000 },
      { description: 'Frais d\'inscription',   quantity: 1, unitPrice: 250000 },
    ],
  }),
});

const invoice = await res.json();
// invoice.number = "INV-0001"
// invoice.total  = 2000000  (20 000 XOF)
console.log('Facture :', `https://bluepay.myfad.org/invoice/${invoice.slug}`);

JSON (réponse)

{
  "id": "clxyz9012ijkl",
  "number": "INV-0001",
  "slug": "a1b2c3d4e5f6",
  "customerName": "Aïssatou Ndiaye",
  "customerEmail": "aissatou@example.sn",
  "currency": "XOF",
  "status": "SENT",
  "dueDate": "2026-08-31T23:59:59.000Z",
  "items": [
    { "id": "item1", "description": "Frais de scolarité S1", "quantity": 1, "unitPrice": 1750000 },
    { "id": "item2", "description": "Frais d'inscription", "quantity": 1, "unitPrice": 250000 }
  ],
  "total": 2000000,
  "createdAt": "2026-07-21T10:00:00.000Z"
}

Cycle de statut

Statut	Signification
DRAFT	Brouillon — non visible ni payable par le client. Modifiable librement.
SENT	Envoyée — visible et payable via la page publique.
PAID	Payée — un paiement a été confirmé pour cette facture.
OVERDUE	En retard — dérivé automatiquement quand une facture SENT dépasse sa date d'échéance.
CANCELLED	Annulée — ne peut plus être payée. Impossible sur une facture déjà payée.

Une facture créée en DRAFT peut être modifiée (lignes, client, échéance) puis envoyée via POST /api/v1/invoices/:id/send. Une fois envoyée, elle devient payable et n'est plus modifiable.

QR code

Chaque facture envoyée a automatiquement un QR code à afficher ou imprimer — pratique sur une facture papier. Le QR encode l'URL de la facture : le client le scanne et arrive directement sur la page de paiement.

GET/invoice/:slug/qrcode

Retourne directement une image PNG (320×320px) — utilisable telle quelle dans une balise <img src="...">, aucune authentification requise.

HTML

<img src="https://bluepay.myfad.org/invoice/a1b2c3d4e5f6/qrcode" alt="Payer la facture par QR code" />

Gérer les factures

Méthode	Endpoint	Action
GET	/api/v1/invoices	Lister toutes vos factures
GET	/api/v1/invoices/:id	Détail d'une facture (lignes, total, statut)
PATCH	/api/v1/invoices/:id	Modifier une facture en brouillon
POST	/api/v1/invoices/:id/send	Envoyer une facture en brouillon (devient payable)
POST	/api/v1/invoices/:id/cancel	Annuler une facture (sauf si déjà payée)

Essayer la facturation

Créez votre première facture depuis l'API en quelques minutes.

Swagger →Liens de paiement →