Documentation

L'API expose un pipeline configurable et des endpoints atomiques. Les deux existent dès la première version : le pipeline pour l'ergonomie, les endpoints pour que le comportement reste débogable et facturable étape par étape.

La référence interactive n'est pas encore publiée. Elle sera générée depuis la spécification OpenAPI et rendue avec Scalar, quand la première version de l'API sera en ligne. Cette page décrit le contrat déjà arrêté.

Un appel

POST /v1/process HTTP/1.1
Host: api.factlint.com
Authorization: Bearer <clé>
Idempotency-Key: 5f2c-…
Content-Type: application/json

{
  "document": {
    "content": "<base64>",
    "filename": "facture.pdf",
    "already_issued": false
  },
  "pipeline": {
    "validate": { "ruleset": "fr-2026-08", "include_passes": true },
    "autofix":  { "enabled": true, "max_changes": 50 }
  },
  "delivery": { "mode": "sync" }
}

Une réponse

Le verdict du document n'est pas un code HTTP. Une facture non conforme renvoie200 avec un statut métier ; les codes 4xx ne concernent que la requête.

{
  "status": "blocked",
  "report": {
    "validate": {
      "ruleset": {
        "id": "fr-2026-08",
        "sha256": "…",
        "effective_from": "2026-08-01",
        "retained_until": "2036-08-01"
      },
      "passes": 412,
      "errors": [
        {
          "code": "BR-CO-15",
          "bt": "BT-112",
          "severity": "fatal",
          "current_value": "1195.00",
          "suggested_value": "1200.00",
          "resolution": "blocked",
          "blocked_reason": "financial_field_policy",
          "docs_url": "https://factlint.com/errors/br-co-15"
        }
      ]
    }
  }
}

Statuts

Statut	Sens
`passed`	Conforme tel quel.
`fixed`	Conforme après corrections structurelles, chacune rendue avec son diff.
`needs_input`	Donnée métier manquante, ou valeur dérivée proposée sans écriture.
`blocked`	Non conforme sur un champ hors périmètre par politique — un champ financier.
`rejected`	Document irrecevable : illisible, chiffré, format inconnu.
`not_evaluated`	Contrôle impossible. Jamais décompté — c'est notre problème, pas le vôtre.

Endpoints

Endpoint	Rôle	Note
`POST /v1/validate`	Validation seule	Gratuit et sans limite de volume
`POST /v1/fix`	Correction structurelle seule
`POST /v1/convert`	Conversion UBL ↔ CII ↔ Factur-X
`POST /v1/enrich`	Complétion tracée des tiers
`POST /v1/process`	Pipeline complet en un appel
`GET /v1/rulesets`	Catalogue des jeux de règles	Versions, dates d'effet, empreintes
`GET /v1/evidence/{id}`	Pack de preuve horodaté

Facturation

L'unité facturée est le document distinct, identifié par son empreinte SHA-256 — pas l'appel HTTP, pas l'étape de pipeline. L'usage normal d'une API de conformité est le re-test itératif : facturer à l'appel reviendrait à pénaliser exactement le comportement qu'on cherche à encourager. Les re-soumissions du même document sont gratuites pendant sept jours, et les erreurs serveur ne sont jamais décomptées.