Journal des versions

Toutes les évolutions de l’API publique, de la plus récente à la plus ancienne.

Ce sur quoi vous pouvez compter

Concrètement, ces changements peuvent survenir sans préavis et ne cassent rien :

un nouveau champ dans une réponse ;
une nouvelle route, une nouvelle portée, un nouveau filtre ;
un nouvel en-tête HTTP ;
un nouveau code d’erreur sur un cas qui échouait déjà.

Côté client, cela suppose une seule discipline : ignorez les champs que vous ne connaissez pas plutôt que de rejeter la réponse. C’est la seule chose qui puisse casser votre intégration lors d’un ajout.

Ceux-ci n’arriveront pas en v1 — ils ouvriraient une /v2, annoncée, avec les deux versions servies en parallèle le temps de la migration :

retirer ou renommer un champ ;
changer le type ou le sens d’un champ ;
retirer une route ou un filtre ;
rendre obligatoire un paramètre qui ne l’était pas.

Comment savoir qu’il y a du nouveau

La sonde publique porte la date du contrat :

curl https://api.omag.ma:7979/api/v1

{
  "api": "omag",
  "version": "v1",
  "statut": "ok",
  "contrat": "2026-09-13.2",
  "journal": "https://docs.omag.ma/developpeurs/changelog/"
}

contrat est un repère de version : une date suivie d’un rang, pour que deux mises en ligne le même jour restent distinguables. Il se compare comme du texte et ne recule jamais.

S’il a changé depuis votre dernier passage, cette page vous dit quoi. Elle ne demande pas de clé — vous pouvez l’interroger depuis une supervision.

14 septembre 2026 — Connecteur IA et option dédiée

Ajouté — Connecteur IA (MCP), en bêta Un connecteur local permet d’interroger vos données en français depuis Claude, Cursor ou VS Code. Neuf outils, résultats déjà totalisés, chaque réponse citant sa source. Voir Connecteur IA (MCP).

Modifié — L’API devient une option L’accès à l’API et au connecteur IA relève désormais du module « API & connecteurs IA ». Un compte qui ne l’a pas reçoit un 403 MODULE_NON_SOUSCRIT, sur l’API comme à la création d’une clé. Les comptes qui utilisaient déjà l’API doivent faire activer l’option.

13 septembre 2026 (2) — Confort d’intégration et achats

Ajouté — En-têtes de quota sur toutes les réponses RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset accompagnent désormais chaque réponse, plus seulement les 429. Vous pouvez ralentir avant d’atteindre le plafond au lieu de gérer des refus. Sur un 429, Retry-After est égal à RateLimit-Reset. Les en-têtes sont exposés au CORS, donc lisibles depuis un navigateur. Le quota est décompté même sur un refus de portée ou d’adresse — votre compteur reste exact quoi qu’il arrive.

Ajouté — Le cycle d’achat Nouvelle portée achats:read, et avec elle /v1/achats/documents/{type} (commandes, réceptions, factures, avoirs fournisseur) et /v1/achats/reglements. Même forme de réponse que les ventes, au nom du tiers près. La portée est distincte de documents:read : un prix d’achat dit ce que vous payez et à qui. Les clés existantes ne l’ont pas — l’administrateur du compte doit la cocher pour l’accorder.

Ajouté — Spécification OpenAPI et interface d’essai GET /v1/openapi.json rend la description complète de l’API, publique et sans clé. Elle permet de générer un client dans votre langage, d’importer l’API dans Postman ou n8n, ou de configurer un assistant IA. La page Essayer l’API la rend interactive, clé de démonstration pré-remplie. Les champs des réponses y sont décrits d’après la base elle-même : la spécification ne peut pas diverger du comportement réel.

Ajouté — Filtres sur les listes Toutes les listes acceptent des filtres nommés, combinés en ET, compatibles avec la pagination et le mode incrémental. Voir le tableau des filtres. Un filtre inconnu ou une valeur invalide rend un 400 FILTRE_INVALIDE qui nomme les filtres acceptés, au lieu d’être ignoré en silence.

13 septembre 2026 — Ouverture de la v1

Première version publique de l’API.

Authentification Clé par société, en-tête X-Omag-Cle (ou Authorization: Bearer). Portées à cocher par l’administrateur du compte. Quota par clé et par minute. Restriction par adresse IP optionnelle.

Lectures Articles, stock par dépôt, clients, fournisseurs, documents de vente (devis, commandes, BL, factures, avoirs), règlements, écritures comptables. Pagination par curseur.

Synchronisation incrémentale ?modifie_depuis= sur toutes les listes, avec les suppressions rendues dans supprimes[]. Sans limite de rétention : vous pouvez remonter à n’importe quelle date.

Flux à plat pour la BI /v1/flux/ventes, /balance, /stock, /reglements — lignes plates, pagination par numéro de page, sortie CSV pour Excel. Les chiffres proviennent des mêmes procédures que les écrans de l’ERP.

Outillage Collection Postman générée par l’API, base de démonstration ouverte avec une clé publique, documentation publique.