Servicios web

Servicios web de BEACON

Bienvenido a las páginas de documentación de la interfaz de programación de aplicaciones (Application Programming Interface, API) de servicios web de BEACON. Estas páginas son para desarrolladores de software que desean comprender las capacidades de la API de servicios web de BEACON y aprender a usarla para extender e integrar BEACON con sistemas de facturación y otros sistemas de administración.

(Última actualización el 22 de agosto de 2017)
La API de servicios web de BEACON consta de diferentes API: la API de importación de Data Exchange de BEACON y la API del Export Data Service de BEACON v1 y v2. La documentación explica cómo autenticarse y obtener acceso a las terminales de la API, cómo crear solicitudes a los diversos métodos de la API y cómo interpretar los resultados de las respuestas de la API.

Al llamar a varias funciones de BEACON a través del código, puede ampliar el sistema y
crear informes personalizados y otras extensiones para lograr requisitos específicos.

Exportar-API

Casos de uso

La API de importación de Data Exchange de BEACON facilita la sincronización automática del sistema entre los sistemas de facturación y de información del cliente y BEACON.

La API del Export Data Service de BEACON facilita el flujo automático y las exportaciones de lectura de facturación de BEACON a los sistemas de facturación.

Prácticas recomendadas

Los servicios web de BEACON utilizan la autenticación de acceso básico HTTP a fin de brindar a sus aplicaciones acceso seguro a los datos disponibles para su empresa de servicios públicos. Le recomendamos que configure una cuenta de correo electrónico, un nombre de usuario y una contraseña de BEACON únicos para acceder a los servicios web de BEACON. Tener credenciales únicas para cada informe basado en los servicios web de BEACON le permite crear, por ejemplo, informes de uso personalizado y otros análisis.

Ejemplo de correo electrónico y nombre de usuario:
Correo electrónico: yourutilityname.eds@mail.com
Nombre de usuario: Informe de lecturas de facturación del Export Data Service (EDS)

Prueba de conducción de los servicios web de BEACON

Los ejemplos de nuestra documentación son declaraciones cURL. Para probar estas declaraciones sin crear una aplicación web completa, ejecútelas en una herramienta de línea de comandos como Terminal en una Mac o en la línea de comandos en Windows. También puede ejecutarlos en un navegador mediante un complemento como Postman para Google® Chrome.

Mac OS X admite cURL de forma nativa. Si utiliza Windows, deberá descargar e instalar cURL junto con un certificado digital que permite que cURL se conecte de forma segura a BEACON mediante el protocolo Secure Socket Layer (SSL).

Métodos cURL

Comando Qué hace
GET Realiza operaciones de solicitud «obteniendo» un localizador de recursos uniforme (Uniform Resource Locator, URL). En BEACON, GET se utiliza para solicitar listas, el estado de archivos e informes.
POST Realiza operaciones de solicitud para recuperar datos demasiado densos para incluirlos en un URL. En BEACON, POST se utiliza para exportar datos de facturación leídos e iniciar nuevos intercambios de archivos.
PUT Carga datos a un servidor HTTP. En BEACON, PUT se utiliza para proceder con una operación de importación después de que se acepta una ejecución en seco.

Terminales de API

Para todos los servicios públicos, excepto los de Canadá, se accede a todas las terminales de la API mediante el URL del servicio de la API de BEACON:
https://api.beaconama.net

Para las empresas de servicios públicos en Canadá, se accede a las terminales de la API mediante el URL de servicio de la API de BEACON:
https://api.beaconama.ca

Sugerencias de programación

Cuando utilice el complemento Postman para Google Chrome, configure el botón de opción Cuerpo en

x-www-form-urlencoded

Y use el siguiente encabezado con sus solicitudes:

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

A menos que esté utilizando cURL, debe pasar parámetros de consulta, p. ej. route=0113, como líneas de valor-clave en el cuerpo del POST.

Por ejemplo, pase

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

en el cuerpo de POST como

ruta = 0366
fecha = 2015-08-23
tolerancia = 72

Cuando se utiliza cURL, de forma predeterminada convierte los parámetros de consulta en líneas clave = valor en el contenido de POST.

No pase el indicador confiable de ubicación cuando utilice cURL. Este indicador envía encabezados de autorización innecesarios que dan como resultado un error 400. Esto es cierto cuando se utiliza el objeto COM WinHttpRequest de Microsoft o se trabaja en otros lenguajes, como Visual Basic, C #, C ++, etc.

Cuando utilice la interfaz de usuario (User Interface, UI) de SOAP, después de configurar el URL para su proyecto REST y antes de continuar con las pruebas de la API:

  1. Seleccione la pestaña Authentication & Security-related settings (Configuración relacionada con autenticación y seguridad), e ingrese su nombre de usuario y contraseña de BEACON.
  2. Ingrese Advanced Metering Analytics (AMA) de BEACON como el dominio y seleccione Authenticate Pre-emptively (Autenticar de forma preferente).Autenticación de UI de Soap
  3. Seleccione la pestaña Header (Encabezado) y haga clic en + para agregar un encabezado.+ encabezado 
  4. En el cuadro de diálogo, escriba: «Content-Type» y presione enter.Captura de pantalla 2016-02-26 a las 10.51.28 a. m.
  5. En el campo Value (Valor), escriba: application/x-www-form-urlencoded.Captura de pantalla 2016-02-26 a las 10.56.23 a. m.
  6. En Attachment>Request>Media Type (Archivo adjunto>Solicitud>Tipo de medio), marque Post QueryString (Publicar QueryString).Screen Shot 2016-03-16 at 1.19.07 PM.png
  7. Continúe probando la API.

 

Límites de tasa

Las API de servicios web de BEACON tienen una tasa limitada. Solo se permite una cierta cantidad de llamadas por empresa de servicio público en un periodo determinado. La siguiente tabla muestra los límites de tasa predeterminados. Badger Meter se reserva el derecho de ajustar el límite de tasa en cualquier momento para que sus API de importación y exportación brinden un servicio de alta calidad a todos nuestros clientes.

 

Límite de tasa Periodo
6 llamadas por 60 segundos
24 llamadas por 60 minutos
48 llamadas por 24 horas

 

Los límites de tasa utilizan ventanas flexibles de tiempo.
Por ejemplo, si la primera llamada a la API del Export Data Service de BEACON se produce a las 11:00:00 del 17 de mayo de 2016, puede realizar x llamadas más hasta las 10:59:59 del 18 de mayo de 2016. Del mismo modo, si inicia una importación de datos a las 11:15:23, podría realizar x llamadas más hasta las 11:16:22.

Superar su límite de tasa produce un código de error HTTP 429 Too Many Requests (HTTP 429 Demasiadas solicitudes) junto con un mensaje que incluye el tiempo restante en segundos hasta que la solicitud sea exitosa.

También es posible que el sistema limite o acelere las llamadas a la API cuando, por ejemplo, detecta un aumento brusco de solicitudes, lo que podría indicar un posible ataque de denegación de servicio.

Comuníquese con su representante de soporte de Badger Meter para determinar un límite de tasa que se adapte a sus necesidades. Pueden aplicarse cargos adicionales.

Introducción

  1. Comuníquese con su representante de soporte de Badger Meter para solicitar acceso a los servicios web de BEACON.
  2. Lea la documentación para familiarizarse con las capacidades de la API y determinar la idoneidad para su proyecto.
  3. Si aún no la tiene, solicite una invitación para usar BEACON con acceso de nivel de administrador, y cree un nombre de usuario y contraseña. Necesitará estas credenciales para autenticarse y proporcionar a sus aplicaciones acceso seguro a todos los datos disponibles en su cuenta.
  4. Cree su aplicación.
  5. Implemente su aplicación.

Soporte

Una vez que se haya configurado, Badger Meter le proporcionará la información de contacto de soporte.

Páginas de documentación

Get Support

Knowledge Base

User Guide
Follow via Email

Enter your email address to get new content notifications by email.

A %d blogueros les gusta esto: