API BlueCold

Cette documentation décrit les spécifications techniques des APIs disponibles en sortie de la solution BlueCold. Elles permettent de récupérer toutes les données brutes relatives à la flotte de capteurs et passerelles gérées par l'utilisateur, ainsi que les informations métier qui auraient pu être saisies dans BlueCold :

Caractéristiques des appareils
Données générées par les appareils
Caractéristiques des assets
Associations capteurs / assets
Caractéristiques des passerelles

Informations générales

Tous les endpoints font référence à un paramètre <base_url>.

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

Authentification

Obtenir un token d'authentification

POST <base_url>/api/auth/login

Payload :

{
  "username": "user@example.com",
  "password": "password"
}

Réponse :

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

Rafraîchir un token existant

Si l'utilisateur s'est déjà authentifié et possède un token actif, le champ refreshToken peut être utilisé pour le renouveler :

POST <base_url>/api/auth/token

Payload :

{
  "refreshToken": "<REFRESH_TOKEN>"
}

Réponse :

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

Durées 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 inclus dans l'en-tête Authorization des requêtes suivantes, avec la valeur :

Bearer <ACCESS_TOKEN>

Note

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

Concepts clé

Description du format de stockage

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

Format	Description	Exemple
Entity Info	Données de caractéristiques essentielles de l'entité	Nom
Attribute	Données secondaires de l'entité	Numéro de commande ELA
Timeseries	Données historiques horodatées liées à un capteur	Température
Relations	Associations entre capteurs et assets	—

Hiérarchie client

Client : Compte principal (par exemple, « Logistics Corp France »)
Sous-client : Compte enfant dans une hiérarchie (par exemple, « Logistics Corp - Agence de Lyon »)
- Les sous-clients héritent des autorisations de leur client parent.
- Le paramètre d'API fetchSubCustomerDevices=true permet d'inclure les appareils des comptes enfants.
Appareil : Balise BLE physique (capteur ou passerelle)
Actif : Entité métier regroupant plusieurs appareils (par exemple, une palette d'expédition ou un conteneur)

Liste des champs disponibles via l'API

Le tableau ci-dessous résume tous les champs disponibles via l'API, le format dans lequel ils sont stockés dans BlueCold, et leur nom de champ. Les utilisateurs peuvent interroger ces champs en effectuant un appel générique sur les infos d'entité, les attributs ou les timeseries d'une entité, en spécifiant le nom de champ souhaité (dernière colonne).

Champ	Capteur	Asset	Passerelle	Stocké comme	Nom du champ dans BlueCold
Adresse MAC / identificateur	✓	✓	✓	Entity info	`name`
bluecold_id	✓	✓	✓	Entity info	`id`
Nom	✓	✓	✓	Entity info	`label`
Groupe d'utilisateurs du capteur	✓			Attribute	`sensorGroupMember`
Groupe d'utilisateurs de la passerelle			✓	Attribute	`gatewayGroupMember`
Version du firmware	✓			Attribute	`firmwareVersion`
Statut	✓		✓	Attribute	`active`
Numéro de commande ELA	✓		✓	Attribute	`order`
Date d'ajout à BlueCold	✓		✓	Attribute	`added`
Niveau de 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 passerelle			✓	Attribute	`gatewayType`
Date de dernière connexion de la passerelle			✓	Attribute	`lastConnectTime`
Date de dernière déconnexion de la passerelle			✓	Attribute	`lastDisconnectTime`
Date de dernière activité de la passerelle			✓	Attribute	`lastActivityTime`
Historique d'association d'asset		✓		Attribute	`assetHistory`
Liste des positions des capteurs dans l'asset		✓		Attribute	`assetPositions`
Données du capteur : timestamp du capteur (voir section 4.1)	✓			Timeseries	`sensorValue`
Données du capteur : timestamp du serveur (voir section 4.1)	✓			Timeseries	`sensorValue_received`
Datalogger	✓			Timeseries	`datalogger`
Asset contenant le capteur	✓			Relations	—
Capteurs associés à l'asset		✓		Relations	—

Timestamps des données de capteur

BlueCold fournit deux champs pour récupérer les données du capteur :

sensorValue : données du capteur horodatées au moment où la trame Bluetooth est scannée par la passerelle. Cela permet de reconstituer une chronologie de données historiques pour le capteur.

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

sensorValue_received : données du capteur horodatées au moment où elles sont sauvegardées dans la plateforme BlueCold. Cela permet de récupérer les données historiques à mesure qu'elles deviennent disponibles. La valeur contient également le champ measuredTs, qui fournit le timestamp de mesure original du capteur.

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

Point clé

Utilisez sensorValue pour la reconstruction de la chronologie (à quel moment la température a été mesurée), utilisez sensorValue_received pour la publication (à quel moment la donnée a été enregistrée dans BlueCold).

Référence API

Liste des appareils (capteurs et passerelles)

Description

Liste tous les appareils du client et fournit leur bluecold_id, qui est utilisé pour d'autres requêtes sur un appareil spécifique.

URL

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

Paramètres

Paramètre	Description
`page_size`	Nombre d'appareils par page. Exemple : 100
`page_num`	Numéro de page demandé, en commençant par 0. Exemple : 0 (première page)

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
}

Liste des assets

Description

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

URL

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

Paramètres

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

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
}

Données historiques (timeseries) par appareil

Description

Fournit l'accès aux données historiques d'un appareil dans BlueCold.

info

Note : Il n'y a pas de timeseries du côté de l'asset. Conception : Cet endpoint récupère les timeseries d'un appareil unique. Adapté pour les requêtes à la demande ou les tableaux de bord.

Scalabilité

Ne pas utiliser pour l'interrogation systématique de plusieurs appareils ou l'alimentation de systèmes externes. Chaque appareil nécessite une requête séparée, ce qui entraîne :

Un volume élevé d'appels API et l'épuisement des limites de débit
Une surcharge réseau et une accumulation de latence
Une utilisation inefficace des ressources

Pour l'ingestion à grande échelle : Utilisez plutôt les endpoints d'export de télémétrie en masse de la section 6.

URL

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

Paramètres

Paramètre	Description
`bluecold_id`	Identificateur interne unique de l'appareil, spécifique à BlueCold. Voir section 5.1. Note : cet identifiant n'est ni le NOM ni l'ADRESSE MAC.
`telemetry_keys`	Noms des champs à récupérer, séparés par des virgules. Exemple pour un capteur de température : `sensorValue` ou `sensorValue_received`
`start_ts`	Limite de début de la plage temporelle. Format : UNIX millisecondes
`end_ts`	Limite de fin de la plage temporelle. Format : UNIX millisecondes
`limit`	(Optionnel) Nombre maximum de points de données de timeseries à récupérer. Maximum : 50 000.
`orderBy`	(Optionnel) Ordre de tri : `ASC` (croissant) ou `DESC` (décroissant).

Réponse

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

Attributs

Description

Fournit l'accès aux caractéristiques secondaires (attributs) de chaque appareil dans BlueCold.

URL

Pour récupérer les attributs d'un appareil :

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

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

Pour récupérer les attributs d'un asset :

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

Paramètres

Paramètre	Description
`bluecold_id`	Identificateur interne unique de l'appareil, spécifique à BlueCold. Voir section 5.1. Note : cet identificateur n'est ni le NOM ni l'ADRESSE MAC.
`attribute_keys`	Noms des champs à récupérer, séparés par des virgules. Exemple : `lastCalibrationDate,nextCalibrationDate`

Réponse

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

Relations

Cette API permet de récupérer l'asset contenant l'appareil courant (voir exemple de workflow).

URL

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

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

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

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

Paramètres

Paramètre	Description
`bluecold_id_sensor`	Identificateur interne unique de l'appareil dont l'asset associé est recherché. Note : cet identificateur n'est ni le NOM ni l'ADRESSE MAC.
`bluecold_id_asset`	Identificateur interne unique de l'asset dont les appareils associés sont listés. Note : cet identificateur n'est ni le NOM ni l'ADRESSE MAC.

Réponse

Réponse pour fromType=DEVICE (asset contenant l'appareil) :

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

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

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

Données historiques (timeseries) par client / par asset

Description

Note : Utiliser ces endpoints pour l'ingestion de données à grande échelle

Le processus fonctionne en mode asynchrone : vous initiez une requête d'export, vérifiez périodiquement son statut, puis téléchargez le fichier CSV généré.

Architecture du flux

Requête d'export                    Polling du statut            Téléchargement
(par client ou par asset) ──────→  (5→15 min poll) ───────→  (CSV downloadUri)
      ↓                                ↓                           ↓
   Job créé                      Attend COMPLETED             Fichier récupéré
   → jobId + statusUrl             ou FAILED                 → Parse + Ingest

Cycle complet :

Initialiser un export (client ou asset)
Attendre que le job se termine (status = COMPLETED ou FAILED)
Télécharger et traiter le fichier CSV

Initier un export pour tous les appareils d'un client

Endpoint : POST /api/custom/customer/{customerId}/devices/telemetry/export

Paramètres de requête :

Paramètre	Type	Obligatoire	Description
`telemetryKey`	string	✅	Clé de télémétrie à exporter (une seule par requête)
`startTs`	number	✅	Timestamp de début, en millisecondes
`endTs`	number	✅	Timestamp de fin, en millisecondes
`fetchSubCustomerDevices`	boolean	❌	Si `true`, inclut les appareils des clients enfants (défaut : `false`)

Contraintes :

La fenêtre temporelle (endTs - startTs) ne peut pas dépasser 30 minutes
Une seule telemetryKey par requête (ex. : sensorValue_received)

Réponse (200 OK) :

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "statusUrl": "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440000"
}

Exemple cURL :

curl -X POST "https://<base_url>/api/custom/customer/bfd9c220-ad9c-4649-8063-c1c612f8bd60/devices/telemetry/export?telemetryKey=sensorValue_received&startTs=1234567890000&endTs=1234568490000"

Initier un export pour tous les appareils contenus dans un asset

Endpoint : POST /api/custom/asset/{assetId}/devices/telemetry/export

Paramètres de requête :

Paramètre	Type	Obligatoire	Description
`telemetryKey`	string	✅	Clé de télémétrie à exporter
`startTs`	number	✅	Timestamp de début, en millisecondes
`endTs`	number	✅	Timestamp de fin, en millisecondes

Contraintes :

L'asset doit appartenir au client courant ou à l'un de ses clients secondaires
Seuls les appareils ayant une relation Contains (To) avec l'asset seront inclus
Même fenêtre maximale de 30 minutes

Réponse (200 OK) :

{
  "jobId": "550e8400-e29b-41d4-a716-446655440001",
  "statusUrl": "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440001"
}

Exemple cURL :

curl -X POST "https://<base_url>/api/custom/asset/6b26482f-04bd-476d-8b7c-bf138cd483d5/devices/telemetry/export?telemetryKey=sensorValue_received&startTs=1234567890000&endTs=1234568490000"

Vérifier le statut d'un job d'export

Endpoint : GET /api/custom/telemetry/export/{jobId}

Paramètres :

Paramètre	Type	Description
`jobId`	string	UUID retourné lors de l'initialisation

Réponse (200 OK) :

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "createdAt": 1783497112000,
  "completedAt": null,
  "rowCount": null,
  "error": null,
  "telemetryKey": "sensorValue_received",
  "downloadUrl": "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440000/file"
}

Valeurs possibles de status :

PENDING – Job en cours de traitement
COMPLETED – Export terminé avec succès, rowCount contient le nombre de points de données
FAILED – Erreur lors de l'export, error contient le message d'erreur

Exemple cURL :

curl -X GET "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440000"

Télécharger le fichier d'export

Endpoint : GET /api/custom/telemetry/export/{jobId}/file

Paramètres :

Paramètre	Type	Description
`jobId`	string	UUID du job d'export (depuis la réponse de statut)

Réponse :

Content-Type: text/csv
Body: Fichier CSV avec les colonnes deviceId;ts;value

⚠️ Important : Ne téléchargez que si status == "COMPLETED"

Exemple cURL :

curl -X GET "https://<base_url>/api/custom/telemetry/export/550e8400-e29b-41d4-a716-446655440000/file" \
  -o telemetry_export.csv

Format du fichier CSV exporté

Le fichier utilise le point-virgule ; comme séparateur (par défaut).

Structure :

deviceId;ts;value

Colonnes :

Colonne	Type	Description
`deviceId`	string	ID interne de l'appareil dans BlueCold
`ts`	number	Timestamp UNIX en millisecondes
`value`	mixed	Valeur scalaire ou objet JSON (ex. : `{"type":"temp","value":15.17}`)

Exemple :

deviceId;ts;value
dde95d0-752c-11f1-8ba9-137c6080ee3d;1783410434081;"{""type"":""temperature_minidatalogger"",""value"":15.17}"
dde95d0-752c-11f1-8ba9-137c6080ee3d;1783410448838;"{""type"":""temperature_minidatalogger"",""value"":15.21}"

Notes :

Les valeurs JSON complexes sont sérialisées en tant que strings
Les timestamps sont toujours en millisecondes (multiplier par 1000 si les secondes sont nécessaires)

Informations générales​

Authentification​

Obtenir un token d'authentification​

Rafraîchir un token existant​

Durées de validité par défaut​

Concepts clé​

Description du format de stockage​

Hiérarchie client​

Liste des champs disponibles via l'API​

Timestamps des données de capteur​

Référence API​

Liste des appareils (capteurs et passerelles)​

Description​

URL​

Paramètres​

Réponse​

Liste des assets​

Description​

URL​

Paramètres​

Réponse​

Données historiques (timeseries) par appareil​

Description​

URL​

Paramètres​

Réponse​

Attributs​

Description​

URL​

Paramètres​

Réponse​

Relations​

URL​

Paramètres​

Réponse​

Données historiques (timeseries) par client / par asset​

Description​

Architecture du flux​

Initier un export pour tous les appareils d'un client​

Initier un export pour tous les appareils contenus dans un asset​

Vérifier le statut d'un job d'export​

Télécharger le fichier d'export​

Format du fichier CSV exporté​

Informations générales

Authentification

Obtenir un token d'authentification

Rafraîchir un token existant

Durées de validité par défaut

Concepts clé

Description du format de stockage

Hiérarchie client

Liste des champs disponibles via l'API

Timestamps des données de capteur

Référence API

Liste des appareils (capteurs et passerelles)

Description

URL

Paramètres

Réponse

Liste des assets

Description

URL

Paramètres

Réponse

Données historiques (timeseries) par appareil

Description

URL

Paramètres

Réponse

Attributs

Description

URL

Paramètres

Réponse

Relations

URL

Paramètres

Réponse

Données historiques (timeseries) par client / par asset

Description

Architecture du flux

Initier un export pour tous les appareils d'un client

Initier un export pour tous les appareils contenus dans un asset

Vérifier le statut d'un job d'export

Télécharger le fichier d'export

Format du fichier CSV exporté