Web Services

BEACON Web Services

Bienvenue dans les pages de documentation de l’API BEACON Web Services. Ces pages s’adressent aux développeurs logiciels qui souhaitent comprendre les capacités de l’API BEACON Web Services et apprendre comment l’utiliser pour étendre BEACON et l’intégrer à des systèmes de facturation et à d’autres systèmes de gestion des données.

(Dernière mise à jour le 22 août 2017)
L’API BEACON Web Services se compose de différentes API : l’API BEACON Data Exchange Import et les API BEACON Export Data Service v1 et v2. La documentation explique comment authentifier et obtenir un accès aux points de terminaison de l’API, comment créer des requêtes auprès des différentes méthodes d’API et comment interpréter les résultats des réponses de l’API.

En appelant différentes fonctions de BEACON via le code, vous pouvez étendre le système et créer des rapports personnalisés et d’autres extensions pour répondre à des exigences spécifiques.

Cas d’utilisation

L’API BEACON Data Exchange Import facilite la synchronisation automatique du système entre les systèmes de facturation et d’information client et BEACON.

L’API BEACON Export Data Service facilite l’exportation automatique des relevés de débit et de facturation depuis BEACON vers les systèmes de facturation.

Meilleures pratiques

BEACON Web Services utilise l’authentification d’accès HTTP de base pour fournir à vos applications un accès sécurisé aux données accessibles à votre service. Nous vous recommandons de configurer un compte e-mail, un nom d’utilisateur BEACON et un mot de passe uniques pour accéder à BEACON Web Services. Le fait de disposer d’identifiants uniques pour chaque rapport basé dans BEACON Web Services vous permet de créer, par exemple, des rapports de consommation personnalisés et d’autres analyses.

Exemple d’e-mail et de nom d’utilisateur :
E-mail : nomdevotreservice.eds@mail.com
Nom d’utilisateur : Rapport relevés de facturation EDS

Test de BEACON Web Services

Les exemples repris dans notre documentation sont des déclarations cURL. Pour tester ces déclarations sans créer une application Web complète, exécutez-les dans un outil de ligne de commande comme le Terminal sur un Mac ou l’invite de commande dans Windows. Vous pouvez également les exécuter dans un navigateur à l’aide d’un plug-in comme Postman pour GoogleMD Chrome.

Mac OS X prend en charge cURL en mode natif. Si vous utilisez Windows, vous devrez télécharger et installer cURL ainsi qu’un certificat numérique qui permet à cURL de se connecter de manière sécurisée à BEACON à l’aide d’un protocole SSL.

Méthodes cURL

Points de terminaison d’API

Pour tous les services à l’exception de ceux situés au Canada, l’accès à tous les points de terminaison d’API se fait à l’aide de l’URL de service de l’API BEACON :
https://api.beaconama.net

Pour les services situés au Canada, l’accès aux points de terminaison d’API se fait à l’aide de l’URL de service de l’API BEACON :
https://api.beaconama.ca

Conseils de programmation

Lorsque vous utilisez le plug-in Postman pour Google Chrome, définissez le bouton radio du corps sur

x-www-form-urlencoded

et utilisez l’en-tête suivant avec vos requêtes :

Content-Type: application/x-www-form-urlencoded

À moins d’utiliser cURL, vous devez transférer des paramètres de requête, par exemple, route=0113, comme lignes de valeurs clés dans le corps du POST.

Par exemple, transférez

route=0366&date=2015-08-23&tolerance=72

dans le corps du POST sous la forme

route=0366
date=2015-08-23
tolerance=72

Lorsque vous utilisez cURL, il transforme par défaut les paramètres de requête en lignes de valeurs clés dans le contenu du POST.

Ne transférez pas le –location-trusted flag si vous utilisez cURL. Cet indicateur envoie des en-têtes d’autorisation inutiles qui produisent une erreur 400. Cela vaut lorsque vous utilisez l’objet Microsoft WinHttpRequest COM ou travaillez dans d’autres langages, comme Visual Basic, C#, C++, etc.

Lorsque vous utilisez SOAP UI, après avoir configuré l’URL pour votre projet REST et avant de passer au test de l’API :

1. Sélectionnez l’onglet Authentication & Security-related settings (Authentification et paramètres liés à la sécurité), saisissez votre nom d’utilisateur et votre mot de passe BEACON.
2. Saisissez BEACON AMA comme domaine et sélectionnez Authenticate Pre-emptively (Authentifier préventivement).
   
3. Sélectionnez l’onglet Header (En-tête) et cliquez sur + pour ajouter un en-tête.
   
4. Dans la boîte de dialogue, saisissez Content-Type et appuyez sur Entrée.
   
5. Dans le champ Value (Valeur), saisissez : application/x-www-form-urlencoded.
   
6. Dans Attachment>Request>Media Type (Pièce jointe>Requête>Type de média), cochez Post QueryString.
   
7. Passez au test de l’API.

Limites de débit

Les API BEACON Web Services sont limitées en débit. Un nombre limité d’appels est autorisé par service pour une période donnée. Le tableau ci-dessous indique les limites de débit par défaut. Badger Meter se réserve le droit d’ajuster la limite de débit à tout moment pour permettre à ses API d’importation et d’exportation de fournir une qualité de service élevée à tous nous clients.

Les limites de débit utilisent des fenêtres temporelles glissantes. Par exemple, si le tout premier appel vers l’API BEACON Export Data Service a lieu à 11:00:00 le 17 mai 2016, vous pouvez effectuer x appels supplémentaires jusqu’à 10:59:59 le 18 mai 2016. De même, si vous démarrez une importation de données à 11:15:23, vous pouvez effectuer x appels supplémentaires jusqu’à 11:16:22.

Le dépassement de votre limite de débit entraîne un code d’erreur HTTP 429 Too Many Requests ainsi qu’un message indiquant le nombre de secondes restantes avant que la requête puisse réussir.

Le système peut également limiter ou ralentir les appels d’API lorsque, par exemple, il détecte une augmentation importante des requêtes, ce qui peut indiquer une attaque par déni de service.

Contactez votre représentant de l’assistance clientèle de Badger Meter pour déterminer une limite de débit qui convienne à vos besoins. Des frais supplémentaires peuvent s’appliquer.

Mise en route

1. Les utilisateurs administrateurs avec des identifiants de connexion BEACON d’origine (un nom d’utilisateur et un mot de passe) ont accès à l’API.
2. Lisez la documentation pour vous familiariser avec les capacités de l’API et déterminer si elle convient pour votre projet.
3. Si vous n’en disposez pas encore, demandez une invitation à utiliser BEACON avec un accès de niveau administrateur et créez un nom d’utilisateur et un mot de passe. Vous aurez besoin de ces identifiants pour vous authentifier et fournir à vos applications un accès sécurisé à toutes les données disponibles pour votre compte.
4. Créez votre application.
5. Déployez votre application.

Assistance

Une fois votre configuration effectuée, Badger Meter vous fournira des coordonnées d’assistance.

Pages de documentation

• API de zone commune de services
• API d’importation
• Cas d’utilisation d’API d’import d’échange de données
• Exemples de cURL de l’API d’importation
• Présentation d’Export Data Services
• API Export Data Service v1
• Aperçu de l’API Export Data Service v2
• Exemples de scripts de service d’exportation de données