Étape 1 — la clé API, sans inscription développeur
Il n’y a ni console développeur ni validation manuelle. Le commerçant ouvre sa conversation WhatsApp Fatora-Bot et écrit « api » : le bot répond avec sa clé personnelle, au format fk_ suivi de 40 caractères. C’est cette clé que votre application stocke et passe dans l’en-tête Authorization: Bearer.
La clé est propre à chaque commerçant : elle émet dans SA numérotation et ne voit que SES documents. « api reset » la régénère à tout moment — l’ancienne est immédiatement révoquée. Un GET /v1/account est le moyen le plus simple de vérifier qu’une clé collée par l’utilisateur est valide : il renvoie le profil société, le plan et le quota restant.
Étape 2 — émettre le document
Un seul appel : POST /v1/documents, avec le nom du client (et son ICE en B2B), puis les lignes — description, quantité, prix unitaire. L’API calcule la TVA ligne par ligne, applique le régime fiscal du commerçant, génère le PDF avec logo et cachet, et répond en 201 avec le numéro attribué, les totaux HT/TVA/TTC, le lien du PDF et l’URL d’un QR code.
Deux options changent tout au quotidien. « type »: « quote » émet un devis (numéroté DEV-, valable 30 jours, hors quota) au lieu d’une facture. « priceIsTtc »: true indique que vos montants sont TTC : l’API reconstitue la base hors taxe elle-même — indispensable quand vos prix de vente sont affichés TTC.
Pour corriger un document déjà émis, pas de schéma de mise à jour à apprendre : l’endpoint de modification accepte une instruction en texte libre (« remplace la formation par 3 jours à 1200 dh le jour ») et l’applique sur le même numéro, PDF régénéré, totaux recalculés.
La numérotation reste continue : modifier ne crée jamais de trou dans la séquence, et annuler passe par un avoir — comme l’exige la réglementation marocaine.
Étape 3 — remettre la facture au client
Générer le PDF ne sert à rien si le client ne le reçoit pas. Trois canaux sont disponibles, à la création (champs « sendToPhone » et « sendToEmail ») ou après coup via l’endpoint d’envoi :
- WhatsApp : le PDF part dans la conversation du client, au nom du commerçant.
- Email : message soigné avec la facture en pièce jointe.
- QR code : chaque document expose une image PNG publique — affichez-la en caisse, imprimez-la sur le ticket, le client scanne et télécharge sa facture.
Les erreurs à gérer dans votre code
L’API renvoie toujours un JSON à deux champs : « error » (code machine stable) et « message » (explication affichable telle quelle). Quatre cas méritent un traitement spécifique dans votre interface : le 402 quota atteint (la réponse contient used et limit — affichez-les, le commerçant change de plan en deux messages WhatsApp), le 401 clé invalide (souvent une clé régénérée par « api reset » — redemandez-la), le 422 instruction incomprise (proposez de reformuler, rien n’a été modifié), et le 429 au-delà de 60 requêtes par minute (mettez en file et réessayez).
La liste complète des codes, avec un exemple de réponse pour chacun, figure sur la page API du site — chaque exemple y a été rejoué contre l’API de production.
Questions fréquentes
Faut-il un compte développeur ou une validation pour utiliser l’API ?
Non. La clé s’obtient en écrivant « api » au bot WhatsApp du compte Fatora concerné, en quelques secondes. Il n’y a ni console, ni contrat, ni frais : l’API est incluse dans tous les plans, essai gratuit compris.
Le PDF généré est-il vraiment conforme pour un contrôle fiscal ?
Le PDF porte les mentions de l’article 145 CGI : ICE, identifiant fiscal, taxe professionnelle, TVA ventilée, montant en toutes lettres, numérotation continue, et les mentions de régime (auto-entrepreneur, exonéré) quand elles s’appliquent. Le cachet et le logo du commerçant sont apposés automatiquement.
Puis-je générer des devis et les transformer en factures ?
Oui. « type »: « quote » émet un devis numéroté DEV- valable 30 jours, gratuit et hors quota. La conversion en facture se fait ensuite par l’instruction libre (« transforme le devis DEV-2026-0012 en facture ») — la facture prend un numéro FAT- normal.
Comment tester sans polluer la numérotation du commerçant ?
Émettez des devis pendant vos tests : ils sont gratuits, illimités et n’entament pas la séquence des factures. Gardez l’émission de vraies factures pour la mise en production — chaque facture émise entre dans la numérotation légale et s’annule par avoir, pas par suppression.
Ce guide présente le cadre général applicable au Maroc. Il ne remplace pas l’avis de votre expert-comptable ni les textes publiés par la Direction Générale des Impôts, dont les valeurs chiffrées évoluent avec les lois de finances.