JSON API pour les applications mobiles et externes

Une intégration ne doit pas dépendre du balisage d’une page web

Une plateforme d’entreprise cesse d’être un site isolé dès qu’elle est reliée à une application mobile, au poste d’un conducteur, à un portail interne, à un terminal ou au service d’un partenaire. Tenter d’utiliser les pages HTML crée vite une dépendance fragile à la conception visuelle. L’accès direct à la base est encore plus dangereux : le client externe commence à reproduire les règles métier, à ignorer les contrôles d’accès et à dépendre de la structure interne de stockage.

Sapphire I.C.D.S. fournit un environnement d’intégration distinct pour ces tâches : une JSON API sur HTTPS. Elle reçoit des demandes structurées et renvoie des réponses exploitables par une machine, sans produire de pages utilisateur ni imposer au client de connaître l’organisation de la base du serveur. Le Roadmap public présente cet environnement comme une base publiée pour les clients natifs et les intégrations d’entreprise.

JSON est le format d’échange, pas toute l’architecture

JSON ne suffit pas à rendre une intégration fiable. Il faut savoir qui définit la commande disponible, comment l’utilisateur est validé et où intervient la validation métier. Dans Sapphire I.C.D.S., l’API système assure l’authentification et les modules publient les commandes de domaine par un contrat distinct. Le client indique une action et des données, mais le serveur choisit le module responsable, contrôle la demande et construit le résultat.

L’interface web, l’application mobile et un système externe peuvent ainsi employer la même logique de domaine. Par exemple, l’enregistrement du résultat d’une livraison doit contrôler de la même manière la tournée, le magasin, la marchandise et les droits de l’exécutant, quel que soit l’écran d’origine. Le client fournit une interface pratique ; le module garantit la validité du processus.

Le serveur valide la session et l’identité

L’API prend en charge le cycle élémentaire d’une session cliente : connexion, obtention de l’utilisateur confirmé actuel, renouvellement de l’accès et déconnexion. Après une connexion réussie, le client reçoit un jeton d’accès de courte durée et un jeton de renouvellement distinct. Lors du renouvellement, la paire est remplacée ; l’application doit donc la stocker atomiquement et ne pas répéter avec l’ancienne valeur une opération déjà réussie.

Le principe essentiel est que les champs d’utilisateur, de groupe ou d’objet contenus dans JSON ne prouvent aucun droit. Le serveur extrait l’identité de la session validée avant de déterminer le périmètre de données accessible. Un module logistique ne doit pas, par exemple, afficher une autre tournée parce que le client a transmis l’identifiant d’un autre conducteur. Le lien avec le rôle métier est résolu côté serveur.

Les modules ne publient que des actions explicites

L’API dédiée n’ouvre pas automatiquement toutes les fonctions de Sapphire I.C.D.S. Le module doit fournir un prestataire d’API et énumérer les commandes prises en charge. Les intégrations peuvent ainsi être publiées progressivement : d’abord les lectures sûres, puis les modifications limitées et, après validation, les processus plus complexes. Un module dépourvu de contrat externe ne devient pas accessible du seul fait de son installation.

Les commandes qui changent l’état doivent utiliser des demandes prévues pour la modification, tandis que la lecture peut rester une opération séparée. Le serveur renvoie des codes clairs pour une demande incorrecte, une session expirée, un refus, une méthode inadéquate ou l’indisponibilité temporaire d’une dépendance. L’application cliente reçoit une branche de traitement définie, et non une page HTML d’erreur.

• Le client mobile n’envoie que les données nécessaires et stocke les jetons dans l’espace protégé de l’appareil.
• L’environnement API valide la session, la méthode de la demande et la taille d’entrée autorisée.
• Le module contrôle les règles de domaine, le périmètre de l’utilisateur et la transition d’état permise.
• La base de données reste derrière la couche serveur et n’est jamais publiée directement au client.

Les scénarios métier appropriés

La JSON API est particulièrement utile lorsque le collaborateur travaille hors du back-office principal. En logistique, elle peut fournir la liste des tournées attribuées, les données d’un point et l’enregistrement des quantités livrées, des retours ou de l’état des documents. En comptabilité, elle peut transmettre un référentiel et recevoir une opération confirmée. Dans une application externe, elle permet de lire un état autorisé et de lancer une commande précise sans imiter les actions du navigateur.

Le Roadmap public cite la logistique, la comptabilité et les opérations de terrain comme axes naturels d’évolution. Cela ne signifie pas qu’un endpoint universel existe déjà pour chaque scénario. La disponibilité dépend des commandes API du module installé. Avant un projet d’intégration, il convient d’établir une matrice des opérations, données, rôles et versions.

La JSON API n’est pas le MCP externe

Les deux environnements emploient des données structurées, mais servent des catégories de clients différentes. La JSON API cible les applications mobiles et d’entreprise dont le parcours utilisateur est conçu à l’avance. Le MCP externe, qui reste en developer alpha et n’a été vérifié qu’avec l’intégration actuelle de ChatGPT sur sapphire-project.com, cible des clients d’AI compatibles qui découvrent des outils et les appellent dans une session agentique. Leurs droits et règles de publication ne sont pas interchangeables.

L’API n’est pas non plus une console SQL distante, un générateur arbitraire de rapports ou une promesse d’accès à toutes les tables. Elle expose des commandes métier placées sous la responsabilité d’un module. Ce niveau d’abstraction résiste mieux aux évolutions du schéma de données et offre une maintenance plus sûre à long terme.

Ce qui est attendu de l’application cliente

Un client natif doit gérer correctement l’expiration du jeton d’accès, le remplacement du jeton de renouvellement, la déconnexion, l’absence de réseau et les nouvelles tentatives. Pour les opérations modifiant l’état, il est particulièrement important de distinguer un refus confirmé d’un résultat de transport incertain : sans idempotence convenue, une action qui a peut-être été exécutée ne peut pas être répétée automatiquement. Le cache local ne doit pas être considéré comme la source des droits actuels.

L’équipe technique définit également le versionnement des contrats, la journalisation, les limites de demandes et la stratégie de compatibilité. La plateforme apporte un environnement modulaire commun, mais la qualité d’un produit mobile précis dépend de la discipline du client et de l’exhaustivité du contrat métier publié.

Le parcours de mise en œuvre

Le travail doit commencer par l’inventaire des scénarios utilisateurs, et non par une liste de tables. Pour chaque étape, il faut fixer les champs d’entrée, la réponse, le rôle, le périmètre de données, les transitions admises et le comportement en cas de répétition. Le module publie ensuite le minimum de commandes, l’équipe mobile construit l’interface et les tests communs vérifient les cas autorisés comme interdits.

Pour le propriétaire, le résultat est la possibilité de développer ses propres applications sans copier la logique du serveur. Pour la direction technique, il s’agit d’une limite d’intégration gouvernée avec authentification commune et commandes modulaires. La JSON API étend Sapphire I.C.D.S. au-delà de l’interface web, tout en maintenant données, droits et règles de processus dans l’environnement serveur faisant autorité.