# L’API REST d’Ondes PRO

> API REST v1 d’Ondes PRO : ~135 ressources, clés API à portées, schéma OpenAPI 3.1, idempotence, pagination par curseur, webhooks signés et mode test.

Mis à jour le 2026-10-21 · L’équipe Ondes PRO · https://ondes.pro/fr/integrations/api-rest

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.

## 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.

> **Un mode test choisi par l’URL** — Les ressources qui encaissent ou qui envoient ont un jumeau sous `/api/v1/test/` : une commande y crée un paiement simulé, avec une page de paiement factice, sans Stripe et sans effet sur votre chiffre d’affaires. Le mode vient de l’adresse appelée, jamais d’un paramètre : on ne passe pas en réel par étourderie.

## Écrire un connecteur avec la documentation de votre espace

_Exemple de conversation · données de démonstration (Atelier Lumen)_

> **Vous** : Écris une fonction qui enregistre le numéro de suivi d’un colis sur la commande correspondante.
>
> 🔧 `ondes_chercher` Cherche « expédition » : la ressource `orders/expeditions` et la section du guide sur l’idempotence.
>
> 🔧 `ondes_ressource` Lit la fiche `orders/expeditions` : champs obligatoires, filtres, portée exigée.
>
> 🔧 `ondes_appeler` `POST orders/expeditions` avec `simuler: true` — le corps est valide, rien n’est écrit.
>
> **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](https://ondes.pro/fr/integrations/mcp/guides/construire-une-integration).

## Pour aller plus loin

- [MCP ou API REST](https://ondes.pro/fr/integrations/mcp/mcp-ou-api-rest) — Ce qui les distingue vraiment, quand choisir l’un ou l’autre, et pourquoi chez Ondes PRO ils fonctionnent ensemble.
- [Construire une intégration](https://ondes.pro/fr/integrations/mcp/guides/construire-une-integration) — Clés à portées, webhooks signés, idempotence et mode test pour un back-office qui ne crée jamais de doublon.
- [Boutique en ligne](https://ondes.pro/fr/integrations/mcp/modules/boutique-en-ligne) — Commandes, catalogue, codes promo et expéditions pilotés par votre assistant, en mode test par défaut.
- [Facturation](https://ondes.pro/fr/integrations/mcp/modules/facturation) — Devis, factures, relances et avoirs préparés par votre assistant, dans le respect des règles de facturation.

## 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](https://ondes.pro/fr/pricing).

### 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](https://ondes.pro/fr/integrations/mcp/mcp-ou-api-rest).