API de desarrollo: Crea y gestiona tu app

• Objetivo
• Requisitos
• Inicio rápido para autenticarse
• Configuración de la app
• Modelo de handshake y autenticación
• UI Integrada (opcional)
• Buenas prácticas (seguridad + operabilidad)
• Enlaces relacionados

Objetivo

Esta guía explica cómo registrar una App de mercado, instalarla en una cuenta, completar la autenticación y empezar a usar la API v3. No pretende ser una referencia completa de la API — usa el portal de desarrolladores para la documentación exhaustiva de los endpoints.

Requisitos

Necesitas:

• Un usuario de la plataforma con permisos de superadministrador para registrar la app.
• Un servidor backend con una URL HTTPS pública y capacidad para gestionar peticiones HTTP.

• Conocimientos básicos de REST, cabeceras HTTP y JSON.

Inicio rápido para autenticarse

Si no necesitas desarrollar ninguna UI que interactúe con la plataforma, y solo necesitas un token para obtener datos de la API, puedes saltarte las secciones de configuración de la app y del modelo de handshake y autenticación, e instalar directamente la App de token de acceso.

Este token tiene permisos de solo lectura. Si necesitas permisos adicionales, sigue las instrucciones de configuración de la app y del handshake.

Configuración de la app

Registra tu app (Gestión de organización → Apps de mercado)

• Desde el menú de usuario de la esquina superior derecha, abre Gestión de la Organización.
• Ve a Aplicaciones del Market y haz clic en Nueva aplicación.
• Rellena:
  • Información general (nombre, descripción, icono, visibilidad privada/pública).
  • URLs: URL de instalación (obligatoria), URL de limpieza/desinstalación opcional; vistas de UI integradas/informes/fuentes de datos opcionales.
  • Permisos: concede las áreas de recursos de lectura/escritura que tu app necesitará (los permisos que falten pueden bloquear el acceso).
• Guarda la app y anota el ID de la app y el Secreto de la app (necesarios para el intercambio de token en la instalación).

Note: Private apps can be installed in your own organisation's accounts without any further action, while public apps (visible for platform customers) require approval. Contact support for approval, once the app is the app is ready and if you would like to make it public.

Install your app in an account (Apps Market)

• En la cuenta de destino, abre el Apps Market e instala tu app.

Modelo de handshake y autenticación

Cuando un usuario instala tu app:

• La plataforma llama a tu URL de instalación con dep_id y tem_token
• Tu backend intercambia el temp_token por un token permanente usado en la API v3 (x-dexcell-token).
• Tu app devuelve HTTP 200 OK para completar la instalación.

Ejemplo: usar el token permanente en llamadas a la API v3

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

Límites de peticiones

Los límites predeterminados son de 10.000 peticiones/día y 1.000 peticiones/hora, que pueden consultarse en las cabeceras de cada petición.

Estos límites pueden aumentarse bajo petición enviando un correo electrónico al soporte. El correo debe incluir los límites solicitados y una justificación de por qué dicha capacidad es necesaria.

UI integrada (opcional)

Es posible exponer una UI en distintas secciones de la plataforma, incluyendo Dashboards, sección de Análisis, Informes y Fuente de datos.

La sesión de la plataforma expone información que puedes usar para construir estas interfaces, que incluye:

• account
• current_location
• location_tags
• locations_below
• user (incluyendo user role and locale)
• custom domain

Buenas prácticas (seguridad + operabilidad)

• Mantén los tokens en el lado del servidor; no expongas x-dexcell-token en el código del frontend.
• Diseña para reinstalación/desinstalación: cada instalación genera un nuevo token, y la desinstalación lo invalida.
• Cachea y agrupa en lotes las lecturas de la API v3 para evitar el agotamiento de la cuota.

Ejemplos de llamadas

Con la app registrada e instalada correctamente en una de tus cuentas, deberías haber recibido el x-dexcell-token y haberlo almacenado en tu app. Con ese token, puedes realizar consultas a los distintos endpoints de la API. Todas las consultas disponibles están descritas en el portal de desarrolladores de la plataforma: developers.dexma.com.

Obtener una lista de todas mis localizaciones

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

Obtener la información específica de una localización

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

Obtener lecturas

• 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: obtenido desde /devices. No es lo mismo que la clave del dispositivo.
  • parameter key: consulta la lista de parámetros e introducción a los parámetros
  • operation: 
    • para lecturas instantáneas: RAW
    • para lecturas de intervalo temporal:
      • DELTA para parámetros de naturaleza acumulada (energía, volumen, masa, ...)
      • AVG, MAX, MIN para parámetros de naturaleza instantánea (potencia, temperatura, humedad, ...)
  • resolution:
    • si operation = RAW, entonces resolution debe ser = B
    • si operation != RAW, entonces resolution puede ser cualquiera de: FM, TM, QH, HH, H, D, M
  • from / to: YYYY-MM-DDThh:mm:ss (en hora local)
• headers: x-dexcell-token 

Enlaces relacionados

• Apps de tipo fuente de datos: Construye tu conector de datos
• Uso de la API de inserción para introducir datos en un gateway
• App de token de acceso
• APIv3 - Portal de desarrolladores