Factures

Lister les factures

GET /v1/invoices

Paramètres de requête :

Paramètre	Type	Description
`skip`	integer	Pagination — offset
`take`	integer	Pagination — limite (max 100)
`search`	string	Recherche par référence ou client
`status`	string	Filtrer par statut : `DRAFT`, `SENT`, `PAID`, `OVERDUE`, `CANCELLED`
`clientId`	string	Filtrer par client
`from`	date	Date de début (ISO 8601)
`to`	date	Date de fin (ISO 8601)

Réponse :

{
  "data": [
    {
      "id": "clx1234abcd",
      "reference": "FAC-2026-0042",
      "status": "SENT",
      "issueDate": "2026-05-01T00:00:00Z",
      "dueDate": "2026-05-31T00:00:00Z",
      "totalHT": 500000,
      "totalTVA": 90000,
      "totalTTC": 590000,
      "currency": "XOF",
      "client": {
        "id": "clx5678efgh",
        "name": "SARL MonClient",
        "email": "contact@monclient.com"
      }
    }
  ],
  "total": 142
}

Obtenir une facture

GET /v1/invoices/{id}

Retourne les détails complets d'une facture, incluant les lignes de facturation.

Créer une facture

POST /v1/invoices

Corps de la requête :

{
  "clientId": "clx5678efgh",
  "issueDate": "2026-05-01",
  "dueDate": "2026-05-31",
  "currency": "XOF",
  "notes": "Facture pour le projet XYZ",
  "lines": [
    {
      "productId": "clxprd001",
      "description": "Développement web",
      "quantity": 10,
      "unitPrice": 50000,
      "taxRateId": "clxtax001",
      "discount": 0
    }
  ]
}

Réponse : 201 Created avec l'objet facture créé.

Cycle de vie recommandé

Créer la facture en brouillon.
Vérifier les totaux et la date d'échéance.
Valider (/validate) pour figer le document.
Envoyer (/send) au client.
Enregistrer les paiements (/payments) jusqu'au solde.

Valider une facture

POST /v1/invoices/{id}/validate

Passe la facture de DRAFT à SENT et génère le numéro définitif.

Contraintes métier

Une facture sans ligne ne doit pas être validée.
Après validation, la modification directe doit être restreinte.
Le cumul des paiements ne doit pas dépasser le total TTC.
dueDate doit être supérieure ou égale à issueDate.

Envoyer par email

POST /v1/invoices/{id}/send

Corps optionnel :

{
  "to": "client@example.com",
  "subject": "Votre facture FAC-2026-0042",
  "message": "Veuillez trouver ci-joint votre facture."
}

Enregistrer un paiement

POST /v1/invoices/{id}/payments

{
  "amount": 590000,
  "date": "2026-05-15",
  "method": "WAVE",
  "reference": "WAVE-TXN-123456",
  "notes": "Virement Wave du 15 mai"
}

Erreurs fréquentes

Code HTTP	`error.code`	Cas typique
`400`	`VALIDATION_ERROR`	Date invalide, ligne invalide, montant non conforme
`404`	`NOT_FOUND`	Facture introuvable
`409`	`CONFLICT`	Transition d'état invalide (ex. validation impossible)
`422`	`BUSINESS_RULE_ERROR`	Paiement supérieur au solde

Exemple de conflit métier :

{
  "error": {
    "code": "BUSINESS_RULE_ERROR",
    "message": "Le montant du paiement dépasse le solde restant."
  }
}

Télécharger le PDF

GET /v1/invoices/{id}/pdf

Retourne le fichier PDF de la facture (Content-Type: application/pdf).

Bonnes pratiques d'intégration

Traitez la validation comme une étape explicite de workflow (pas implicite).
Synchronisez les statuts de facture dans votre système tiers via polling ou webhooks.
Journalisez les tentatives d'envoi email et les échecs pour faciliter le support.

On this page