Intégration développeur

L’API REST d’Ondes PRO

Chaque espace Ondes PRO expose une API REST versionnée sous /api/v1/ : produits, commandes, stocks, devis, factures, fiches CRM, cartes Kanban, événements d’agenda… Environ 135 ressources, documentées à partir des routes réelles de votre espace, avec des clés API à portées, un schéma OpenAPI 3.1, des webhooks signés et un mode test pour encaisser sans risque.

Mis à jour le
.ondes.pro/mcp/

Tapez le nom de votre espace : les configurations de cette page s’adaptent. Il est retenu dans ce navigateur seulement.

Un premier appel à l’API REST d’Ondes PRO

Créez une clé dans Administration → API & Développeurs → Clés API, puis envoyez-la dans l’en-tête Authorization. Ici, les factures dont l’échéance est dépassée, en ne gardant que trois champs.

bash
curl "https://votre-espace.ondes.pro/api/v1/billing/factures/?statut=en_attente&date_echeance__lt=2026-10-21&fields=numero,date_echeance,etat" \
  -H "Authorization: ApiKey opk_…"

La clé ne s’affiche qu’une fois, à sa création. Rangez-la dans un gestionnaire de secrets.

Comment s’authentifier : clé API, JWT ou session

Une clé API (Authorization: ApiKey opk_…) porte des portées de la forme module:action, par exemple billing:read. Une portée est un plafond : l’accès exige la portée et la permission du module dans le rôle du porteur. Une clé ne peut donc jamais dépasser la personne qui l’a créée, et chaque clé a son propre quota par minute.

Quelques ressources ne s’ouvrent jamais à une clé, parce qu’elles touchent aux droits eux-mêmes (rôles) ou à des contenus chiffrés de bout en bout (messagerie). Elles demandent un jeton JWT ou une session d’administrateur. La fiche de chaque ressource l’indique, et l’API répond par un refus explicite plutôt que par un silence.

Ce que l’API v1 fait pour vous éviter les pièges

  • Idempotence : un en-tête Idempotency-Key rend une création rejouable sans doublon après une coupure réseau.
  • Pagination par page (50 lignes par défaut, 200 au plus) ou par curseur avec ?pagination=curseur, pour parcourir de gros volumes sans décalage.
  • `expand` et `fields` : développez une relation dans la même réponse, ou ne recevez que les colonnes utiles.
  • Erreurs structurées : chaque refus porte un bloc ondes_erreur avec un code stable et un indicateur reessayable.
  • Quotas annoncés : les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset, et Retry-After quand il faut patienter.
  • Multi-sociétés : chaque requête s’exécute dans une société précise, et une filiale ne lit jamais les données d’une sœur.

Recevoir des webhooks signés quand une commande est payée

Plutôt que d’interroger l’API en boucle, abonnez une URL aux événements qui vous intéressent avec la ressource developer/abonnements. Chaque livraison porte un en-tête Ondes-Signature (horodatage et HMAC-SHA256 du corps), sur le modèle que les développeurs connaissent chez Stripe. Le secret de signature n’est montré qu’à la création.

La destination est vérifiée avant d’être enregistrée, et chaque abonnement garde un journal de ses livraisons. Si votre serveur était indisponible, vous voyez ce qui a échoué et vous pouvez rejouer une livraison, au lieu de resynchroniser à la main.

Écrire un connecteur avec la documentation de votre espace

Branché sur le serveur MCP, votre éditeur de code lit la fiche exacte d’une ressource au lieu de deviner. Ici, un développeur d’Atelier Lumen relie son logiciel d’expédition.

Claude Code · Exemple de conversation · données de démonstration (Atelier Lumen)
  1. Vous : Écris une fonction qui enregistre le numéro de suivi d’un colis sur la commande correspondante.
  2. Outil MCP : ondes_chercher Cherche « expédition » : la ressource orders/expeditions et la section du guide sur l’idempotence.
  3. Outil MCP : ondes_ressource Lit la fiche orders/expeditions : champs obligatoires, filtres, portée exigée.
  4. Outil MCP : ondes_appeler POST orders/expeditions avec simuler: true — le corps est valide, rien n’est écrit.
  5. Assistant : La fonction est prête et le corps a été validé contre votre espace. J’ai ajouté une clé d’idempotence calculée depuis le numéro de suivi, pour qu’un renvoi ne crée pas deux expéditions. Il vous faudra une clé portant la portée indiquée sur la fiche.

Où trouver la documentation et le schéma OpenAPI ?

Dans votre administration, API & Développeurs réunit le guide, l’explorateur des routes, le schéma OpenAPI 3.1 à télécharger, vos clés et leur analyse d’usage. Tout est engendré par introspection des routes réelles : une ressource qui n’existe pas dans votre espace n’y figure pas.

Le guide existe aussi sous forme servie à la demande par le serveur MCP : six outils de documentation, dont ondes_impossible, qui liste ce que l’API ne fait volontairement pas. Pour un pas-à-pas complet, suivez le guide construire une intégration.

Pour aller plus loin

Questions fréquentes

L’API REST est-elle incluse dans toutes les offres ?

Oui. L’API v1 et le serveur MCP sont disponibles dans les offres Essentiel, Pro et Entreprise, sans option à activer. Voir les tarifs.

Quelle est l’adresse de base de l’API ?

Celle de votre espace suivie de /api/v1/, par exemple https://votre-espace.ondes.pro/api/v1/. Chaque client a sa propre instance, donc sa propre adresse.

Comment limiter ce qu’une intégration peut faire ?

Créez une clé avec les seules portées nécessaires, par exemple billing:read pour un tableau de bord. Un gestionnaire peut aussi régler le quota par minute d’une clé, la suspendre ou la révoquer, et chaque geste est tracé.

L’API permet-elle d’annuler une facture ?

Non, et c’est volontaire : en France, une facture émise ne s’annule pas. L’API émet un avoir, total ou partiel, avec un motif obligatoire, par l’action avoir/ de billing/factures.

Existe-t-il un schéma OpenAPI ?

Oui, au format OpenAPI 3.1, téléchargeable depuis API & Développeurs. Il est engendré depuis les routes réelles de votre espace, donc toujours à jour.

Faut-il choisir entre l’API et le serveur MCP ?

Non. Le serveur MCP appelle l’API v1 elle-même : mêmes routes, mêmes permissions. L’API convient aux synchronisations automatiques, le MCP aux échanges avec un assistant IA. Voir MCP ou API REST.

Branchez votre IA sur votre entreprise

Le serveur MCP est inclus dans toutes les offres, sans option ni supplément.

Créer mon espaceVoir les tarifs

À lire aussi

Claude, Claude Code et Claude Desktop sont des marques d’Anthropic, PBC ; Cursor est une marque d’Anysphere, Inc. ; Visual Studio Code et Microsoft sont des marques du groupe Microsoft ; GitHub et GitHub Copilot sont des marques de GitHub, Inc. ; ChatGPT et OpenAI sont des marques d’OpenAI ; Windsurf est une marque de Cognition ; Zed est une marque de Zed Industries, Inc. ; JetBrains, Cline, Zapier, Make, n8n, Stripe et Model Context Protocol sont des marques de leurs titulaires respectifs. Ces noms sont cités uniquement pour indiquer une compatibilité ou établir une comparaison. Ondes PRO n’est ni affilié à ces sociétés, ni sponsorisé, ni approuvé par elles.