API pour les développeurs

L’API permet à n’importe quel logiciel de transmettre ses factures à la passerelle. Les modules Dolibarr et WHMCS l’utilisent eux aussi.

• Adresse : https://efacture.odoip.cloud
• Format : JSON en UTF-8, HTTPS obligatoire
• Authentification : en-tête Authorization: Bearer efk_… avec la clé d’accès remise par ODOIP pour votre logiciel
• Limite : 120 requêtes par minute et par clé ; au-delà, réponse 401 « Trop de requêtes : réessayez dans une minute. »

Montants en texte

Tous les montants et quantités sont des chaînes de caractères décimales ("19.00", jamais 19.00). Un montant transmis comme un nombre JSON est refusé.

Déposer une facture

POST /api/v1/invoices

{
  "source": "monlogiciel",
  "source_ref": "3723925",
  "number": "FA-2026-0142",
  "type": "invoice",
  "issue_date": "2026-10-20",
  "due_date": "2026-11-19",
  "currency": "EUR",
  "operation_category": "services",
  "vat_on_debits": false,
  "buyer": {
    "name": "Exemple Conseil SAS",
    "siren": "000000018",
    "vat_id": null,
    "country": "FR",
    "address": { "line1": "10 rue de l’Exemple", "postcode": "75001", "city": "Paris", "country": "FR" },
    "delivery_address": null
  },
  "lines": [
    { "label": "Abonnement Trunk SIP — octobre 2026", "qty": "1", "unit_price_ht": "120.00", "vat_rate": "20.00", "vat_category": "S" }
  ],
  "totals": { "ht": "120.00", "tva": "24.00", "ttc": "144.00" },
  "payment": { "terms": "Paiement à réception" },
  "original_pdf": "<votre PDF encodé en base64, ou null>"
}

Champ	Valeurs
source	Nom court de votre logiciel (20 caractères au plus), le même pour toutes vos factures.
number	Numéro de la facture (64 caractères au plus). Avec source, il identifie la facture de façon unique.
type	invoice (facture) ou credit_note (avoir).
operation_category	goods, services ou mixed.
vat_category	Catégorie de TVA de la ligne : S (taux normal), Z, E (exonéré), AE (autoliquidation), K (intracommunautaire), G (export), O (hors champ).
buyer.siren	Obligatoire pour une entreprise française. Laisser null pour un particulier ou un client étranger.
original_pdf	Facultatif. S’il est lisible (non chiffré), il devient le PDF visible de la facture Factur-X.

Exemple d’appel :

curl -X POST https://efacture.odoip.cloud/api/v1/invoices \
  -H "Authorization: Bearer efk_votrecle" \
  -H "Content-Type: application/json" \
  --data @facture.json

Réponses

Code	Signification	Corps
202	Facture acceptée et mise en file d’envoi.	{ id, numero, statut: "en_file", message, voie, maj }
200	Facture déjà connue pour ce couple source + numéro : son état réel est renvoyé (envoi en double ignoré).	même forme
422	Facture invalide : rien n’est envoyé.	{ id, statut: "invalide", erreurs: [ { champ, message } ] }
400	Corps absent ou JSON mal formé.	{ erreur }
401	Clé absente, inconnue, révoquée, ou limite de requêtes dépassée.	{ erreur }

Une facture invalide ou rejetee peut être renvoyée sous le même numéro après correction : elle remplace la précédente.

Consulter le statut d’une facture

GET /api/v1/invoices/{id} — id est celui renvoyé au dépôt.

{ "id": "01a0f26b-…", "numero": "FA-2026-0142", "statut": "emise", "message": "Facture émise vers le destinataire.", "voie": "B2B", "maj": "2026-10-20T09:31:06+02:00" }

voie vaut B2B (facture électronique), B2C ou B2BInt (e-reporting). Réponse 404 si la facture n’appartient pas à votre espace. Voir les statuts.

Plutôt que d’interroger cette adresse régulièrement, utilisez les notifications de statut.

Vérifier un SIREN avant de facturer

GET /api/v1/directory/siren/{siren}

{ "siren": "000000018", "statut": "inscrit", "message": "Inscrit à l’annuaire national : ce client peut recevoir des factures électroniques." }

statut	Signification
inscrit	Le client peut recevoir des factures électroniques.
absent	Le client n’est pas inscrit : une facture électronique serait refusée.
invalide	Le SIREN est mal formé ou sa clé de contrôle est fausse (l’annuaire n’est pas interrogé).

Réponse 503 avec statut: "indisponible" si l’annuaire est momentanément injoignable : réessayez plus tard.