Factures

Une facture est un document que vous émettez, remettez à un client, puis attendez de voir payé. Wajub stocke les lignes, calcule les totaux, héberge la page de paiement et enregistre les montants réglés. Wajub ne relance personne et ne débite rien. Le produit se résume à un document avec une URL publique et un solde actualisé. Facturation et abonnements présente ce cycle. Cette page sert de référence pour l'objet lui-même.

La facturation est un produit live dont l'accès dépend de votre plan. Une clé sandbox renvoie 403 This feature is only available in live mode.. Un plan sans cette fonctionnalité renvoie 403 Invoicing is not available on your plan.. Une fois le plafond total d'un plan atteint, la réponse est 403 You have reached the maximum number of invoices for your plan.. Seuls les documents de type invoice comptent dans ce plafond.

Les huit appels

Voici toutes les opérations proposées par l'API pour les factures. /send est l'appel qui envoie une facture par e-mail, son PDF est un lien public (plus bas), et aucun endpoint ne débite un client.

{id} correspond à l'id renvoyé par l'API, soit la chaîne inv_.

L'objet facture

Tous les appels renvoient cet objet. items est présent chaque fois que la facture est chargée avec ses lignes, ce qui est le cas pour les huit appels.

invoice_number vaut null sur un brouillon et est attribué au premier envoi de la facture. Il vient de la numérotation de votre compte, la même séquence que celle du Dashboard, que vous envoyiez la facture ici ou là-bas : le préfixe (INV- si vous ne l'avez pas changé), l'année, puis un compteur à quatre chiffres, tels que réglés dans les paramètres de facturation du Dashboard. Le compteur repart à 0001 chaque année, sauf si vous l'avez désactivé, et un numéro est unique au sein de votre compte. status peut valoir draft, sent, viewed, partial, paid, overdue, cancelled ou refunded. Facturation et abonnements présente les transitions entre ces statuts et les webhooks émis.

customer désigne le client à qui la facture est adressée, par l'identifiant cus_ que renvoie l'API Clients, et vaut null quand vous l'avez adressée à un nom et un e-mail seulement. Le customer_id de la réponse désigne ce même client sous un autre identifiant : ignorez-le et rapprochez vos données sur customer.

language est la langue de l'e-mail et du PDF de la facture, fr ou en, enregistrée à la création de la facture, ici ou dans le Dashboard. accept est la restriction des moyens proposés au payeur sur la page de la facture, {} quand il n'y en a pas.

Deux champs sont calculés plutôt que stockés. amount_due vaut toujours total moins amount_paid, avec un minimum de zéro. Il ne devient donc jamais négatif en cas de trop-perçu. amount_paid ne change qu'avec mark-paid, un paiement effectué sur la page hébergée ou un avoir émis depuis le Dashboard, qui le diminue de son montant. Un paiement sur la page compte les trois : les paiements en ligne de la facture, plus ce que mark-paid a enregistré, moins ses avoirs. Une facture qui porte un avoir de 1 000 ne passe à paid qu'une fois 1 000 de plus que son total reçus.

Créer une facture

Les quatre champs obligatoires sont customer_name, items, invoice_date et currency. Tous les autres sont facultatifs. La facture est toujours créée avec draft, quelle que soit votre requête.

Chaque entrée de items constitue un objet distinct.

curl https://api.wajub.com/invoices \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Traoré & Fils",
    "customer_email": "[email protected]",
    "invoice_date": "2026-09-12",
    "payment_terms_days": 30,
    "currency": "XAF",
    "items": [
      { "name": "Consulting service", "quantity": 2, "unit_price": 150000, "tax_rate": 19.25 },
      { "name": "Onboarding", "quantity": 1, "unit_price": 100000, "discount_type": "percentage", "discount_value": 10 }
    ]
  }'

La création est le seul appel de facture qui respecte Idempotency-Key. Rejouer une création avec la même clé renvoie la première facture au lieu d'en émettre une seconde. Rejouer un appel send ou mark-paid l'exécute une nouvelle fois.

Les montants sont en unité principale

unit_price, subtotal, discount_amount, tax_amount, total et amount_paid sont tous exprimés dans l'unité principale de la devise : 150000 représente cent cinquante mille francs, et non mille cinq cents.

Les décimales sont acceptées. "unit_price": 1500.50 est enregistré tel quel, et un taux qui ne produit pas un résultat entier garde ses décimales : 19,25 % de 1 000 vaut 192,5. Wajub conserve deux décimales sur chaque montant.

Calcul d'une ligne

Chaque ligne effectue ses propres calculs à chaque enregistrement, dans l'ordre suivant. Vous envoyez les quatre premières valeurs. Les quatre autres sont calculées et renvoyées.

subtotal        = quantity × unit_price
discount_amount = discount_type = percentage  →  subtotal × discount_value / 100
                  discount_type = fixed       →  discount_value
                  otherwise                   →  0
taxable         = subtotal − discount_amount
tax_amount      = taxable × tax_rate / 100
total           = taxable + tax_amount

La taxe est exclusive. Elle est ajoutée à la ligne et n'en est jamais extraite. Elle est aussi calculée après la remise. Une remise de 10 % sur une ligne taxée réduit donc également la taxe.

La facture additionne ensuite les lignes.

subtotal   = Σ (quantity × unit_price)
tax_amount = Σ line tax_amount
total      = subtotal + tax_amount
amount_due = max(0, total − amount_paid)

Aucune remise globale sur une facture

Les remises s'appliquent par ligne. L'appel de création accepte également has_global_discount, global_discount_type et global_discount_value. Ces trois champs sont ignorés : ils sont validés et n'ont aucun effet. Ils ne produisent aucune erreur. Une facture envoyée avec une remise globale de 15 % est donc enregistrée au prix total tout en donnant l'impression d'avoir fonctionné.

Devis et estimations

document_type accepte quote et estimate, puis crée le document.

Paiement en plusieurs fois

Définissez payment_type sur split ou milestone, puis transmettez le calendrier. La page hébergée débite alors une échéance à la fois au lieu du solde total.

Le client ouvre la facture et voit la première échéance non payée. Son amount est débité dans la limite de l'amount_due restant. Après son règlement, Wajub marque cette échéance comme payée, ajoute le montant à amount_paid et fait passer la facture à partial. La visite suivante propose l'échéance suivante. La facture passe à paid lorsque amount_paid atteint le total. Si toutes les échéances sont réglées mais qu'un solde reste dû, la page propose le paiement du reste en une fois.

Lister les factures

GET /invoices renvoie vos factures live, de la plus récente à la plus ancienne, par groupes de vingt-cinq.

Un status, un payment_status, un sort_by ou un sort_dir hors de ces valeurs renvoie une 422 sur ce champ, comme un per_page hors limites. De même pour une borne de date qui n'est pas une date, ou une borne supérieure antérieure à la borne inférieure.

curl -G https://api.wajub.com/invoices \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -d status=overdue \
  -d customer_id=cus_7Kq2mX9vL4tRb3nP8sZcWd1e

La liste utilise une pagination par curseur avec le tri par défaut. Si vous demandez un sort_by ou un sort_dir personnalisé, elle revient aux numéros de page.

Corriger une facture

PUT /invoices/{id} remplace le document au lieu de le modifier partiellement. customer_name, items, invoice_date et currency sont obligatoires à chaque appel. Renvoyez donc toute la facture avec votre modification, pas uniquement le changement. Les lignes envoyées remplacent entièrement les précédentes : chaque mise à jour remplace les lignes et leurs id. Tous les items[].id changent donc.

Vous pouvez modifier recurring_interval pendant une mise à jour. L'alias recurring_frequency accepté à la création ne l'est pas. Utilisez donc toujours recurring_interval. language reste tel quel tant que vous ne l'envoyez pas, même quand customer_id change. Un PUT envoie un seul invoice.updated, avec les lignes et les totaux enregistrés, et aucun quand il ne change rien. Une facture supprimée ne vous est plus jamais renvoyée, et son numéro de facture reste utilisé.

Enregistrer un paiement encaissé ailleurs

mark-paid sert aux fonds reçus hors de Wajub, en espèces ou par virement bancaire. Il modifie le solde de la facture, mais ne crée aucune transaction et ne règle rien.

Un amount inférieur au total est ajouté à amount_paid et fait passer le statut à partial. Rappelez l'endpoint pour l'échéance suivante. Les montants s'accumulent et la facture passe à paid avec un paid_at dès qu'ils atteignent le total.

curl https://api.wajub.com/invoices/inv_LRQqYvlhrgUOE225KMKU/mark-paid \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 178875, "payment_date": "2026-09-20" }'

La facture doit être ouverte : envoyée, consultée, en retard ou partiellement payée. Un brouillon renvoie 400, puisqu'il n'a été ni envoyé ni numéroté : envoyez-le d'abord. Une facture déjà paid renvoie aussi 400 et garde son paid_at ; de même pour une facture cancelled ou refunded, avec 400 This invoice cannot be marked as paid. Un amount nul ou négatif renvoie 422.

Le PDF

Une fois envoyée, une facture a un PDF que toute personne qui détient son id peut télécharger, sans clé : la copie que votre client archive. Un brouillon renvoie 404, comme sa page.

https://api.wajub.com/i/inv_LRQqYvlhrgUOE225KMKU/pdf

Il est rédigé dans la language de la facture. Ajoutez ?locale=fr ou ?locale=en pour l'obtenir dans l'autre langue. C'est le lien que propose la page de la facture : partagez-le comme vous partagez la page.

Annuler une facture

POST /invoices/{id}/cancel définit le statut sur cancelled, renseigne cancelled_at et ferme la page publique. L'appel accepte un champ reason, mais ne le stocke pas. Une facture déjà paid, cancelled ou refunded renvoie 400 This invoice cannot be cancelled.

Une facture partiellement payée ne peut plus être modifiée ni supprimée. L'annuler la clôt sans rembourser les fonds encaissés. Rembourser en totalité ce qui a été payé en ligne, avec les remboursements sur les paiements sous-jacents, la fait passer à refunded, sauf si une part a été enregistrée avec mark-paid.