Intégrer des balances à votre logiciel via une API

Ce que fait une API de balance

Une API de balance (interface de programmation applicative) permet à votre propre logiciel de lire les poids et enregistrements d'une balance et de lui envoyer des commandes, via une interface documentée et lisible par machine plutôt qu'en extrayant un affichage à l'écran ou en analysant un flux d'imprimante. Avec une API, un programme d'enregistrement des captures, un contrôleur de ligne de conditionnement ou un tableau de bord à terre peut utiliser la balance comme source de données et comme appareil contrôlable.

Les intégrations plus anciennes reposaient sur une sortie série continue : la balance envoyait une ligne de texte avec le poids plusieurs fois par seconde via RS232, et le programme récepteur l'analysait. Cela fonctionne toujours, mais cela ne circule que dans un sens et le format diffère selon chaque fabricant. Une API réseau ajoute des données structurées (généralement JSON), l'accès aux enregistrements stockés et aux préréglages, et un moyen défini d'émettre des commandes. Le volet physique de cette connexion est traité dans RS232, Ethernet, USB, Wi-Fi ou Bluetooth LE : choisir une interface de balance.

Points d'accès et fonctions typiques

La plupart des API de balance exposent les cinq mêmes groupes de fonctions : poids en direct, stabilité et statut, préréglages, journaux, et commandes telles que zéro, tare et impression.

Le tableau ci-dessous est une illustration générique de la façon dont une telle API est habituellement organisée. Ce n'est pas le schéma d'un produit spécifique, y compris ceux de WPL.

Deux principes rendent une telle API prévisible. La lecture des données utilise des méthodes sûres qui ne modifient rien sur la balance ; la modification des préréglages ou l'émission de commandes utilise des méthodes dont l'effet est documenté. La sémantique HTTP, y compris les méthodes sûres et idempotentes, est définie dans la RFC 9110. De nombreux fournisseurs décrivent leurs API HTTP au format OpenAPI Specification, ce qui permet de générer du code client et de valider les requêtes.

Exemples de charges utiles

Une réponse de poids en direct doit porter la valeur, son unité, un horodatage et le statut nécessaire pour décider si la valeur peut être utilisée.

Exemple illustratif uniquement, pas le schéma réel de l'API WPL :

{

"scale_id": "scale-03",

"timestamp": "2026-09-14T06:42:17.250Z",

"net": 5.120,

"tare": 0.450,

"unit": "kg",

"stable": true,

"zero": false,

"check": "ok",

"preset": "COD-GUT-5KG"

}

Les champs les plus importants pour l'intégration sont stable et timestamp. Un programme qui enregistre un poids de caisse ne doit accepter qu'une lecture marquée stable, et il doit comparer les horodatages pour détecter une valeur obsolète lorsque la connexion se bloque. Les poids doivent être des nombres JSON avec une unité fixe, et non des chaînes avec l'unité ajoutée, afin de pouvoir être additionnés sans analyse (RFC 8259).

Un échange de commande, à nouveau à titre d'exemple illustratif :

POST /commands

{ "command": "tare", "request_id": "7f3c-0192" }

200 OK

{ "request_id": "7f3c-0192", "result": "done", "tare": 0.450, "unit": "kg" }

L'identifiant request_id permet au client d'associer la réponse à sa requête et permet à la balance de reconnaître une nouvelle tentative d'une commande déjà exécutée, afin qu'une réponse perdue sur une liaison de mauvaise qualité ne provoque pas une seconde tare.

Interrogation ou envoi push

L'interrogation (polling) signifie que le client demande des données à la balance à intervalles réguliers ; le push signifie que la balance envoie des données dès qu'un changement survient. L'interrogation est plus simple à construire, le push est plus efficace pour les valeurs en direct et les événements.

Le coût de l'interrogation est facile à sous-estimer. Interroger le poids en direct cinq fois par seconde produit 432 000 requêtes par jour et par client. Pour un affichage en direct, c'est acceptable sur un réseau local ; sur une liaison satellite, ce ne l'est pas. Un modèle pratique consiste à utiliser le push ou l'interrogation rapide à bord pour les affichages et le contrôle, et à collecter les enregistrements terminés depuis le journal à intervalles pour tout ce qui quitte le navire.

Valeurs en direct et enregistrements

Traitez le poids en direct comme une valeur d'affichage et le journal comme le système de référence. Si votre logiciel construit ses propres enregistrements à partir de valeurs en direct interrogées, il peut manquer des pesées entre les interrogations ou enregistrer deux fois la même caisse. Lire les enregistrements enregistrés depuis le journal de la balance, avec un identifiant d'enregistrement unique, évite ces deux problèmes. Ce que ces enregistrements doivent contenir est décrit dans Enregistrement des données de pesage en mer.

Commandes, sécurité et contrôle d'accès

Les commandes à distance sont puissantes et doivent être restreintes : un zéro ou une tare envoyé au mauvais moment corrompt silencieusement toutes les pesées suivantes.

• Vérifiez l'état avant d'agir. Ne remettez à zéro qu'une balance vide et stable ; ne tarez qu'avec le contenant sur la plateforme et la lecture stable.
• Confirmez le résultat. Lisez le statut après une commande au lieu de supposer qu'elle a réussi.
• Rendez les nouvelles tentatives inoffensives. Utilisez des identifiants de requête ou des opérations idempotentes afin qu'une requête répétée ait le même effet qu'une seule.
• Authentifiez et limitez l'accès. Séparez l'accès en lecture des droits de commande et de modification des préréglages ; n'exposez pas directement les balances à internet.
• Consignez les commandes. Les remises à zéro, tares et changements de préréglages à distance doivent figurer dans la piste d'audit avec le client qui les a envoyés.

Des recommandations sur la gestion du cyber-risque à bord des navires sont publiées par l'OMI dans ses directives de gestion du cyber-risque maritime.

Intégration étape par étape

Une intégration de balance fiable suit une séquence fixe, de la documentation au test sur le terrain.

1. Obtenez la documentation API pour le modèle de balance exact et la version logicielle.
2. Listez les données dont votre logiciel a besoin et associez chaque élément à un champ de l'API, y compris les unités et les décimales.
3. Décidez, par flux de données, d'interroger, de s'abonner ou de lire les journaux.
4. Utilisez des identifiants d'enregistrement pour rendre les imports idempotents et détecter les lacunes.
5. Gérez explicitement les lectures instables, la surcharge, la déconnexion et les délais d'attente.
6. Synchronisez les horloges et stockez les horodatages en UTC.
7. Testez à bord avec le réseau réel, pas seulement au bureau, y compris une perte de connexion en milieu de poste.
8. Consignez la version d'API utilisée, afin qu'une mise à jour logicielle ultérieure puisse être vérifiée pour ses changements.

L'approche de WPL

WeightControl inclut une API intégrée qui renvoie des données en JSON. Grâce à elle, un logiciel externe peut récupérer le poids actuel, le statut de contrôleuse de poids et l'indication de stabilité, charger et modifier des préréglages, lire le dernier enregistrement de journal et tous les journaux stockés, et émettre des commandes telles que Zero, Print et Tare. WeightControl s'exécute sur la balance R10 elle-même ou en tant qu'application externe gérant plusieurs balances. La documentation est fournie avec chaque modèle ; pour plus de détails et de mises à jour, contactez info@wpl-industries.com. Le module WeightControl IOT est disponible en option sur les séries M2, M3, M5 et M6 ; voir le portail données et intégration pour l'architecture plus large.