Documentation API
Guide de référence des API
Ce guide présente les principales API à utiliser lors de la création d'une connexion entre un logiciel externe et SIGSCAN.
Plus de détails sur chaque API peuvent être trouvés à l'adresse suivante :
https://app.sigscan.eu/swagger-ui.html
Architecture globale
Organization: Une organisation est la plus grande unité Sigscan qui contient toutes les données du client. Les clients peuvent avoir une ou plusieurs organisations dédiées hébergées sur la même instance Sigscan (type une machine virtuelle).
Beacon: Également appelée "tag", la beacon est un dispositif IOT suivi dans le système de localisation en temps réel Sigscan. Il utilise le plus souvent la technologie Bluetooth LE pour signaler sa présence.
Sigscan Object: Il s'agit d'un objet physique que nous voulons suivre dans un environnement intérieur. Lorsqu'une balise est associée à un objet, la position de la balise devient la position de l'objet à cet instant. De cette manière, nous obtenons la position de l'objet uniquement lorsqu'il est associé à une balise dans le logiciel Sigscan.
Object Type: Les objets Sigscan peuvent être classés par type. Le concept de type d'objet permet de regrouper les objets en fonction de leurs propriétés qui sont reflétées dans les champs personnalisés.
Custom Field/Custom Values: Les champs personnalisés sont créés indépendamment et peuvent ensuite être attachés à un type d'objet. Différents types d'objets peuvent partager un ou plusieurs champs personnalisés. L'objet Sigscan d'un type d'objet spécifique hérite automatiquement de tous les champs personnalisés attachés au type d'objet.
Les champs personnalisés d'un objet peuvent être remplis avec des valeurs qui correspondent à des valeurs personnalisées dans la terminologie Sigscan. Le type de données qu'un champ personnalisé peut accepter (nombre, chaîne de caractères, date, booléen, liste) est défini lors de sa création.
Authentification
Avant d'appeler une API, vous devez vous authentifier. Le mécanisme d'authentification de SIGSCAN est basé sur un JWT Token.
Method | POST |
Endpoint | /api/login |
Headers | Accept: application/json Content-Type: application/json |
Body (as HTTP POST Data) | { "username": "[username]", "password": "[password]" } |
Response | JWT Authentication Token |
Exemple:
curl -X POST https://demo.sigscan-industry.com/api/login -d '{"username": "john", "password": "johnpwd"}'
La réponse renvoyée par le serveur inclut le JWT Token dans l'en-tête HTPP Authorization. Ce Token doit être inclus dans l'en-tête HTTP de toute demande ultérieure, comme suit :
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiO…
Obtenez l'identifiant de votre organisation
L'identifiant de l'organisation sera requis dans la plupart des appels à l'API décrits ci-dessous dans ce document. Nous recommandons de l'obtenir juste après l'authentification pour plus de commodité.
Method | GET |
Endpoint | /api/organizations |
Headers | Authorization : Bearer [AuthToken] |
Request parameters | page=[pageNumber] size=[pageSize] sort=[fieldName],[ASC|DESC] name=[organizationName] |
Response | Paginated Organizations |
Exemple:
curl -H 'Authorization: Bearer [AuthToken]' -X GET https://demo.sigscan-industry.com/api/organizations?page=0&size=100&name=SIGC
{
"content": [
{
"id": 59,
"name": "SIGSCAN"
}
],
"pageable": {
"sort": {
"empty": false,
"sorted": true,
"unsorted": false
},
"offset": 0,
"pageNumber": 0,
"pageSize": 100,
"paged": true,
"unpaged": false
},
"last": true,
"totalPages": 1,
"totalElements": 1,
"size": 100,
"number": 0,
"sort": {
"empty": false,
"sorted": true,
"unsorted": false
},
"first": true,
"numberOfElements": 1,
"empty": false
}
Gestion des objets
Créer un objet
Method | POST |
Endpoint | /api/objects |
Headers | Authorization: Bearer [AuthToken] Content-Type: application/json |
Body (as HTTP POST Data) | { "name": "[objectName]", "organization": { "id": [Organization ID] }, "type": { "id": [object_type ID] } } |
Response | Object created (HTTP OK 200) |
Example:
curl -H 'Authorization: Bearer [AuthToken]' -X POST https://demo.sigscan-industry.com/api/objects -d '{"name": "My object", "organization": {"id": 36}, “type”: {“id”: 54}}'
{
"id": 1206,
"organization": {
"id": 36,
"name": "SIGSCAN"
},
"name": " My object ",
"type": {
"id": 54,
"name": "Default",
"customFields": [
],
}
}
Récupérer un objet
Method | GET |
Endpoint | /api/objects/[objectId] |
Headers | Authorization : Bearer [AuthToken] |
Response | Object requested |
Example:
curl -H 'Authorization: Bearer [AuthToken]'
-X GET https://demo.sigscan-industry.com/api/objects/1206
{
"id": 1206,
"organization": {
"id": 36,
"name": "SIGSCAN"
},
"name": " My object ",
"type": {
"id": 54,
"name": "Default",
"customFields": [
],
}
}
Obtenir une liste d'objets
Method | GET |
Endpoint | /api/objects |
Headers | Authorization : Bearer [AuthToken] |
Parameters | page=[pageNumber] size=[pageSize] sort=[fieldName],[ASC|DESC]
organizationId=[organizationId] name=[organization Name] associated=[true|false] inSight=[true|false] area=[area Name] buildingId=[building ID] typeName=[type Name] associatedName=[associated beacon name]
|
Response | Paginated objects |
Les paramètres page et taille sont spécifiques aux résultats paginés et sont facultatifs.
Exemple:
curl -H 'Authorization: Bearer [AuthToken]' -X GET https://demo.sigscan-industry.com/api/objects?organizationId=36?page=0&size=4
{
"content": [
{
"id": 1020,
"name": "99710",
},
{
"id": 1024,
"name": "99629",
},
{
"id": 845,
"name": "99378",
}
],
"pageable": {
"sort": {
"empty": false,
"sorted": true,
"unsorted": false
},
"offset": 0,
"pageNumber": 0,
"pageSize": 4,
"paged": true,
"unpaged": false
},
"last": false,
"totalPages": 4,
"totalElements": 14,
"size": 4,
"number": 0,
"sort": {
"empty": false,
"sorted": true,
"unsorted": false
},
"first": true,
"numberOfElements": 4,
"empty": false
}
Mise à jour d'un objet
Method | PUT |
Endpoint | /api/objects/[objectId] |
Headers | Authorization : Bearer [AuthToken] Accept : application/json Content-Type : application/json |
Body | { "name": "[objectName]", } |
Response | Updated object |
Exemple:
curl -H 'Authorization: Bearer [AuthToken]' -X PUT https://demo.sigscan-industry.com/api/objects/229 -d '{"name": "name updated", "organization": {"id": 36}}'
Supprimer un objet
Method | DELETE |
Endpoint | /api/objects/[objectId] |
Headers | Authorization : Bearer [AuthToken] |
Body | None |
Response | None |
Exemple:
curl -H 'Authorization: Bearer [AuthToken]' -X DELETE https://demo.sigscan-industry.com/api/objects/229
Obtenir toutes les tags de l'organisation
Method | GET |
Endpoint | /api/beacons?organizationId=[organizationId] &page=[pageNumber]&size=[pageSize] |
Headers | Authorization : Bearer [AuthToken] |
Body (as HTTP POST Data) |
|
Response | Paginated beacons |
Note : Les paramètres page et taille sont spécifiques aux résultats paginés et sont facultatifs.
Exemple:
curl -H 'Authorization: Bearer [AuthToken]' -X GET https://demo.sigscan-industry.com/api/beacons?organizationId=36
{
"content":[
{
"id":1720,
"macAddress":"AC:23:3F:EB:12:D9",
"identifier":"AC:23:3F:EB:12:D9",
"beaconSoftware":"BLE_EDDYSTONE",
"beaconModel":"MINI_BEACON",
"name":"Timbre 12D9",
"organization":{},
"latestPosition":{},
"latestTemperature":{},
"latestVoltage":{},
"disabled":false,
"associatedSigscanObject":{},
"lastSeenDate":1669720539513
},...
],
"pageable":{},
"totalElements":102,
"totalPages":6,
"last":false,
"size":20,
"number":0,
"sort":{},
"numberOfElements":20,
"first":true,
"empty":false
}
Association d’un tag à un objet
Associer
Pour associer un beacon à un objet, il faut mettre à jour l'objet Sigscan et fournir le paramètre associatedBeacon contenant des données de beacon valides.
Method | PUT |
Endpoint | /api/objects/[objectId] |
Headers | Authorization : Bearer [AuthToken] Accept : application/json Content-Type : application/json |
Body (as HTTP POST Data) | { "organization": { "id" : [OrganizationId] }, "associatedBeacon" : { "id" : [beaconId] } } |
Response | Updated object |
Exemple:
Curl -H 'Authorization: Bearer [AuthToken]' -X PUT https://demo.sigscan-industry.com/api/objects/231 -d '{"organization": {"id": 36}, "associatedBeacon": {"id": 254}}'
Dissocier
Pour dissocier un beacon d'un objet auquel elle est associée, il faut mettre à jour l'objet Sigscan et fournir le paramètre associatedBeacon avec id=0.
Method | PUT |
Endpoint | /api/objects/[objectId] |
Headers | Authorization : Bearer [AuthToken] Accept : application/json Content-Type : application/json |
Body (as HTTP POST Data) | { "organization": { "id" : [OrganizationId] }, "associatedBeacon" : { "id" : 0 } } |
Response | Updated object |
Exemple:
curl -H 'Authorization: Bearer [AuthToken]' -X PUT https://demo.sigscan-industry.com/api/objects/231 -d '{"organization": {"id": 36}, "associatedBeacon": {"id": 0}}'
Récupérer la dernière position de l'objet
Structure du positionement Sigscan
La position d'un beacon/objet Sigscan est composée de trois éléments : le site, l'édifice et l'étage. La position Sigscan est créée pour un étage donné qui fait partie d'un bâtiment situé sur le site d'une organisation donnée.
Utiliser les API REST
Pour un objet associé à un becon et dont la position est déterminée, la réponse renvoyée lors de l'appel API GET /api/objects/ ou GET /api/objects/[id] comprendra un champ appelé latestPosition.
Exemple:
curl -H 'Authorization: Bearer [AuthToken]'
-X GET https://demo.sigscan-industry.com/api/objects/1206
{
"id": 1206,
"organization": {
"id": 36,
"name": "SIGSCAN"
},
"name": " My object ",
"type": {
"id": 54,
"name": "Default",
"customFields": [],
},
"associatedBeacon": {"id":737,...},
"latestPosition": {
"sigscanObject":{
"id":1206
},
"beacon":{
"id":941
},
"positionX":2467.4917412133414,
"positionY":1195.7007648831443,
"positionPrecision":1.0,
"creationDate":1677680955587,
"lastUpdateDate":1677685291055,
"areaName"*:"CONTROLE FINAL",
"floor":{
"id":2,
"name":"ATELIER ELECTRONIQUE",
"xOrigin":0.0,
"yOrigin":0.0,
"xRatio":1.0,
"yRatio":1.0,
"edifice":{
"id":3,
"name":"Electronique",
"site":{
"id":13,
"name":"Site de Toulouse",
"organization":{},
"address":"20 rue Hermes",
"latitude":43.5492284,
"longitude":1.4861919,
"plan":{
"id":438,
"filename":"Image1.png",
"size":2004319,
"contentType":"image/png"
}
},
"positionX":1281.173838209983,
"positionY":716.739323419515
}
},
"area":{
"name":"CONTROLE FINAL"
},
"building"**:{}
},
"type":{},
" customValues":[]
}
- “areaName” field is deprecated. The field “area” -> “name” should be used instead
** - “building” field is deprecated. The “site” -> “edifice” -> “floor” architecture should be used instead
Certains champs de latestPosition et leur signification sont énumérés ci-dessous :
“positionX” - corresponds to the X coordinate of the Gateway on the floor plan that reported this position
“positionY” - corresponds to the Y coordinate of the Gateway on the floor plan that reported this position
"positionPrecision" - corresponds to the Gataway’s range
"creationDate" - corresponds to the timestamp of the position creation
"lastUpdateDate" - corresponds to the timestamp of the latest update of this position
"area" -> "name" - corresponds to the name of the zone where the beacon/object was detected
"edifice” -> "positionX"/"positionY" - correspond to the edifice coordinate on the site plan
Utilisation de Websocket
Si vous avez besoin d'obtenir des mises à jour de position en temps réel, SIGSCAN met en œuvre le protocole HTTPS WebSocket (WSS) + le protocole STOMP pour ce faire.
STOMP, utilisé au-dessus du canal WebSocket, utilise un mécanisme de "sujets" auxquels l'application doit s'abonner pour obtenir des mises à jour en temps réel. Voir https://stomp.github.io/ pour plus de détails sur le protocole STOMP.
Pour recevoir les dernières mises à jour des positions, l'application cliente doit s'abonner à chaque sujet "beacon associate".
Tout d'abord, la connexion WebSocket doit être établie. La connexion ne peut être établie que si un jeton d'authentification valide est fourni. Le jeton d'authentification doit être fourni comme suit :
wss://demo.sigscan-industry.com/ws?[authToken]
Une fois connecté, vous devez vous abonner au thème que vous souhaitez écouter, en utilisant le protocole STOMP.
SUBSCRIBE /organization/[organizationId]/beacons/[beaconId]/positions
En retour, le serveur enverra des mises à jour de position. Vous trouverez ci-dessous une capture d'écran provenant de l'interface Web SIGSCAN et montrant les données de mise à jour de la position provenant du serveur :
MESSAGE
destination:/organization/58/beacons/2601/positions
content-type:application/json
subscription:sub-25
message-id:a56d9e96-7ca9-4717-e287-ba3f327263e4-340501
content-length:1186
{
"wsMessagetype":"UPDATE",
"beaconPositionJson":{
"sigscanObject":{},
"beacon":{},
"positionX":152.42667496370046,
"positionY":299.3356199476261,
"positionPrecision":5.0,
"creationDate":1677945947752,
"lastUpdateDate":1678092644694,
"areaName":"Entrée Bureaux Dev",
"floor":{},
"area":{},
"building":{}
}
}
Récupérer les positions pour une période donnée
Il est possible de récupérer les postes de tous les objets d'une organisation pour une période donnée définie par les paramètres startDate et endDate.
Exemple:
curl -H 'Authorization: Bearer [AuthToken]'