Devices API v3

Cette page répertorie chaque endpoint de la Devices API v3, les informations d'identification attendues par chacun, ainsi que les conventions de requête et de réponse. Utilisez-la avec la spécification OpenAPI en ligne lorsque vous développez le micrologiciel d'un appareil, des outils d'usine ou des scripts de provisionnement.

URL de base et spécification

La spécification est au format OpenAPI 3.0.1. Générez-en un client avec n'importe quel générateur OpenAPI, comme décrit dans Public API.

La Devices API est destinée aux appareils et aux outils qui les mettent en service. Pour gérer votre parc, vos utilisateurs et vos données, utilisez la Public API.

Informations d'identification

Toutes les informations d'identification circulent dans la requête, jamais dans l'URL. Les informations d'identification de type bearer utilisent l'en-tête Authorization: Bearer <value>.

Un JWT d'appareil ou une clé de provisionnement n'est jamais accepté par la Public API.

Endpoints

Dans le tableau, {P} représente /api/v3/projects/{project_id}/regions/{region_id}. L'identifiant de région est 1, sauf indication contraire.

Provisionnement

Corps de la requête pour les deux méthodes de provisionnement :

POST /api/v3/provision HTTP/1.1
Host: devices.fundamentum-iot.com
Content-Type: application/json

{
  "project_id": <project-id>,
  "region_id": 1,
  "registry_id": <registry-id>,
  "serial_number": "<serial-number>",
  "asset_type_id": 2,
  "access_token": "<registry-token>",
  "algorithm": "RS256",
  "secret": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
}

Une réponse réussie renvoie la configuration de l'appareil et l'adresse à laquelle se connecter :

{
  "status": "success",
  "data": {
    "configuration": {},
    "mqtt": { "host": "mqtts.fundamentum-iot.com", "port": 8883 }
  }
}

Si l'appareil existe déjà, POST répond :

{
  "status": "error",
  "message": "Authorization conflict",
  "data": { "error": "device already provisioned" }
}

Le reprovisionnement est toujours une étape explicite : n'utilisez PUT que si vous souhaitez réellement remplacer la clé. Voir Self-provisioning.

Le fichier de jeton du registre contient server_url, mqtt_host, mqtt_port, token, project_id, region_id et registry_id.

Appareils

La télémétrie via HTTPS est l'alternative à MQTT pour les appareils qui ne peuvent pas maintenir une connexion ouverte. Voir HTTPS alternative.

curl -X POST "https://devices.fundamentum-iot.com/api/v3/projects/<project-id>/regions/1/registries/<registry-id>/devices/<serial-number>/telemetry" \
  -H "Authorization: Bearer $DEVICE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 21.4}'

Appareils en stock

Les appareils en stock sont préenregistrés en usine avec une clé de provisionnement, puis affectés ultérieurement à un registre. Voir Shelf devices and provisioning keys.

Clés de provisionnement

start_at et end_at sont des dates au format YYYY-MM-DD, interprétées à minuit UTC. Une clé est active lorsque start_at ≤ maintenant < end_at. La clé elle-même est un UUID.

Numéros de série

• Lettres minuscules, chiffres, - et _.
• Uniques au sein d'un registre, et comparés sans tenir compte de la casse.
• Les identifiants de type d'actif sont des entiers positifs. Les valeurs négatives sont réservées.

Réponses et erreurs

Les réponses utilisent l'enveloppe status/data décrite dans Conventions.

Autres versions

Chaque version publie sa spécification à l'adresse /api/{version}/swagger.json. Voir Changelog and deprecations.

Et ensuite

• Provisioning
• Connect over MQTTS
• MQTT topics and message formats