App de Tipo de fuente de datos: Construye tu conector de datos

Sofia Fernandes

15 de abril de 2026 14:10

Introducción

Una App de tipo fuente de datos te permite construir tu propio conector de datos dentro de la plataforma.

Definir un nuevo tipo de fuente de datos
Ofrecer una experiencia de configuración personalizada
Crear y gestionar fuentes de datos
Enviar lecturas a la plataforma

Este es el enfoque recomendado para:

Integrar un sistema externo
Construir un conector reutilizable
Productizar una integración pública

Si solo quieres enviar datos vía API a una fuente de datos ya existente y/o sin ninguna interfaz personalizada, puedes seguir directamente las instrucciones de la API de inserción.

Antes de empezar

Debes:

Haber creado una app (ver: API de desarrollo: Crear y gestionar tu app)
Disponer de infraestructura backend (servidor de API)
Ser capaz de exponer endpoints HTTPS públicos
Consejo PRO: pide a soporte un esqueleto de app que te ayudará a avanzar más rápido

¿Qué es una App de tipo fuente de datos?

Una App de tipo fuente de datos es una app que:

Define un tipo de fuente de datos
Permite a los usuarios crear fuentes de datos a través de tu UI
Envía datos a esas fuentes de datos

Cómo funciona

1. La app se instala

La app se instala en una cuenta
Tu backend recibe un token permanente
Utilizas este token para llamar a la API v3

(para más detalles ver: API de desarrollo: Crear y gestionar tu app)

2. El tipo de fuente de datos queda disponible

Tras la instalación:

Ve a Configuración
Abre Fuentes de datos
Haz clic en Registrar nueva fuente de datos
Tu tipo de fuente de datos aparece en la lista en la sección de fuentes de datos externas

3. El usuario crea una fuente de datos

Cuando el usuario selecciona tu tipo de fuente de datos, la plataforma carga tu UI:

GET /datasources/new

4. Tu app gestiona la configuración

Tu UI debe:

Solicitar la configuración (credenciales, IDs, etc.)
Validar la entrada
Enviar los datos a tu backend

Custom interface to create and edit each datasource type

5. Tu backend crea la fuente de datos

Debes llamar a la API v3:

POST https://api.dexcell.com/v3/datasources

Ejemplo:

curl --location 'https://api.dexcell.com/v3/datasources' \
  --header 'x-dexcell-token: <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Datasource",
    "key": "unique-key-123",
    "timezone": "Europe/Madrid",
    "type": "VIRTUAL",
    "status": "CONNECTED"
  }'

👉 Referencia completa: https://developers.dexma.com/#75913267-89ad-422f-bce2-fbf606353196

6. Almacena los datos de la fuente de datos localmente

Tu backend debe almacenar:

El id de la fuente de datos
La key de la fuente de datos
La configuración de la fuente de datos
El mapeo hacia tu sistema externo

7. Obtén el token de inserción

Tras crear la fuente de datos:

GET https://api.dexcell.com/v3/datasources/{id}/token

Esto devuelve el token necesario para enviar lecturas.

👉 Referencia completa: https://developers.dexma.com/#18c8716c-e3fe-4d09-82a9-ebd4c17096cb

8. Envía lecturas (API de inserción)

Este es el flujo de datos principal.

POST https://insert.dexma.com/readings?source_key=<DATASOURCE_KEY>

Headers:

x-dexcell-source-token: <DATASOURCE_TOKEN>
Content-Type: application/json

Ejemplo de petición

curl -X POST "https://insert.dexma.com/readings?source_key=<KEY>" \
  -H "x-dexcell-source-token: <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "did": "device-1",
      "sqn": 1,
      "ts": "2026-01-01T00:00:00+01:00",
      "values": [
        { "p": 402, "v": 1250.0 }
      ]
    }
  ]'

Cómo funciona la inserción

para definir "p" ver Introducción a los Parámetros y la lista de id de parámetro, operación y resolución
Las peticiones son asíncronas
HTTP 200 OK significa aceptado, no procesado completamente
Los datos aparecen más tarde en la plataforma

👉 Referencia completa: Uso de la API de inserción para introducir datos en un gateway

9. Editar una fuente de datos

Cuando un usuario abre una fuente de datos:

GET /datasources/{id}

Tu app debe:

Cargar la configuración actual
Permitir ediciones
Enviar las actualizaciones al backend

Llamada al backend:

PUT https://api.dexcell.com/v3/datasources/{id}

10. Eliminar una fuente de datos

Cuando se elimina una fuente de datos:

DELETE /datasources/{id}

Tu backend debe:

Eliminar los mapeos internos
Opcionalmente llamar a la API v3:

DELETE https://api.dexcell.com/v3/datasources/{id}

Devolver:

HTTP 2xx

Si devuelves un error, la eliminación se cancela.

Responsabilidades de la API

	API v3	Insertion API
Usada para	Crear/actualizar/eliminar fuente de datos Obtener el token de la fuente de datos Recuperar datos de contexto Recuperar lecturas	Enviar lecturas
Documentación	https://developers.dexma.com	Uso de la API de inserción para introducir datos en un gateway
Autenticación	x-dexcell-token	datasource-token

Regla arquitectónica crítica

No llames a la API v3 antes de cada inserción.

En su lugar:

Almacena el estado de la fuente de datos localmente
Mantenlo actualizado cuando se produzcan cambios
Usa la API de inserción directamente

Por qué es importante

Si no sigues esta regla:

Puedes alcanzar los límites de la API
El rendimiento se degradará
La integración puede fallar a escala

Directrices de payload y rendimiento

Recomendado: ~1.000 lecturas por petición
Máximo: ~5.000 lecturas
Concurrencia máxima: ~8 peticiones simultáneas
Utiliza el procesamiento por lotes siempre que sea posible

Problemas comunes

Error de inserción

Token de fuente de datos incorrecto
Key de fuente de datos incorrecta
Combinación de parámetros no válida (parámetro base + resolución + parámetro)
Formato de timestamp incorrecto

La inserción tiene éxito pero no aparecen datos

Los datos se insertan con OK, pero no se visualizan en la fuente de datos

Los datos no se pueden ver dentro de la fuente de datos en «eliminar lecturas» ni en «últimas lecturas». Puede deberse a:

Timestamp inválido para la combinación de parámetros: los datos de intervalo temporal deben insertarse al inicio del período y teniendo en cuenta la resolución elegida.
Combinación de parámetros no válida (parámetro base + resolución + parámetro)
Dispositivo siendo rechazado

Los datos se insertan con OK, pero no se visualizan en los análisis

Los datos sí se pueden ver dentro de la fuente de datos en «eliminar lecturas» o «últimas lecturas», pero no en los análisis. Comprueba que:

El dispositivo y el parámetro están aceptados
El dispositivo está asignado a una ubicación
Estás visualizando los datos en el dispositivo, parámetro, resolución, operación y período de tiempo correctos

Buenas prácticas de UI