API de développement : créez et gérez votre application

• Objectif
• Exigences
• Démarrage rapide pour l’authentification
• Configuration de l’application
• Modèle de poignée de main et d’authentification
• Interface intégrée (optionnelle)
• Bonnes pratiques (sécurité + exploitabilité)
• Liens connexes
   

Objectif

Exigences

Vous avez besoin de:

• Un utilisateur de la plateforme avec des permissions superadmin pour enregistrer l’application.
• Un serveur backend avec une URL HTTPS publique et la capacité de gérer des requêtes HTTP.

• Des connaissances de base en REST, en-têtes HTTP et JSON.

   

Démarrage rapide pour l'authentification

Si vous n'avez pas besoin de développer une interface utilisateur qui interagit avec la plateforme et que vous avez simplement besoin d'un jeton pour obtenir des données via l'API, vous pouvez ignorer les sections Configuration de l'application et Modèle de poignée de main et d'authentification, et installer directement l'application Access Token.

Ce jeton dispose de permissions en lecture seule. Si vous avez besoin d'autorisations supplémentaires, suivez les instructions de configuration de l'application et de poignée de main.

App set-up

Register your app (Organisation management → Market Apps)

• From the top-right user menu, open Organisation management.
• Go to Market Apps and click New Market App.
• Fill in:
  • General info (name, description, icon, visibility private/public).
  • URLs: Install URL (required), optional cleanup/uninstall URL; optional embedded UI views/reports/datasources.
  • Permissions: grant the read/write resource areas your app will need (missing permissions can block access).
• Save the app and record App ID and App Secret (needed for token exchange on install). 

Configuration de l'application

Inscrivez votre application (Gestion de l'organisation → Applications Market).

Depuis le menu utilisateur en haut à droite, ouvrez Gestion de l'organisation.

Allez dans Applications Market et cliquez sur Nouvelle application Market.

Remplissez :

• Informations générales (nom, description, icône, visibilité privée/publique).
• URL : URL d’installation (obligatoire), URL de nettoyage/désinstallation optionnelle ; vues/rapports/sources de données UI intégrée optionnelles.
• Permissions : accordez les zones de ressources en lecture/écriture dont votre application aura besoin (des permissions manquantes peuvent bloquer l’accès).

Enregistrez l’application et notez l’App ID et le App Secret (nécessaires pour l’échange de jeton lors de l’installation).

Installez votre application dans un compte (Apps Market)

• Dans le compte cible, ouvrez le Apps Market et installez votre application

Modèle de poignée de main et d’authentification

Lorsqu’un utilisateur installe votre application:

• La plateforme appelle votre URL d’installation avec dep_id et temp_token.
• Votre backend échange le temp_token contre un jeton permanent utilisé dans l’API v3 (x-dexcell-token).
• Votre application renvoie HTTP 200 OK pour finaliser l’installation.

curl --request GET \
  --url "https://api.dexma.com/v3/locations" \
  --header "x-dexcell-token: <PERMANENT_TOKEN>"

Limites de taux

Interface utilisateur intégrée (optionnelle)

Il est possible d’exposer une interface utilisateur dans différentes sections de la plateforme, y compris Tableaux de bord, section Analyses, Rapports et Source de données.

La session de la plateforme expose des informations que vous pouvez utiliser pour construire ces interfaces, incluant:

• account
• current_location
• location_tags
• locations_below
• user (y compris le rôle de l’utilisateur et la locale)
• custom domain

Bonnes pratiques (sécurité + exploitabilité)

Exemples d'appels

Obtenir la liste de tous mes emplacements

• url: https://api.dexcell.com/v3/locations
• headers: x-dexcell-token

Obtenir des informations spécifiques sur un emplacement

• url: https://api.dexcell.com/v3/locations/XXX
• headers: x-dexcell-token 

Obtenir des relevés

• url:  http://api.dexcell.com/v3/readings?device_id=XXXXX&operation=DELTA&parameter_key=EACTIVE&resolution=D&from=2015-05-08T00:00:00&to=2015-05-09T23:59:59​
• parameters:
  • device_id: obtenu via  devices. Ne correspond pas à la clé de l’appareil..
  • parameter key: check parameters list et introduction to parameters
  • operation: 
    • for instant readings: RAW
    • for time interval readings:
      • DELTA for accumulated nature parameter (energy, volume, mass, ...)
      • AVG, MAX, MIN for instantaneous nature parameters (power, temperature, humidity, ...)
  • resolution:
    • if operation = RAW, then resolution must be = B
    • if operation != RAW, then resolution can be any of: FM, TM, QH, HH, H, D, M
  • from / to: YYYY-MM-DDThh:mm:ss (in local time)
• headers: x-dexcell-token 

Liens associés

• Datasource Type Apps: Build your data connector
• Using the insertion API to introduce data in a gateway
• Access Token App
• APIv3 - Developers portal