API eedomus

De eedomus - Documentación

Contenido

Cómo hacer más cosas con la API eedomus

Introducción

La API eedomus le ofrece un abanico de funciones que le permiten manejar los datos de su cuenta eedomus. Puede consultar los datos de sus sensores así como controlar sus actuadores.

Con esta API en tiempo real, puede desarrollar aplicaciones para ampliar la posibilidades que le ofrece eedomus. Le recomendamos que sólo use URL's que figuran en esta página para sus desarrollos. De lo contrario, podrían dejar de funcionar en el futuro.

Las condiciones generales son de aplicación. El uso de la API eedomus es libre para un uso no comercial.

Se puede llamar al conjunto de funciones de la API a través de llamadas HTTP GET o HTTP POST.

Existen dos API's: la llamada API Cloud, ubicada en la plataforma y el servidor eedomus, y la API local, que se encuentra en el controlador eedomus. Le recomendamos que use preferentemente la API local en la medida de lo posible, entre otras cosas porque ésta no está sujeta a las limitaciones de la API Cloud en función del tipo de cuenta (Free o Premium).

Para solicitar sus credenciales para la API, revocarlas o acceder a la herramienta de ayuda para construir llamadas HTTP, conéctese al potal eedomus (secure.eedomus.com) y vaya a Configuración => Mi cuenta (el enlace que le llevará a la API aparece en la pestaña "Mi cuenta"). Las credenciales están disponibles para la cuenta principal y las cuentas secundarias sin restricciones.

Sintaxis de las llamadas HTTP 

https://api.eedomus.com/[request_type]?action=[service.action]&[parameters]

Donde:

  • [request_type] es el tipo de llamada HTTP
  • [service.action] es la acción que deberá ejecutarse para el servicio determinado
  • [parameters] son parámetros, obligatorios u opcionales, relativos al servicio en cuestión.

Sintaxis de las respuestas

Las repuestas a las llamadas HTTP se hacen en formato JSON. 

{
  success: 1
}


El campo success es obligatorio. Arroja el valor 1 si la llamada HTTP ha funcionado correctamente.

En caso contrario, arroja el valor 0 así como comentarios complementarios en el campo body. 

{
   success: 0,
   body:
   {
     error_code: 1,
     error_msg: "Authentification error."
   }
}

La lista de códigos de error (error_code) está disponible aquí.

Autenticación

Todas las llamadas HTTP deben estar vinculadas con un usuario eedomus válido previamente creado en https://secure.eedomus.com.

La autenticación para la API es distinta de la que se usa en el portal eedomus. En el portal, el proceso de autenticación está basado en un usuario y una contraseña. Con la API eedomus, la autenticación está basada en un api_user y un api_secret que el usuario puede solicitar y revocar en cualquier momento en el apartado "Mi cuenta" del portal eedomus.

Por razones de seguridad, api_user/api_secret se envían sólo por mail. Para recuperarlos, identifíquese en https://secure.eedomus.com, vaya a Configuración / Mi cuenta / Parámetros y haga clic en Credenciales para la API -> Enviar.

Protocolo

La API eedomus usa preferentemente el protocolo HTTPS (los datos que se intercambian están cifrados), pero puede autorizar el uso de HTTP en la opciones de su cuenta.

API local (LAN)

Las funciones de la API eedomus disponibles en el servidor eedomus van estando disponibles también, poco a poco, en el controlador eedomus.

Para usar la API en modo LAN, lo único que debe hacer es sustituir api.eedomus.com por IP_DE_SU_CONTROLADOR/api


A día de hoy, la funciones de la API disponibles en modo LAN son las siguientes:


Ejemplo: (Si la dirección IP de su controlador eedomus es 192.168.0.30): 

http://192.168.0.30/api/get?action=auth.test&api_user=XXXX&api_secret=XXXX

Nota 1: Si llama a la API desde el mismo controlador (ejemplo: Actuadores HTTP), los parámetros api_user y api_secret se pueden omitir (en ese caso, la sintaxis de las URL's debe ser del tipo http://localhost/api/)

Nota 2: La API local no soporta el protocolo HTTPS, al contrario de lo que sucede con la API Cloud.

Funciones de la API

get -> auth.test

Le permite realizar una prueba de autenticación.

Sintaxis de la llamada HTTP 

https://api.eedomus.com/get?action=auth.test&api_user=XXXX&api_secret=XXXX

Descripción de los parámetros de la llamada HTTP


Ejemplo de respuesta 

{
 "success": 1
}


get -> periph.caract

Devuelve las características básicas de un periférico.

Sintaxis de la llamada HTTP 

https://api.eedomus.com/get?action=periph.caract&periph_id=XXXX&api_user=XXXX&api_secret=XXXX

Descripción de los parámetros de la llamada HTTP


Ejemplo de respuesta 

{ 
 "success": 1,
 "body": 
 { 
  "name": "Movimiento Taller",
  "last_value": "100",
  "last_value_text": "Movimiento",
  "last_value_change": "2010-03-29 14:51:22"
 }
}

Descripción de los campos de la respuesta


get -> periph.list

Devuelve la lista de periféricos vinculados a su cuenta.

Sintaxis de la llamada HTTP 

https://api.eedomus.com/get?action=periph.list&api_user=XXXX&api_secret=XXXX

Descripción de los parámetros de la llamada HTTP


Ejemplo de respuesta 

{
   "success": 1,
   "body": [
       {
           "periph_id": "756",
           "parent_periph_id": "",
           "name": "Día actual",
           "value_type": "list",
           "room_id": "1",
           "room_name": "Programación",
           "usage_id": "18",
           "usage_name": "Estado técnico: Día",
           "creation_date": "2013-04-30 14:11:37"
      },
      {
           "periph_id": "757",
           "parent_periph_id": "",
           "name": "Fase del día",
           "value_type": "list",
           "room_id": "1",
           "room_name": "Programación",
           "usage_id": "34",
           "usage_name": "Estado técnico: Fase",
           "creation_date": "2013-04-30 14:11:37"
       },
       { ... }
   ]
}

Descripción de los campos de la respuesta


get -> periph.history

Devuelve el histórico de valores de un periférico.

Sintaxis de la llamada HTTP 

https://api.eedomus.com/get?action=periph.history&periph_id=XXXX&start_date=YYYY-MM-DD HH:MM:SS&end_date=YYYY-MM-DD HH:MM:SS&api_user=XXXX&api_secret=XXXX

Descripción de los parámetros de la llamada HTTP


Ejemplo de respuesta 

{
 "success": 1,
 "body":
 {
   "history": 
   [
    ["69","2010-02-12 14:35:50"],
    ["69","2010-02-12 14:35:50"],
    ["87","2010-04-03 19:36:38"],
    ["82","2010-04-03 20:06:47"],
    ["87","2010-04-03 21:07:03"],
    ["81","2010-04-03 23:17:36"],
    ["87","2010-04-03 23:47:43"],
    ["76","2010-04-04 01:18:13"],
    ["81","2010-04-04 01:38:18"],
    ["87","2010-04-04 03:40:10"],
    ["93","2010-04-04 06:40:59"]
   ]
 }
}

Descripción de los campos de la respuesta


Nota

La respuesta está limitada a los 10.000 primeros valores. En ese caso, se añade el siguiente campo en el JSON de respuesta: 

history_overflow: 10000,

get -> periph.value_list

Lista de valores posibles de un periférico (sólo está disponible para periféricos de tipo Lista).

Sintaxis de la llamada HTTP 

https://api.eedomus.com/get?action=periph.value_list&periph_id=XXXX&api_user=XXXX&api_secret=XXXX

Descripción de los parámetros de la llamada HTTP


Ejemplo de respuesta 

{
   "success": 1,
   "body": {
       "periph_id": 72762,
       "values": [
           {
               "value": "0",
               "description": "Off",
               "icon": "lamp_off.png"
           },
           {
               "value": "100",
               "description": "On",
               "icon": "lamp_on.png"
           }
       ]
   }
}

set -> periph.value

Establece un valor en un periférico. El periférico puede ser un sensor (en ese caso, el valor se guarda en el histórico) o un actuador (el periférico recibe una orden de cambio de valor).

Sintaxis de la llamada HTTP 

https://api.eedomus.com/set?action=periph.value&periph_id=XXXX&value=XXXX&value_date=YYYY-MM-DD HH:MM:SS&api_user=XXXX&api_secret=XXXX

Descripción de los parámetros de la llamada HTTP


Ejemplo de respuesta 

{
 "success": 1,
 "body":
 {
   "result": "[OK]"
 }
}

Nota: Una respuesta exitosa ("success") significa que la orden ha sido recibida por la API y que será transmitida al periférico en cuanto sea posible. No significa que la comunicación con el periférico esté operativa (especialmente si se trata de periféricos inalámbricos) o que se haya ejecutado la orden en el periférico (podría ocurrir que el periférico no estuviera conectado).

Descripción de los campos de la respuesta


set -> periph.macro

Activa una macro en un periférico.

Sintaxis de la llamada HTTP 

https://api.eedomus.com/set?action=periph.macro&macro=XXXX&api_user=XXXX&api_secret=XXXX

Descripción de los parámetros de la llamada HTTP


Ejemplo de respuesta 

{
 "success": 1,
 "body":
 {
   "result": "[OK]"
 }
}

Nota: Una respuesta exitosa ("success") significa que la orden ha sido recibida por la API y que será transmitida al periférico en cuanto sea posible. No significa que la comunicación con el periférico esté operativa (especialmente si se trata de periféricos inalámbricos) o que se haya ejecutado la orden en el periférico (podría ocurrir que el periférico no estuviera conectado).

Descripción de los campos de la respuesta


Códigos de error


Generación automática de llamadas a la API

En la ventana de configuración de cada periférico, en la sección Parámetros Experto, puede acceder a una herramienta que genera automáticamente llamadas a la API haciendo clic en el icono en forma de llave situado delante del código API. Lo único que tiene que hacer es seleccionar en las listas desplegables el tipo de acción y el periférico del que se trate. Esta herramienta le permite construir las llamadas a la API de forma muy sencilla.

Estadísticas sobre el uso de la API

En el caso de que recibiera un mensaje avisándole de que ha superado la cuota APi que tiene asignada, puede consultar las estadísticas sobre el uso de la API.

Para acceder a estas estadísticas, vaya a Configuración / Mi cuenta y haga clic en "Ver sus credenciales" y a continuación en "Estadísticas de uso".


Ejemplos

Puede descargarse y modificar libremente los siguientes ejemplos de uso de la API para empezar sus propios proyectos:

C

eedomus_api_c.zip

C#

Descárguese gratis Visual C# Express

PHP

eedomus_api_php.zip