Référence HTTP — API de génération

L’API de génération (apps/api) est un service HTTP stateless hébergé sur le même VPS que les autres apps Kortilabs. Elle expose les opérations de génération, validation et parsing de factures électroniques.

Base URL : https://api.facturation.kortilabs.com

---

Authentification

Toutes les routes de génération requièrent un header Authorization: Bearer <PORTAL_HMAC_SECRET>. Les clés API sont gérées depuis le portail OPERAT (/api/portal).

---

POST /api/v1/generate

Génère un fichier Factur-X (PDF/A-3 + XML EN 16931 CII).

Corps de la requête

{
  "invoice": {
    "number": "FACT-2026-0001",
    "typeCode": "380",
    "issueDate": "2026-06-01",
    "currency": "EUR",
    "seller": {
      "name": "ACME SAS",
      "siret": "12345678900012",
      "vatNumber": "FR12345678900",
      "address": { "street": "1 rue de la Paix", "city": "Paris", "postalCode": "75001", "country": "FR" }
    },
    "buyer": {
      "name": "Client SAS",
      "siret": "98765432100019",
      "address": { "street": "5 avenue des Champs", "city": "Lyon", "postalCode": "69001", "country": "FR" }
    },
    "lines": [
      {
        "id": "1",
        "description": "Prestation de conseil",
        "quantity": 2,
        "unitCode": "HUR",
        "unitPrice": 150,
        "vatRate": 20
      }
    ],
    "paymentTerms": "Paiement à 30 jours"
  }
}

Réponse 200

{
  "xml": "<base64>…</base64>",
  "pdf": "<base64>…</base64>",
  "validation": { "valid": true, "errors": [], "warnings": [] }
}

Codes d’erreur

Code	Cause
422	Facture invalide — validation.errors liste les règles BR-* en échec
400	JSON malformé
401	Clé API manquante ou invalide

---

POST /api/v1/validate

Valide une facture contre les règles EN 16931 et les règles françaises BR-FR-* sans générer de fichier.

Corps de la requête

Même structure que /generate, champ invoice uniquement.

Réponse 200

{
  "valid": false,
  "errors": [
    { "rule": "BR-01", "message": "Le numéro de facture est obligatoire", "path": "invoice.number" }
  ],
  "warnings": [
    { "rule": "BR-FR-09", "message": "SIREN vendeur recommandé pour les factures françaises", "path": "invoice.seller.siret" }
  ]
}

---

POST /api/v1/parse

Parse un fichier Factur-X (XML CII ou UBL) et retourne la structure JSON normalisée.

Corps de la requête

{ "xml": "<base64 du fichier XML>" }

Réponse 200

{
  "format": "CII",
  "invoice": { "number": "FACT-2026-0001", "…": "…" },
  "validation": { "valid": true, "errors": [], "warnings": [] }
}

Le champ format vaut "CII" (CrossIndustryInvoice — Factur-X) ou "UBL" (Universal Business Language).

---

POST /check-xml

Valide la conformité syntaxique et structurelle d’un fragment XML sans l’authentification HMAC. Utile pour les tests et l’intégration PrestaShop.

Corps de la requête

{ "xml": "<contenu XML brut>" }

Réponse 200

{
  "valid": true,
  "format": "CII",
  "errors": [],
  "warnings": []
}

---

Webhooks — vérification HMAC

Le SDK expose verifyWebhook pour vérifier la signature des webhooks entrants (LemonSqueezy, PA, etc.).

import { verifyWebhook } from '@facturation/sdk';

// Dans votre handler Next.js / Hono
const isValid = verifyWebhook({
  payload: rawBody,          // Buffer ou string du corps brut
  signature: req.headers['x-signature'],
  secret: process.env.LEMONSQUEEZY_WEBHOOK_SECRET,
});

if (!isValid) return new Response('Unauthorized', { status: 401 });

La vérification utilise crypto.timingSafeEqual pour éviter les attaques par timing.

Événements LemonSqueezy traités

Événement	Action
order_created	Upgrade plan utilisateur (SITE ou MULTI)
subscription_cancelled	Passage plan FREE en fin de période
subscription_expired	Passage plan FREE immédiat

---

Limites et quotas

Limite	Valeur
Taille max corps requête	10 Mo
Rate limiting	100 req/min par IP
Factures en lot (batch)	Non disponible en v1 — 1 facture par appel