Pour développeurs et équipes d’intégration

Gardez votre logiciel de facturation. Reliez ses factures à Peppol.

Créez des factures à partir de données structurées, envoyez vos factures et notes de crédit via Peppol, puis récupérez les statuts et documents reçus. Chaque clé de l’API REST publique agit pour une seule entreprise OrdoGrid. Votre équipe développe et exploite la connexion ; la référence décrit les requêtes et réponses disponibles.

Explorer la référence API Comparer les offres

Une intégration adaptée à vos flux réels

Un ERP ou votre propre application de facturation

Créez clients, factures et notes de crédit à partir de champs mappés. Conservez l’identifiant source pour retrouver le même document lors d’une reprise, sans émettre une seconde facture.

Un système qui produit déjà ses PDF

Fournissez les champs structurés et, si vous le souhaitez, votre rendu PDF. OrdoGrid construit l’UBL à partir de ces champs ; cette API n’extrait pas les données d’une facture PDF.

Un flux de réception ou de rapprochement

Lisez l’Inbox Peppol, récupérez les fichiers XML et PDF échangés et rapprochez-les de votre système. L’entreprise doit recevoir via OrdoGrid pour alimenter cette Inbox.

De votre enregistrement source à un résultat vérifiable

Créer une clé limitée à l’entreprise
Un propriétaire ou administrateur crée la clé dans Entreprise → Clés API. Choisissez un identifiant d’intégration stable et uniquement les permissions nécessaires. Commencez par GET /api/v1/me pour vérifier l’entreprise, l’espace de noms et les droits effectifs.
Créer et vérifier la facture
POST /api/v1/invoices accepte un client_id existant ou un client intégré au contenu, avec des lignes structurées. Conservez l’id et le numéro renvoyés. Omettez number pour utiliser la série de l’entreprise ; vérifiez montants, client et régime TVA avant l’envoi.
Vérifier le destinataire, puis envoyer
Vérifiez GET /api/v1/peppol/participants/{vat_number}, puis appelez POST /api/v1/peppol/invoices/{id}/send. La création exige invoices:write ; l’envoi exige peppol:send. Les notes de crédit ont leur propre route credit-notes.
Lire la livraison et conserver les fichiers échangés
Appelez GET /api/v1/peppol/invoices/{id}/status avec peppol:read. Conservez document_id et peppol_document_id ; ce dernier sert à télécharger l’XML échangé. Remise au point d’accès, livraison réseau, réponse du client et paiement sont des résultats distincts.

Trois requêtes distinctes, une seule facture

Exemples de requêtes HTTP, sans console interactive. Remplacez chaque valeur symbolique par votre clé d’entreprise, l’identifiant d’un client existant et des clés d’opération stables. Utilisez l’id renvoyé pour l’envoi et le statut. L’exemple compte deux unités à 150 € HTVA et 21 % de TVA ; choisissez le régime adapté à votre opération réelle.

Les requêtes agissent sur les données réelles de l’entreprise. Créer une facture enregistre un vrai document et son numéro. Il n’y a pas de sandbox : n’envoyez que de vraies factures à un destinataire convenu. Cette page n’exécute aucune requête.

1. Créer la facture

POST /api/v1/invoices
Authorization: Bearer <company-api-key>
Idempotency-Key: <stable-create-operation-key>
Content-Type: application/json

{
  "external_id": "your-source-order-id",
  "client_id": "<existing-client-id>",
  "currency": "EUR",
  "items": [
    {
      "description": "Prestation de conseil",
      "quantity": "2",
      "unit_price": "150.00",
      "vat_rate": 21
    }
  ]
}

2. Envoyer la facture vérifiée

POST /api/v1/peppol/invoices/<invoice-id>/send
Authorization: Bearer <company-api-key>
Idempotency-Key: <stable-send-operation-key>
Content-Type: application/json

{ "include_pdf": true }

3. Lire son statut Peppol

GET /api/v1/peppol/invoices/<invoice-id>/status
Authorization: Bearer <company-api-key>

La création renvoie id et number. L’envoi et le statut utilisent document_id pour la facture et peppol_document_id pour son document Peppol, avec status, lifecycle et transmission_state normalisés. Une réponse d’envoi réussie ne prouve ni l’acceptation du client ni le paiement.

Explorer la référence API

Maîtriser l’entreprise et les permissions

La clé identifie une seule entreprise ; aucun en-tête ne permet d’en sélectionner une autre. Les cookies de session de l’application n’authentifient pas les opérations de l’API publique.
Cet exemple nécessite invoices:write, peppol:send et peppol:read. Un droit write inclut read sur la même ressource ; peppol:send n’inclut pas peppol:read.
Copiez le secret une seule fois dans votre coffre côté serveur. Gardez-le hors du code navigateur, des URL, des outils d’analyse et des journaux. Faites-le tourner ou révoquez-le depuis l’application.
Conservez le même identifiant d’intégration lors d’un changement de clé. La rotation le préserve ; une nouvelle clé créée séparément exige de ressaisir le même espace de noms.

Prévoir la reprise dans votre connexion

Deux identités pour les reprises

Sur les routes POST compatibles, Idempotency-Key restitue la réponse réussie pendant 24 heures pour la même clé API. Un external_id stable protège la création par entreprise, identifiant d’intégration et type de document au-delà de ce délai. Conservez le contenu d’origine sans modification.

Rapprocher d’abord un résultat inconnu

Après un délai dépassé, recherchez la facture par external_id et lisez son statut de transmission. Un envoi incertain peut déjà être sur le réseau : suspendez-le et rapprochez la transmission archivée avant de renvoyer. Ne créez pas une nouvelle facture pour contourner l’erreur.

Respecter les limites et codes d’erreur

Lisez les en-têtes de limite par clé et attendez Retry-After sur HTTP 429. Branchez votre logique sur le code d’erreur, pas sur le message. Parcourez les listes avec limit et offset pour récupérer tous les enregistrements.

Récupérer et rapprocher les statuts

Votre intégration lit les routes publiques de statut et de documents et assure leur suivi. Conservez l’XML échangé et rapprochez séparément les totaux source, la livraison et le règlement. Les guides détaillent les reprises et les contrôles de recette.

Vérifier ces limites avant de choisir l’API

Les champs structurés sont indispensables. Cette API publique ne propose ni extraction à partir d’un PDF seul ni envoi d’un fichier UBL brut téléversé. Le PDF facultatif est le rendu, pas la source de génération de l’UBL.
L’envoi Peppol concerne les factures et notes de crédit, pas les devis ni reçus. L’autorisation de l’entreprise et le quota mensuel applicable sont vérifiés avant l’envoi.
POST /api/v1/peppol/send crée une vraie facture, même avec send: false. Cette option n’est pas une sandbox et contrôle toujours l’autorisation Peppol et le quota.
L’API publique n’a pas d’opération d’envoi de documents par e-mail. Enregistrez uniquement des paiements déjà réalisés par votre canal habituel ; payments:write ne débite pas une carte et ne transfère pas d’argent.
La connexion exige un mapping, du développement et une exploitation. Ce n’est pas un connecteur prêt à l’emploi pour chaque ERP ou comptable. L’historique et les exports nécessitent un plan de migration distinct.

Questions sur la facturation par API

Puis-je lire la documentation sans compte ?: Oui. La référence et GET /api/v1/openapi.json sont publics. Les opérations métier exigent votre propre clé d’entreprise et les permissions indiquées pour chaque opération.
Puis-je garder les PDF produits par mon logiciel ?: Oui. Fournissez votre PDF avec les données structurées correspondantes, ou téléversez son rendu sur la facture existante. La référence décrit les formats acceptés. Vérifiez l’accord entre le rendu et les montants structurés avant l’envoi.
Faut-il l’API pour quelques factures par mois ?: L’application suffit généralement. L’offre gratuite à vie comprend la réception Peppol illimitée et une facture envoyée par mois ; Starter ajoute les envois illimités. Choisissez Business si vous avez besoin de cette API ou de ses autres parcours inclus.
Puis-je lire les statuts avec seulement peppol:send ?: Non. Ajoutez peppol:read pour vérifier les destinataires, les statuts, l’Inbox et les documents échangés. Limitez la clé aux permissions nécessaires à votre intégration.