API BlueCold

1 Introduction

1.1 But du document

Ce document décrit les spécifications techniques des APIs disponibles en sortie de la solution BlueCold. Celles-ci permettent de récupérer toutes les données brutes liées à la flotte de capteurs et de gateways gérée par l'utilisateur, ainsi que des informations métier qui ont pu être renseignées dans BlueCold :

Caractéristiques des devices
Données générées par les devices
Caractéristiques des assets
Associations capteur / asset
Caractéristiques des gateways

2 Fonctionnement de l'API

2.1 Généralités

Les endpoints se réfèrent à un paramètre <base_url>.

L'URL utilisée est : https://bluecold.elainnovation.com

2.2 Authentification

Obtenir un token d'authentification

POST <base_url>/api/auth/login

Payload :

{
  "username": "utilisateur@exemple.com",
  "password": "mot_de_passe"
}

Réponse :

{
  "token": "<ACCESS_TOKEN>",
  "refreshToken": "<REFRESH_TOKEN>"
}

Rafraîchir un token existant

Dans le cas où l'utilisateur s'est déjà authentifié et possède un jeton actif, il est aussi possible d'utiliser le champ refreshToken pour le réactualiser :

POST <base_url>/api/auth/token

Payload :

{
  "refreshToken": "<REFRESH_TOKEN>"
}

Réponse :

{
  "token": "<ACCESS_TOKEN>",
  "refreshToken": "<REFRESH_TOKEN>"
}

Durée de validité par défaut

Token	Durée
Access Token (JWT)	2,5 heures (9 000 secondes)
Refresh Token	1 semaine (604 800 secondes)

Le token doit ensuite être utilisé dans le header Authorization des requêtes suivantes, avec la valeur :

Bearer <ACCESS_TOKEN>

Note : Si l'utilisateur ne s'est pas reconnecté ni n'a rafraîchi son token depuis plus d'une semaine, il devra obligatoirement se réauthentifier.

2.3 Description des formats de stockage

BlueCold stocke la donnée sous quatre formats, tous liés à une entité (c'est-à-dire un beacon ou un asset) :

Format	Description	Exemple
Entity Info	Donnée caractéristique de l'entité	Nom
Attribute	Donnée secondaire de l'entité	Numéro de commande ELA
Timeseries	Donnée historisée liée au capteur	Température
Relations	Associations entre capteur et asset	—

2.4 Liste des champs disponibles via API

Le tableau ci-dessous résume tous les champs disponibles par API, le format dans lequel ils sont stockés dans BlueCold, et leur nom. L'utilisateur peut requêter ces champs en faisant un appel générique sur les entity infos, les attributes ou les timeseries d'une entité en spécifiant le nom du champ souhaité (dernière colonne).

Champ	Capteur	Asset	Gateway	Enregistré comme	Nom du champ dans BlueCold
Adresse MAC / identifiant	✓	✓	✓	Entity info	`name`
bluecold_id	✓	✓	✓	Entity info	`id`
Nom	✓	✓	✓	Entity info	`label`
Groupe d'utilisateurs capteurs	✓			Attribute	`sensorGroupMember`
Groupe d'utilisateurs gateways			✓	Attribute	`gatewayGroupMember`
Version firmware	✓			Attribute	`firmwareVersion`
Etat	✓		✓	Attribute	`active`
Numéro de commande ELA	✓		✓	Attribute	`order`
Date d'intégration dans BlueCold	✓		✓	Attribute	`added`
Etat de la batterie	✓			Timeseries	`batteryLevel`
Date du dernier étalonnage	✓			Attribute	`lastCalibrationDate`
Date du prochain étalonnage	✓			Attribute	`nextCalibrationDate`
URL du certificat d'étalonnage actif	✓			Attribute	`calibrationReportUrl`
Type de gateway			✓	Attribute	`gatewayType`
Date de dernière connexion gateway			✓	Attribute	`lastConnectTime`
Date de dernière déconnexion gateway			✓	Attribute	`lastDisconnectTime`
Date de dernière activité gateway			✓	Attribute	`lastActivityTime`
Historique des associations de l'asset		✓		Attribute	`assetHistory`
Liste de la position des capteurs dans l'asset		✓		Attribute	`assetPositions`
Données capteur : horodatage capteur (voir section 2.4.1)	✓			Timeseries	`sensorValue`
Données capteur : horodatage serveur (voir section 2.4.1)	✓			Timeseries	`sensorValue_received`
Datalogger	✓			Timeseries	`datalogger`
Asset contenant le capteur	✓			Relations	—
Capteurs associés à l'asset		✓		Relations	—

2.4.1 Horodatage des données capteurs

BlueCold met à disposition deux champs pour récupérer la donnée capteur :

sensorValue : donnée du capteur horodatée au moment du scan de la trame Bluetooth par la gateway. Cela permet de reconstituer un historique de données pour le capteur.

{
  "sensorValue": [
    {
      "ts": 1751292795758,
      "value": "{\"type\":\"temperature_live\",\"value\":-5.12}"
    }
  ]
}

sensorValue_received : donnée du capteur horodatée au moment de sa sauvegarde dans la plateforme BlueCold. Cela permet de récupérer la donnée même historique au fur et à mesure qu'elle est disponible. La valeur contient en plus le champ measuredTs qui permet de retrouver l'horodatage de la mesure capteur.

{
  "sensorValue_received": [
    {
      "ts": 1751292795758,
      "value": "{\"type\":\"temperature\",\"value\":26.87,\"measuredTs\":1751292785750}"
    }
  ]
}

2.5 Exemple de workflow : initialisation d'un système tiers

Authentification → Récupération du token JWT pour la suite des requêtes
Liste des devices du client
- Lecture des ids bluecold, noms et labels
Liste des assets du client
- Lecture des ids bluecold, noms et labels
Pour chaque device
- Lecture du id bluecold, nom et label
- Lecture des attributs
- Récupération de la télémétrie
- Relation vers l'asset contenant le device (si existant)
Pour chaque asset
- Lecture du id bluecold, nom et label
- Lecture des attributs

3 Description des APIs

3.1 Liste des devices (capteurs et gateways)

3.1.1 Description

Liste tous les devices du client et fournit leur bluecold_id, utilisé pour les requêtes sur un device spécifique.

3.1.2 URL

GET <base_url>/api/user/devices?pageSize=<page_size>&page=<page_num>

3.1.3 Paramètres

Paramètre	Description
`page_size`	Nombre de devices par page. Exemple : 100
`page_num`	Numéro de page demandé, commence à 0. Exemple : 0 (première page)

3.1.4 Réponse

{
  "data": [
    {
      "id": {
        "entityType": "DEVICE",
        "id": "<bluecold_id>"
      },
      "createdTime": 1751289432568,
      "tenantId": {
        "entityType": "TENANT",
        "id": "<tenant_id>"
      },
      "customerId": {
        "entityType": "CUSTOMER",
        "id": "<customer_id>"
      },
      "name": "<device_name>",
      "type": "default",
      "label": "",
      "deviceProfileId": null,
      "firmwareId": null,
      "softwareId": null,
      "externalId": null,
      "version": null,
      "ownerId": {
        "entityType": "CUSTOMER",
        "id": "<customer_id>"
      },
      "additionalInfo": {
        "gateway": false,
        "overwriteActivityTime": false,
        "description": ""
      },
      "deviceData": null
    }
  ],
  "totalPages": 15,
  "totalElements": 30,
  "hasNext": true
}

3.2 Liste des actifs (assets)

3.2.1 Description

Liste tous les assets du client et fournit leur bluecold_id, utilisé pour les requêtes sur un asset spécifique.

3.2.2 URL

GET <base_url>/api/user/assets?pageSize=<page_size>&page=<page_num>

3.2.3 Paramètres

Paramètre	Description
`page_size`	Nombre d'assets par page. Exemple : 100
`page_num`	Numéro de page demandé, commence à 0. Exemple : 0 (première page)

3.2.4 Réponse

{
  "data": [
    {
      "id": {
        "entityType": "ASSET",
        "id": "<bluecold_id>"
      },
      "createdTime": 1751293508556,
      "tenantId": {
        "entityType": "TENANT",
        "id": "<tenant_id>"
      },
      "customerId": {
        "entityType": "CUSTOMER",
        "id": "<customer_id>"
      },
      "name": "<asset_name>",
      "type": "default",
      "label": null,
      "assetProfileId": null,
      "externalId": null,
      "version": null,
      "ownerId": {
        "entityType": "CUSTOMER",
        "id": "<customer_id>"
      },
      "additionalInfo": {
        "description": ""
      }
    }
  ],
  "totalPages": 1,
  "totalElements": 1,
  "hasNext": false
}

3.3 Données historisées (timeseries)

3.3.1 Description

Permet d'accéder aux données historisées de chaque device de BlueCold.

Note : Il n'y a pas de timeseries côté asset.

3.3.2 URL

GET <base_url>/api/plugins/telemetry/DEVICE/<bluecold_id>/values/timeseries?keys=<telemetry_keys>&startTs=<start_ts>&endTs=<end_ts>

3.3.3 Paramètres

Paramètre	Description
`bluecold_id`	Identifiant interne unique du device, propre à BlueCold. Voir section 3.1. Note : cet id n'est ni le NAME, ni l'ADRESSE MAC.
`telemetry_keys`	Nom des champs à récupérer, séparés par des virgules. Exemple pour un capteur température : `sensorValue` ou `sensorValue_received`
`start_ts`	Borne de début de l'intervalle de temps. Format : UNIX millisecondes
`end_ts`	Borne de fin de l'intervalle de temps. Format : UNIX millisecondes
`limit`	(Facultatif) Nombre maximal de points de données de séries temporelles à récupérer. Maximum : 50 000.
`orderBy`	(Facultatif) Ordre de tri : `ASC` (croissant) ou `DESC` (décroissant).

3.3.4 Réponse

{
  "sensorValue_received": [
    {
      "ts": 1751292795758,
      "value": "{\"type\":\"temperature\",\"value\":26.87,\"measuredTs\":1751292785750}"
    }
  ]
}

3.4 Attributs

3.4.1 Description

Permet d'accéder aux caractéristiques secondaires (attributs) de chaque device de BlueCold.

3.4.2 URL

Pour récupérer les attributs relatifs à un device :

GET <base_url>/api/plugins/telemetry/DEVICE/<bluecold_id>/values/attributes?keys=<attribute_keys>

Une gateway est considérée comme un device. Par exemple, pour récupérer les groupes d'utilisateurs d'une gateway :
GET <base_url>/api/plugins/telemetry/DEVICE/<bluecold_id>/values/attributes?keys=gatewayGroupMember

Pour récupérer les attributs relatifs à un asset :

GET <base_url>/api/plugins/telemetry/ASSET/<bluecold_id>/values/attributes?keys=<attribute_keys>

3.4.3 Paramètres

Paramètre	Description
`bluecold_id`	Identifiant interne unique du device, propre à BlueCold. Voir section 3.1. Note : cet id n'est ni le NAME, ni la MAC ADDRESS.
`attribute_keys`	Nom des champs à récupérer, séparés par des virgules. Exemple : `lastCalibrationDate,nextCalibrationDate`

3.4.4 Réponse

[
  {
    "lastUpdateTs": 1750668601047,
    "key": "lastCalibrationDate",
    "value": "2025-05-12"
  }
]

3.5 Relations

Cette API permet de trouver l'asset contenant le device courant (cf. exemple de workflow).

3.5.1 URL

Requête pour récupérer l'asset contenant le device courant :

GET <base_url>/api/relations?fromId=<bluecold_id_capteur>&fromType=DEVICE

Requête pour lister les capteurs contenus dans un asset :

GET <base_url>/api/relations?toId=<bluecold_id_asset>&toType=ASSET

3.5.2 Paramètres

Paramètre	Description
`bluecold_id_capteur`	Identificateur interne unique du device dont on cherche l'asset associé. Note : cet id n'est ni le NAME, ni l'ADRESSE MAC.
`bluecold_id_asset`	Identificateur interne unique de l'asset dont on cherche les devices associés. Note : cet id n'est ni le NAME, ni l'ADRESSE MAC.

3.5.3 Réponse

Réponse pour fromType=DEVICE (asset contenant le device) :

[
  {
    "from": {
      "entityType": "ASSET",
      "id": "<bluecold_id_asset>"
    },
    "to": {
      "entityType": "DEVICE",
      "id": "<bluecold_id_capteur>"
    },
    "type": "Contains",
    "typeGroup": "COMMON",
    "version": 791355646,
    "additionalInfo": {
      "created": 123456789
    }
  }
]

Réponse pour toType=ASSET (devices contenus dans l'asset) :

[
  {
    "from": {
      "entityType": "ASSET",
      "id": "<bluecold_id_asset>"
    },
    "to": {
      "entityType": "DEVICE",
      "id": "<bluecold_id_capteur>"
    },
    "type": "Contains",
    "typeGroup": "COMMON",
    "version": 791355646,
    "additionalInfo": {
      "created": 123456789
    }
  }
]

1 Introduction​

1.1 But du document​

2 Fonctionnement de l'API​

2.1 Généralités​

2.2 Authentification​

Obtenir un token d'authentification​

Rafraîchir un token existant​

Durée de validité par défaut​

2.3 Description des formats de stockage​

2.4 Liste des champs disponibles via API​

2.4.1 Horodatage des données capteurs​

2.5 Exemple de workflow : initialisation d'un système tiers​

3 Description des APIs​

3.1 Liste des devices (capteurs et gateways)​

3.1.1 Description​

3.1.2 URL​

3.1.3 Paramètres​

3.1.4 Réponse​

3.2 Liste des actifs (assets)​

3.2.1 Description​

3.2.2 URL​

3.2.3 Paramètres​

3.2.4 Réponse​

3.3 Données historisées (timeseries)​

3.3.1 Description​

3.3.2 URL​

3.3.3 Paramètres​

3.3.4 Réponse​

3.4 Attributs​

3.4.1 Description​

3.4.2 URL​

3.4.3 Paramètres​

3.4.4 Réponse​

3.5 Relations​

3.5.1 URL​

3.5.2 Paramètres​

3.5.3 Réponse​