API publique

POST /api/public/v1/valider-facture : corps binaire, 15 Mo au plus. Avec votre clé : 100 validations par jour, et les en-têtes x-quota-limit et x-quota-remaining pour savoir où vous en êtes. Sans clé, les quotas anonymes du site s’appliquent.

Node.js, en une ligne

MAFACTUREOK_CLE=mfok_live_votre_cle npx @mafactureok/sdk valider facture.pdf

TypeScript

import { MaFactureOK } from "@mafactureok/sdk";
import { readFile } from "node:fs/promises";

const client = new MaFactureOK({ cle: process.env.MAFACTUREOK_CLE });
const rapport = await client.valider(await readFile("facture.pdf"));
console.log(rapport.verdict, rapport.anomalies);

Le SDK @mafactureok/sdk est open source (licence MIT), sans dépendance, avec les types du contrat : github.com/mafactureok/mafactureok-node. Le dépôt contient aussi des factures d’exemple et leurs rapports attendus.

Python

import os, requests

with open("facture.pdf", "rb") as f:
    reponse = requests.post(
        "https://mafactureok.com/api/public/v1/valider-facture",
        headers={
            "Authorization": f"Bearer {os.environ['MAFACTUREOK_CLE']}",
            "Content-Type": "application/octet-stream",
        },
        data=f.read(),
        timeout=60,
    )
rapport = reponse.json()
print(rapport["verdict"], [a["titre"] for a in rapport["anomalies"]])

curl

curl -X POST https://mafactureok.com/api/public/v1/valider-facture \
  -H "Authorization: Bearer mfok_live_votre_cle" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @facture.pdf

Réponse

{
  "version": "1.0",
  "verifie_le": "2026-10-08T10:00:00Z",
  "verdict": "invalide",
  "titre": "Facture non conforme",
  "format": "UBL 2.1", "profil": "EN16931",
  "referentiels": [{ "nom": "FNFE France RFE", "version": "1.4.0.03" }],
  "points": [{ "ton": "error", "titre": "1 anomalie bloquante", "details": [] }],
  "anomalies": [
    { "gravite": "bloquante", "titre": "Montant à payer incohérent",
      "sens": "Le total à payer ne correspond pas au total TTC moins le montant déjà réglé.",
      "correction": "Recalculez BT-115 à partir de BT-112 et BT-113.",
      "valeur_proposee": "1200.00", "ou": "BT-115", "regles": ["BR-CO-16"] }
  ],
  "entreprises": [{ "role": "Vendeur", "etat": "ok", "signaux": [], "tva": "valide" }],
  "duree_ms": 412
}

Verdicts

valide, a_verifier (avertissements ou entreprise à contrôler), invalide (au moins une anomalie bloquante), non_analyse (fichier non pris en charge, motif fourni).

Codes

• 200
• 400 (fichier vide)
• 401 (clé envoyée mais invalide : sans en-tête, l’appel reste anonyme)
• 413 (plus de 15 Mo)
• 429 avec Retry-After (quota atteint)
• 502 (moteur indisponible : la réponse contient tout de même un rapport non_analyse)

Contrat

OpenAPI 3.1 : /api/public/v1/openapi.json. GET /api/public/v1/moi renvoie votre plan, vos quotas et votre usage, hors quota.