API REST - Vue d'ensemble

Base URL

Versioning

L'API est versionnée via le préfixe d'URL. La version courante est v1 .

/v1/invoices

Authentification

Toutes les requêtes doivent inclure la clé API secrète dans le header Authorization :

Authorization: Bearer efact_sk_xxx

La clé identifie votre organisation côté serveur : aucun identifiant d'organisation ne transite dans vos requêtes. Voir Authentification pour le détail complet.

Format des requêtes

Format des réponses

Chaque réponse, succès ou erreur, utilise la même enveloppe { code, message, data, errors }. Les SDK officiels déballent data automatiquement et lèvent une erreur typée sinon.

Succès

{
  "code": "OK",
  "message": "Invoice created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "invoiceNumber": "INV-2026-042",
    "status": "SIGNED",
    "currency": "MAD",
    "amountHt": 12000.00,
    "amountVat": 2400.00,
    "amountTtc": 14400.00,
    "createdAt": "2026-04-07T10:00:00Z"
  },
  "errors": null
}

Erreur

{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "data": null,
  "errors": [
    {
      "field": "buyerIce",
      "message": "buyerIce must be exactly 15 digits"
    }
  ]
}

Codes de statut HTTP

Codes d'erreur métier

Le champ codede l'enveloppe porte un code stable, exploitable par programme. Les principaux :

Idempotence

L'idempotence de la création repose sur le invoiceNumber, unique par organisation :

// invoiceNumber est unique par organisation : rejouer la même
// création retourne 409 INVOICE_NUMBER_EXISTS au lieu de créer un doublon.
POST /v1/invoices
{ "invoiceNumber": "INV-2026-042", ... }

En cas de doute après un timeout réseau, rejouez la création : soit elle réussit, soit vous recevez 409 INVOICE_NUMBER_EXISTS - la facture existe déjà et peut être retrouvée via la liste. Les SDK ne rejouent jamais un POST automatiquement.

Rate limiting

Au-delà, l'API retourne 429 avec un header Retry-After (en secondes). Les SDK officiels le respectent automatiquement avec un back-off exponentiel.

Pagination

Les endpoints de liste utilisent une pagination par page :

GET /v1/invoices?status=ACCEPTED&page=0&size=20&sort=createdAt,desc

Paramètres

Réponse

{
  "code": "OK",
  "message": "Invoices retrieved",
  "data": {
    "content": [ ... ],
    "page": 0,
    "size": 20,
    "totalElements": 42,
    "totalPages": 3,
    "first": true,
    "last": false
  },
  "errors": null
}

Endpoints disponibles

Questions fréquentes