Guide développeur

Construire une intégration back-office avec l’API d’Ondes PRO

Synchroniser un ERP, alimenter un entrepôt, pousser les clients d’une application métier : ce guide déroule une intégration serveur à serveur complète avec l’API REST v1 d’Ondes PRO. Clé à portées minimales, lecture paginée, écritures idempotentes, webhooks signés pour réagir sans interroger en boucle, et le serveur MCP comme compagnon pendant le développement.

L’équipe Ondes PROMis à 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.

Comment s’authentifier sur l’API REST d’Ondes PRO ?

Un service qui tourne sans humain devant l’écran utilise une clé API, transmise dans l’en-tête Authorization: ApiKey opk_…. Chaque clé porte des portées au format module:action — billing:read, shop:write, inventory:read — et ces portées sont un plafond : la clé n’atteint jamais plus que les droits de la personne qui l’a créée. Si celle-ci perd l’accès à la facturation, la clé le perd aussi.

Donnez à chaque intégration sa propre clé, avec le strict nécessaire. Le jour où un serveur est compromis, vous révoquez une clé sans couper les autres, et le journal d’appels de l’onglet Analyse montre ce qu’elle a fait. Chaque clé a aussi un quota par minute, choisi à la création ; les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset disent où vous en êtes.

Mettre en place une intégration fiable, de la clé au webhook

Le scénario : le back-office logistique d’Atelier Lumen doit récupérer chaque nouvelle facture et créer dans Ondes PRO les clients saisis par son équipe commerciale.

  1. Créez une clé dédiée

    Dans API & Développeurs → Clés API, créez une clé nommée « Back-office logistique » avec billing:read et billing:write, et un quota adapté à votre volume. La valeur ne s’affiche qu’une fois : rangez-la dans le gestionnaire de secrets de votre serveur.

  2. Lisez en demandant seulement ce qui sert

    ?fields= réduit chaque ligne aux champs utiles, ?expand= développe une relation dans la même réponse au lieu de multiplier les appels. La pagination par défaut renvoie 50 lignes, jusqu’à 200 avec page_size.

    bash
    curl "https://votre-espace.ondes.pro/api/v1/billing/factures/?fields=id,numero,statut,date_echeance&page_size=100" \
  -H "Authorization: ApiKey opk_…"

  3. Parcourez une collection entière par curseur

    Pour une synchronisation complète, ajoutez pagination=curseur et suivez le lien next jusqu’au bout. Contrairement à la pagination par numéro, le curseur ne saute ni ne double aucune ligne quand des factures sont créées pendant le parcours.

  4. Écrivez avec une clé d’idempotence

    Chaque POST, PUT ou PATCH peut porter Idempotency-Key. Même clé et même corps : la réponse mémorisée revient, sans rien refaire. Même clé et corps différent : 409, car c’est le signe d’un bug côté client. Dérivez la clé de l’identifiant de votre propre système, pas d’un nombre aléatoire tiré à chaque essai.

    bash
    curl -X POST https://votre-espace.ondes.pro/api/v1/billing/clients/ \
  -H "Authorization: ApiKey opk_…" \
  -H "Idempotency-Key: crm-client-4812" \
  -H "Content-Type: application/json" \
  -d '{"nom": "Le Comptoir des Marées", "email": "achats@comptoir-marees.fr", "ville": "Saint-Malo"}'

  5. Abonnez-vous aux événements

    POST /api/v1/developer/abonnements/creer/ enregistre l’adresse de votre serveur et la liste des événements suivis, nommés <ressource>.<cree|modifie|supprime> — par exemple billing.factures.cree. Le secret de signature n’est renvoyé qu’à cette création. L’adresse doit appartenir à une origine déclarée, et les adresses de réseau interne sont refusées.

    json
    {
  "nom": "Back-office logistique",
  "url": "https://logistique.atelier-lumen.fr/hooks/ondes",
  "evenements": ["billing.factures.cree", "billing.factures.modifie"]
}

  6. Vérifiez chaque livraison, puis relisez l’objet

    L’en-tête Ondes-Signature vaut t=<horodatage>,v1=<hmac> ; recalculez le HMAC-SHA256 de <t>.<corps> avec votre secret et refusez un horodatage de plus de cinq minutes. La charge utile ne transporte que l’identité de l’objet (ressource, id, société) : relisez-le par l’API pour obtenir son état actuel.

  7. Testez, puis rattrapez ce qui a été manqué

    POST …/abonnements/<id>/tester/ envoie un événement ondes.test signé. GET …/<id>/livraisons/ liste ce qui est parti et avec quel code ; POST …/<id>/rejouer/ renvoie une livraison après une panne de votre côté.

Vérifier la signature d’un webhook en Python

python
import hashlib, hmac, time

def signature_valide(corps: bytes, entete: str, secret: str, tolerance: int = 300) -> bool:
    morceaux = dict(p.split("=", 1) for p in entete.split(",") if "=" in p)
    horodatage = int(morceaux.get("t", "0"))
    if abs(time.time() - horodatage) > tolerance:
        return False
    attendu = hmac.new(
        secret.encode(), f"{horodatage}.".encode() + corps, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(attendu, morceaux.get("v1", ""))

Calculez la signature sur le corps BRUT reçu, avant tout décodage JSON.

Quelles erreurs gérer, et comment réagir ?

Toute erreur de l’API v1 suit le même format JSON, un objet ondes_erreur avec un code stable, un message lisible et, pour une validation, les champs fautifs.

RéponseSignificationRéaction conseillée
400Corps ou paramètre invalideLire ondes_erreur.champs, corriger, ne pas réessayer tel quel
403Portée ou droit manquantAjouter la portée à la clé, ou demander le module à l’administrateur
409Même Idempotency-Key, corps différentCorriger la génération de clés côté client
429Quota par minute atteintAttendre la durée de Retry-After, puis reprendre
503 instance_occupeeEspace momentanément occupéRéessayer après Retry-After, avec la même clé d’idempotence

Écrire en masse sans laisser un import à moitié fait

Sur toute ressource qui accepte l’écriture, POST /api/v1/<ressource>/lot/ regroupe jusqu’à 100 opérations dans une seule transaction. Le corps porte une liste operations, chacune avec sa methode (POST, PATCH, PUT, DELETE), son id quand il s’agit d’un objet existant et ses donnees.

Le lot est tout ou rien : une seule opération refusée annule l’ensemble, et la réponse dit laquelle et pourquoi. Chaque opération repasse par les mêmes contrôles qu’un appel unitaire — droits, société, mode test — donc le lot ne crée aucun droit nouveau, il évite seulement cent allers-retours.

Le mode test : développer contre de vraies routes sans conséquences

Certaines ressources ont un jumeau sous /api/v1/test/ : les commandes de la boutique, les réunions visio, les envois d’e-mails et les invitations. Le mode vient de l’URL et de rien d’autre — ni en-tête, ni paramètre — si bien qu’on ne peut pas écrire en réel par étourderie. Les objets de test sont invisibles des chiffres d’affaires, des exports et des tableaux de bord.

Pointez votre environnement de recette sur les URLs /test/, et votre production sur les URLs sans préfixe : la bascule devient une variable de configuration, pas une modification de code.

Le serveur MCP comme compagnon de développement

Connecté à votre espace, votre assistant de code lit la fiche de chaque ressource et les recettes vérifiées au lieu de supposer.

Claude Code · Exemple de conversation · données de démonstration (Atelier Lumen)
  1. Vous : Écris le gestionnaire de webhook de notre back-office : à chaque nouvelle facture, enregistre son numéro et son échéance dans notre table factures_ondes.
  2. Outil MCP : ondes_exemple Recette « s’abonner aux événements » : création de l’abonnement, vérification de Ondes-Signature, relecture de l’objet.
  3. Outil MCP : ondes_impossible Confirme qu’une livraison ne contient jamais le contenu de l’objet, seulement son identité.
  4. Assistant : Le webhook ne transporte que la ressource et l’id : j’ajoute donc une relecture GET billing/factures/<id>/?fields=numero,date_echeance,statut après la vérification de signature. L’écriture dans factures_ondes est un upsert sur l’id, pour qu’un rejeu depuis rejouer/ ne crée pas de doublon.

Pour aller plus loin

Questions fréquentes

Quelle authentification utiliser pour une intégration serveur ?

Une clé API, dans l’en-tête Authorization: ApiKey opk_…, créée dans API & Développeurs → Clés API avec les seules portées nécessaires. Les portées sont un plafond : la clé ne dépasse jamais les droits de son créateur.

Comment éviter les doublons quand une requête échoue en cours de route ?

Envoyez un en-tête Idempotency-Key sur chaque écriture. Rejouée avec le même corps, la requête renvoie la réponse mémorisée sans rien refaire ; avec un corps différent, elle répond 409.

Comment être prévenu d’un changement sans interroger l’API en boucle ?

Créez un abonnement avec developer/abonnements : Ondes PRO envoie à votre serveur des événements comme billing.factures.cree, signés par l’en-tête Ondes-Signature. Le journal des livraisons et l’action rejouer/ rattrapent une indisponibilité.

Pourquoi le webhook ne contient-il pas toutes les données de l’objet ?

Par choix : la charge utile ne porte que l’identité de l’objet. Vous le relisez par l’API avec votre clé, ce qui garantit d’obtenir son état actuel et applique vos droits du moment.

Existe-t-il un schéma OpenAPI ?

Oui, un schéma OpenAPI 3.1 engendré à partir des routes réelles de votre espace, téléchargeable depuis API & Développeurs une fois connecté. Il est personnalisé : il ne décrit que les modules de l’espace.

Que se passe-t-il quand mon quota est atteint ?

L’API répond 429 avec un en-tête Retry-After. Les en-têtes X-RateLimit-* présents sur chaque réponse permettent d’anticiper, et un gestionnaire de l’espace peut relever le quota par minute de la clé.

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