API pour développeurs

L'API REST publique d'EUFactura (offre Scale) permet à vos propres outils — un CRM, une boutique e-commerce, un script personnalisé — de créer des clients, de rédiger et d'émettre des factures et devis, d'enregistrer des paiements, et d'être notifiés des événements clés via des webhooks. Chaque endpoint utilise exactement la même logique que l'application EUFactura elle-même, si bien que rien ne se comporte différemment via l'API que dans l'interface.

Référence complète

L'API complète est décrite sous forme de spécification OpenAPI 3.1 — importez-la directement dans Postman, Insomnia ou tout outil compatible OpenAPI.

Authentification

Créez une clé depuis la page Paramètres → Développeurs de votre organisation (propriétaire/administrateur uniquement). Chaque clé est limitée à une organisation et porte un rôle — member (lecture + écriture) ou accountant (lecture seule). Le secret complet n'est affiché qu'une seule fois, lors de la création ; conservez-le en lieu sûr.

curl https://app.eufactura.eu/api/v1/customers?companyId=<company-id> \
  -H "Authorization: Bearer eufk_..."

Créer un client et émettre une facture

curl -X POST https://app.eufactura.eu/api/v1/customers \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "<company-id>",
    "type": "business",
    "legalName": "Acme GmbH",
    "countryCode": "DE"
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices \
  -H "Authorization: Bearer eufk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a UUID you generate>" \
  -d '{
    "companyId": "<company-id>",
    "customerId": "<customer-id>",
    "currency": "EUR",
    "issueDate": "2026-01-01",
    "lines": [{ "description": "Consulting", "quantity": "1", "unitPriceNet": "500" }]
  }'

curl -X POST https://app.eufactura.eu/api/v1/invoices/<invoice-id>/issue \
  -H "Authorization: Bearer eufk_..."

Les factures sont toujours créées comme brouillons puis émises lors d'une étape distincte et explicite — l'émission attribue le numéro de facture légal et rend la facture immuable, conformément au fonctionnement de l'application elle-même.

Idempotence

Envoyez un en-tête Idempotency-Key (une chaîne de votre choix, généralement un UUID) sur une requête modifiant des données. Renvoyer la même requête avec la même clé renvoie la réponse d'origine au lieu d'effectuer l'action une seconde fois — sûr face aux nouvelles tentatives réseau et aux doubles clics.

Limites de débit

Les requêtes sont limitées par clé d'API. Une réponse dépassant la limite renvoie 429 avec un champ Retry-After équivalent, retryAfter, dans le corps de l'erreur.

Erreurs

Chaque erreur est renvoyée sous la forme {"error": {"code": "...", "message": "..."}}. L'identifiant d'une ressource appartenant à une autre organisation renvoie toujours 404, jamais 403 — EUFactura ne confirme jamais qu'une ressource existe avant de confirmer que vous pouvez y accéder.

Webhooks

Enregistrez une URL de point de terminaison et choisissez les événements à recevoir depuis Paramètres → Développeurs : invoice.issued, invoice.payment_recorded, quote.converted et credit_note.issued. Chaque envoi est un POST HTTPS signé :

POST <your endpoint>
Content-Type: application/json
X-EUFactura-Signature: t=1700000000,v1=<hex-encoded HMAC-SHA256>

{"id": "...", "type": "invoice.issued", "data": { ... }}

Vérifiez-le en calculant un HMAC-SHA256 de l'horodatage, d'un point littéral et du corps brut de la requête à l'aide du secret de votre point de terminaison, puis en comparant le résultat à la valeur v1 — le même format t=...,v1=... qu'utilise Stripe pour ses webhooks, donc tout code de vérification de webhooks Stripe que vous possédez déjà constitue un bon point de départ. Les envois sont relancés avec un backoff en cas d'échec (jusqu'à cinq tentatives sur environ 12 heures) ; votre point de terminaison doit être idempotent sur l<id>id</id> de la charge utile.

Questions

Contactez-nous à hello@eufactura.eu.