Développeurs
Développer sur Hermetry
Connectez vos appareils via MQTT ou HTTPS, travaillez avec votre organisation grâce à l’API REST, réagissez aux événements avec des webhooks signés et laissez les assistants IA lire vos données via MCP.
Quatre voies d’accès
Une plateforme, quatre interfaces
Les appareils utilisent l’API des appareils. Vos systèmes utilisent l’API REST et les webhooks. Les assistants IA utilisent MCP. Ne placez jamais une clé d’API sur un appareil, ni un jeton d’appareil dans une intégration.
API des appareils
Les appareils envoient des données et reçoivent des commandes via MQTT ou HTTPS. Ils s’authentifient avec un jeton d’appareil, un nom d’utilisateur et un mot de passe MQTT, ou un certificat.
API REST
Votre ERP, MES, système de tickets ou script appelle Hermetry avec une clé d’API ne disposant que des droits que vous choisissez.
Webhooks
Hermetry appelle votre système lorsqu’un événement se produit : un appareil passant hors ligne, une alarme ouverte, une commande terminée.
Serveurs MCP
Un assistant IA compatible MCP appelle les outils de Hermetry avec une clé d’API ou une connexion, sans jamais pouvoir faire plus que la personne concernée.
API des appareils
Envoyez votre première mesure
Via MQTT, l’appareil maintient une seule connexion ouverte. Via HTTPS, il envoie une requête par message. Les charges utiles sont identiques.
MQTT
- MQTT 3.1.1, TLS sur le port 8883 (TLS 1.2 ou ultérieur), vers l’hôte indiqué sur la carte Détails de connexion de l’appareil
- Nom d’utilisateur : le jeton d’accès de l’appareil, mot de passe vide
- Les topics commencent par
v1/; utilisez QoS 1 - Une mesure est un objet JSON plat, ou
tsetvalueslorsque l’appareil connaît l’heure
CONNECT port 8883 (TLS)
username: <device access token>, password: empty
SUBSCRIBE v1/attributes/set (QoS 1)
SUBSCRIBE v1/attributes/res/+ (QoS 1)
SUBSCRIBE v1/rpc/req/+ (QoS 1)
PUBLISH v1/attributes/req/1 {}
PUBLISH v1/telemetry {"temperature": 21.5, "humidity": 40}
{"temperature": 21.5, "humidity": 40, "door_open": false}
{"ts": 1759572000000, "values": {"temperature": 21.5, "humidity": 40}}
HTTPS
- Un POST par message, avec le jeton dans un en-tête
Authorization: Bearer - Les mêmes formes de charge utile et règles de clés que pour MQTT, jusqu’à 64 KiB
- Les commandes attendent dans une requête longue (long poll) d’au plus 60 secondes
- Les appareils sur batterie qui se réveillent, envoient et se rendorment conviennent le mieux
curl -X POST 'https://<your-host>/api/v1/telemetry' \
-H 'Authorization: Bearer <device access token>' \
-H 'Content-Type: application/json' \
-d '{"ts":1759572000000,"values":{"temperature":21.5,"humidity":40}}'
curl -X GET 'https://<your-host>/api/v1/rpc?timeout=20000' \
-H 'Authorization: Bearer <device access token>'
API REST
Appelez l’API avec une clé limitée
Une clé d’API agit au nom du membre qui l’a créée, limitée aux droits que vous cochez pour elle. Il n’y a pas d’échange de jeton : la clé est envoyée à chaque appel.
- Les clés ont la forme
sk_live_…et ne sont affichées qu’une seule fois - Les droits sont choisis module par module, sans jamais dépasser les vôtres
- Chaque clé expire : 90 jours par défaut, un an au maximum
- Une liste d’adresses IP autorisées allant jusqu’à 100 sous-réseaux limite les endroits où une clé fonctionne
- Les chemins se trouvent sous votre organisation :
/tenant/<tenantId>/api/…
curl "https://<your host>/tenant/<tenantId>/api/iot/devices" \
-H "Authorization: Bearer sk_live_…"
GET /tenant/{tenantId}/api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity
Webhooks
Réagissez aux événements, et vérifiez qu’ils viennent de nous
Chaque livraison est un POST avec l’événement dans le corps et une signature dans les en-têtes. Vérifiez X-Webhook-Signature-V2 avec votre secret de signature avant de faire confiance au corps.
- Adresses HTTPS uniquement, avec jusqu’à 20 en-têtes personnalisés de votre choix
- Les filtres d’événements ne livrent que les événements dont la charge utile correspond
- Le même identifiant
X-Webhook-Deliveryà chaque nouvelle tentative, pour pouvoir écarter les doublons - CloudEvents 1.0 au lieu de l’enveloppe par défaut, si vous le préférez
{
"webhookId": "…",
"tenantId": "…",
"event": "device.disconnected",
"createdAt": "2026-11-03T12:00:30.000Z",
"data": { "deviceId": "…", "name": "router-17", "reason": "timeout" }
}
import crypto from 'crypto';
function verifyWebhook(body: string, timestamp: string, signatureV2: string, secret: string): boolean {
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
// Reject deliveries older than 5 minutes.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const a = Buffer.from(expected);
const b = Buffer.from(signatureV2);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Limites
Limites à prévoir
Une limite répond 429 avec un en-tête Retry-After. Attendez ce délai, espacez les nouvelles tentatives en cas de répétition, et ne retentez jamais à l’identique une réponse 400, 401, 403, 404 ou 422.
| Limite | Par défaut | S’applique à |
|---|---|---|
| Limite par adresse | 120 requêtes par minute | Chaque adresse IP appelante |
| Limite par clé | 1 000 appels par minute | Chaque clé d’API |
| Commandes | 10 par minute par appareil, 600 par minute par organisation | Commandes vers les appareils |
| Outils MCP | 120 appels de lecture et 20 d’écriture par minute | Chaque identifiant |
| Corps HTTP des appareils | Jusqu’à 64 KiB | Chaque message d’appareil |
Assistants IA
Connecter un assistant IA via MCP
Chaque module dispose de son propre serveur MCP sous l’adresse de votre espace de travail. MCP reste désactivé tant qu’un administrateur ne l’active pas, et un assistant ne voit que les outils que sa personne est autorisée à utiliser.
- Appareils, mesures et tableaux de bord : lecture seule
- Alarmes : acquitter une alarme immédiatement ; la levée d’une alarme attend une seconde personne
- Les réponses sont limitées à 10 secondes et 256 KiB
- Les identifiants, jetons et clés des appareils ne sont jamais renvoyés
https://<your host>/tenant/<tenantId>/api/mcp/iot_device
https://<your host>/tenant/<tenantId>/api/mcp/telemetry
https://<your host>/tenant/<tenantId>/api/mcp/iot_alarm
https://<your host>/tenant/<tenantId>/api/mcp/dashboard
Monter en charge et étendre
Quand un appareil devient mille
Importer depuis un CSV
Ajoutez des centaines d’appareils à partir d’un fichier. Chaque import est vérifié d’abord, appliqué après relecture et peut être annulé.
Revendication et provisionnement
Appareils revendiqués avec un code, ou enregistrés à la première connexion via une session de provisionnement.
Micrologiciels signés par vagues
Vous signez les images dans votre propre chaîne et n’enregistrez que les clés publiques. Les déploiements partent par vagues.
Vos propres codecs
Décodez un capteur LoRaWAN que la bibliothèque ne couvre pas, avec un codec que vous publiez : une table JSON, jamais un script.
Bloc script
Quand les blocs prêts à l’emploi d’un flux ne suffisent pas, exécutez votre propre JavaScript sur chaque message.
Vos propres widgets
Enregistrez une carte configurée comme widget, ou créez des widgets à partir d’un modèle HTML avec leur propre formulaire de réglages.
Référence
Référence de l’API
Commencez à développer sur Hermetry
Créez une organisation, ajoutez un appareil et effectuez votre premier appel API.

