> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/user/es/guide/account/iot-logic/nodes/data-source-node.md).
# Fuente de datos
El nodo Fuente de datos es el punto de entrada de IoT Logic para la telemetría del dispositivo. Recibe datos por TCP, UDP, HTTP o MQTT, los decodifica y los pasa a los nodos posteriores. También puede enriquecer un dispositivo ya conectado.
## Visión general técnica y capacidades
{% columns %}
{% column %}
**Fuente de datos** Nodo es un punto de entrada para los datos de telemetría de dispositivos IoT y plataformas OEM en el sistema IoT Logic. Funciona como un traductor universal, recibiendo datos mediante los protocolos TCP/UDP/HTTP en interfaces de red y a través de colas MQTT, y luego decodifica los flujos de datos entrantes según el protocolo seleccionado. El nodo transforma los mensajes del dispositivo en un formato estandarizado que luego puede procesarse en su flujo.
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
Además de recibir telemetría, un **Fuente de datos** nodo también puede enriquecer un dispositivo que ya haya agregado a él. Un sistema externo, como una plataforma telemática separada que no envía datos a Navixy de forma predeterminada, envía atributos adicionales al flujo del dispositivo. A veces esa plataforma externa es la del propio fabricante del dispositivo. En lugar de migrar el dispositivo a la ingesta nativa de Navixy, la **pestaña Software** lo mantiene registrado tal cual. Lo enriquece continuamente con datos de esa otra plataforma, de modo que ambos flujos funcionan en paralelo. Vea [Cómo se gestionan los datos enviados](#how-pushed-data-is-handled) para conocer la mecánica, y [Opciones de configuración](#configuration-options) para configurarlo.
### Integración con la arquitectura del flujo
**nodo de Fuente de datos** funciona como el punto de entrada de datos en un flujo de IoT Logic. Un solo flujo puede contener varios nodos de origen, cada uno con configuraciones independientes. Esta arquitectura permite:
* Adquisición inicial de datos de múltiples tipos de dispositivos y formatos de protocolo
* Transformación estandarizada de datos de varios fabricantes en formatos unificados
* Rutas de procesamiento en paralelo al conectar una fuente de datos con varios nodos descendentes
* Filtrado selectivo de dispositivos para incluir solo las fuentes de datos relevantes en su flujo
* Enriquecimiento del flujo para dispositivos ya conectados, utilizando atributos enviados desde un sistema externo por HTTP
### Capacidades del nodo
El **nodo de Fuente de datos** por sí solo ofrece:
* **Diversidad de protocolos**: admite varios fabricantes de dispositivos, incluidos Teltonika, Queclink, Suntech, Jimi y otros, mediante analizadores y decodificadores heredados de Navixy
* **Flexibilidad de transporte**: admite protocolos TCP, UDP, HTTP y conexiones con el broker MQTT
* **Transformación unificada de datos**: convierte mensajes específicos de cada dispositivo a un formato estandarizado para un procesamiento uniforme
* **Filtrado de dispositivos**: ofrece capacidades de filtrado para seleccionar modelos o protocolos específicos
* **Procesamiento en tiempo real**: maneja flujos entrantes de datos de telemetría en tiempo real para su procesamiento inmediato
* **Enriquecimiento por envío HTTP**: fusiona atributos enviados desde un sistema externo en el flujo de un dispositivo ya seleccionado en este nodo. HTTP es hoy el único tipo de envío admitido, con una arquitectura diseñada para añadir más en el futuro
## Opciones de configuración
{% columns %}
{% column width="58.333333333333336%" valign="middle" %}
Configurar un **Fuente de datos** El nodo determina qué dispositivos envían datos a su flujo y, opcionalmente, cómo un sistema externo puede enriquecer esos dispositivos con datos enviados.
El diálogo de configuración se organiza en dos pestañas:
* **Dispositivos**: selecciona qué dispositivos envían telemetría al flujo. Obligatorio y funciona exactamente igual que antes.
* **pestaña Software**: configura el enriquecimiento por envío HTTP para los dispositivos que seleccionó en la pestaña Dispositivos. Es opcional y depende de esa selección.
{% endcolumn %}
{% column width="41.666666666666664%" %}
{% endcolumn %}
{% endcolumns %}
{% hint style="info" %}
El **pestaña Software** depende de la **Dispositivos** pestaña. Su **Dispositivo de origen** selector solo enumera los dispositivos ya seleccionados en **Dispositivos**, y no muestra datos disponibles hasta que seleccione al menos uno allí.
{% endhint %}
Veamos qué elementos utiliza este nodo y qué puede configurar al trabajar con él:
### Pasos de configuración
{% stepper %}
{% step %}
#### Especificar el nombre del nodo
Ingrese un nombre descriptivo para esta fuente de datos:
* Use un nombre que le ayude a identificar el fabricante, los modelos u otra información relevante.
* Este nombre se mostrará en el diagrama de flujo para facilitar su identificación.
{% endstep %}
{% step %}
#### Seleccionar fuentes
De la lista filtrada, seleccione los dispositivos que desea incluir. Solo están disponibles para selección los dispositivos registrados en su cuenta de usuario de Navixy. Esta selección también es el requisito previo para la pestaña opcional **pestaña Software** pestaña, que solo puede mapear dispositivos seleccionados aquí.
{% endstep %}
{% step %}
#### Guarde la configuración del nodo
Haga clic en **Aplicar cambios** para completar la creación del nodo.
{% endstep %}
{% step %}
#### Configurar el enriquecimiento por envío HTTP (opcional)
Cambie a la **pestaña Software** pestaña para enriquecer los dispositivos que seleccionó en Dispositivos con datos enviados desde un sistema externo. Este paso es opcional. Vea [Configuración del enriquecimiento por envío HTTP](#configuring-http-push-enrichment) para la configuración completa.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
Si cambia la configuración del fabricante o del modelo después de seleccionar dispositivos, Navixy le notifica si alguno de los dispositivos seleccionados no coincide con los nuevos parámetros, pero no los elimina automáticamente de su selección.
{% endhint %}
### Configuración del enriquecimiento por envío HTTP
El enriquecimiento por envío HTTP permite que un sistema externo agregue atributos a un dispositivo ya seleccionado en la **Dispositivos** pestaña de este nodo, enviando datos a una URL generada. Es opcional y requiere al menos un dispositivo seleccionado en [Pasos de configuración](#configuration-steps) primero.
Esto es útil cuando un dispositivo ya reporta a otro sistema que, de forma predeterminada, no alimenta Navixy; por ejemplo, una plataforma de gestión de baterías que rastrea el Nivel de batería del mismo vehículo. En lugar de migrar el dispositivo a la ingesta nativa de Navixy, puede mantenerlo registrado tal cual y hacer que esa otra plataforma envíe aquí sus lecturas. Un envío con `vehicle_id: "truck_12"`, `bms_battery_soc: 76`, y `bms_battery_temp: 34.2` agrega `bms_battery_soc` y `bms_battery_temp` como nuevos atributos en el dispositivo asignado, junto con su telemetría GPS nativa.
{% stepper %}
{% step %}
#### Establecer tipo de conector
Cambie a la **pestaña Software** pestaña y establezca **Tipo de conector** a **HTTP**, actualmente es la única opción.
{% endstep %}
{% step %}
#### Guarde el flujo y copie la URL generada
Guarde todo el flujo, no solo este nodo. El **URL** el campo solo genera un valor una vez que el flujo se guarda con **Tipo de conector** configurado. Hasta entonces, muestra un marcador de posición que le indica guardar el flujo. Una vez que aparezca la URL, haga clic en el ícono de copiar junto a ella; solo está deshabilitado mientras el campo esté vacío.
{% endstep %}
{% step %}
#### Autenticar el sistema externo
Proporcione al sistema externo una [clave API de Navixy](/docs/user/es/guide/account/api-keys.md), y configúrelo para enviar `Authorization: NVX ` con cada solicitud push, junto con la URL. Una solicitud push sin este encabezado falla, por lo que tanto la URL como el encabezado son necesarios antes de que los datos puedan llegar.
{% endstep %}
{% step %}
#### Definir la clave primaria y las asignaciones
Ingrese un **Clave primaria**: el nombre del campo que el sistema externo usa para identificar a qué dispositivo pertenece un registro enviado. Acepta hasta 64 caracteres, solo letras, dígitos y guiones bajos.
Añada una **Mapeos** fila por dispositivo para enriquecer. Para cada fila, seleccione el **Dispositivo de origen**, limitado a los dispositivos ya seleccionados en Dispositivos, e ingrese el **Valor de clave** que identifica ese dispositivo en los envíos entrantes. Este campo almacena hasta 255 caracteres, pero el propio endpoint de push solo acepta hasta 100 caracteres por campo, así que en la práctica mantenga el valor muy por debajo de 100 caracteres.
{% hint style="warning" %}
Tanto Clave primaria como Valor de clave aceptan solo letras, dígitos y guiones bajos, no guiones ni otros signos de puntuación. La validación general de campos del endpoint de push es más permisiva y acepta guiones en cualquier campo sin objeciones, pero un valor con guiones nunca puede coincidir con un Valor de clave almacenado, por lo que los envíos que usen uno se descartan silenciosamente exactamente como si el valor no coincidiera. Si los identificadores de su sistema externo usan guiones (por ejemplo `truck-12`), tradúzcalos, por ejemplo a `truck_12`, antes de enviarlo.
{% endhint %}
{% endstep %}
{% step %}
#### Aplicar y guardar
Haga clic en **Aplicar cambios**, y luego guarde nuevamente el flujo si configuró la pestaña Software después del guardado inicial.
{% endstep %}
{% endstepper %}
### Detalles del procesamiento de datos
**Nodo de fuente de datos** hereda todos los analizadores y decodificadores de Navixy, lo que proporciona compatibilidad con una amplia gama de dispositivos IoT. Cuando los datos llegan a este nodo, pasan por el siguiente proceso:
1. El flujo de datos entrante se recibe a través del protocolo de transporte especificado
2. Los datos se pasan al decodificador de protocolo correspondiente según su configuración
3. Los mensajes del dispositivo se transforman en un formato estandarizado que IoT Logic puede procesar
4. Los datos unificados se pasan al siguiente nodo de su flujo
Este proceso de estandarización le permite crear flujos de procesamiento consistentes, independientemente del formato de datos original de distintos fabricantes de dispositivos.
### Cómo se gestionan los datos enviados
Navixy compara cada push entrante por el valor de su clave primaria con el nodo configurado **Mapeos**, luego fusiona los campos restantes en el flujo de datos del dispositivo mapeado como atributos: nuevos si el nombre del campo es nuevo, o escritos en el historial existente de ese atributo si el nombre coincide con uno que ya existe, ya sea reportado de forma nativa por el dispositivo o enviado por el conector de otro flujo. No afectan la ubicación ni otra telemetría. El campo indicado en **Clave primaria**, junto con `flujo_id` y `nodo_id`, se utiliza para el enrutamiento y nunca se convierte en un atributo en sí mismo. Una solicitud puede terminar en uno de tres estados:
| Resultado | Respuesta HTTP | ¿Se fusionaron los datos? |
| ---------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| El valor de la clave primaria coincide con un mapeo | 200, `éxito: true` | Sí. Los campos restantes se fusionan como atributos: nuevos si el nombre es nuevo, historial existente si coincide con uno ya en uso |
| El valor de la clave primaria no coincide con ningún mapeo | 200, `éxito: true` | No. Se descarta silenciosamente |
| Falta o no es válido `Authorization` encabezado | error 400 | No. Se rechaza antes de que Navixy compruebe la clave primaria |
{% hint style="info" %}
Una respuesta 200 solo confirma que Navixy aceptó la solicitud, no que los datos se hayan fusionado. Un valor de clave primaria que no coincida se descarta silenciosamente, sin ningún error que lo indique. Si no está seguro de que un envío haya coincidido, revise los atributos del dispositivo mapeado en [Analizador de datos](/docs/user/es/guide/account/iot-logic/data-stream-analyzer.md) en lugar de confiar en la respuesta.
{% endhint %}
{% hint style="warning" %}
El nombre de un campo enviado comparte un mismo espacio de nombres con los atributos nativos del propio dispositivo y con los nombres enviados por el conector de otro flujo que enriquece el mismo dispositivo. Si el nombre coincide con uno ya en uso, ya sea nativo del dispositivo o enviado por otro flujo, el envío sobrescribe el historial existente de ese atributo en lugar de crear uno separado.
Los sensores, Reportes y Alertas leen el valor fusionado como una lectura real, por lo que un nombre en conflicto puede generar datos falsos aguas abajo. Por ejemplo, un campo enviado llamado `nivel_de_combustible` que coincida con el atributo nativo de Combustible de un dispositivo inyectaría una lectura falsa, lo que produciría eventos falsos de caída de combustible o reabastecimiento en los Reportes.
Para evitar esto, anteponga un prefijo a los nombres de los campos enviados para que no puedan colisionar con los atributos nativos de un dispositivo ni con los nombres enviados por otro flujo, por ejemplo `bms_battery_soc` en lugar de `battery_soc`.
Los campos de mensaje del sistema, como `velocidad`, `latitud`, `longitud`, `rumbo`, `satélites`, y `hdop` no pueden sobrescribirse de esta manera. Los envíos solo crean o actualizan atributos; nunca telemetría a nivel de mensaje. Un campo enviado que use uno de esos nombres sigue apareciendo con ese nombre en [Analizador de datos](/docs/user/es/guide/account/iot-logic/data-stream-analyzer.md), separado de la telemetría real del dispositivo.
{% endhint %}
Un atributo fusionado queda como una entrada puntual en el historial de atributos del dispositivo, no como un valor actual persistente. Si el dispositivo informa su propia telemetría con mucha más frecuencia que el sistema externo envía actualizaciones, los propios paquetes del dispositivo pueden adelantar el historial del atributo más allá del valor enviado en cuestión de segundos, aunque la fusión haya tenido éxito.
{% hint style="info" %}
Esta es una consecuencia esperada de que dos flujos de datos funcionen a distintas velocidades, no un defecto. Haga referencia al atributo aguas abajo como `value('attribute_name', 0, 'valid')` en lugar de usar su nombre sin formato. `'válido'` recorre hacia atrás el historial del atributo hasta la última lectura no nula, por lo que los nodos aguas abajo reciben el valor enviado sin importar el momento. Vea [Valores faltantes y enrutamiento de null](/docs/user/es/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md#missing-values-and-null-routing) para ver cómo `'válido'` se compara con `'todos'` en una condición del nodo Logic.
{% endhint %}
El endpoint de envío acepta hasta 1 solicitud por segundo por clave de API, con un tamaño de ráfaga de 1. Ajuste en consecuencia el ritmo de las solicitudes del sistema externo.
## Preguntas frecuentes
#### ¿Puedo usar varios nodos de Fuente de datos en un flujo?
Sí, puede usar varios **nodos de Fuente de datos** en un mismo espacio de trabajo. Esto es útil cuando necesita procesar datos de distintos tipos de dispositivos de diferentes maneras o cuando quiere fusionar varios flujos de datos después de transformaciones específicas.
#### ¿Qué pasa si un dispositivo ya se usa en otro flujo?
Un dispositivo puede pertenecer a varios flujos al mismo tiempo. Si agrega un dispositivo que ya se usa en otro flujo, ambos flujos procesan sus datos simultáneamente y los resultados se fusionan para evitar la pérdida de datos. Estar asignado a otro flujo no es una restricción. Sin embargo, si los conectores de dos flujos envían el mismo nombre de atributo a ese dispositivo, no se fusionan sin problemas. El historial de un envío sobrescribe el del otro. Vea [Cómo se gestionan los datos enviados](#how-pushed-data-is-handled) para evitar nombres en conflicto.
#### ¿Todos mis dispositivos de Navixy están disponibles automáticamente en IoT Logic?
Sí, todos los dispositivos de su cuenta de usuario de Navixy pueden usarse en el procesamiento de IoT Logic. Esto incluye dispositivos GPS, plataformas OEM, dispositivos y pasarelas MQTT, y conectores MQTT/Kafka. Un dispositivo ya seleccionado en un **Fuente de datos** nodo también puede enriquecerse con atributos enviados desde un sistema externo por HTTP, a través del nodo **pestaña Software** pestaña.
#### ¿Cómo sé qué fabricante seleccionar para mis dispositivos?
El protocolo debe coincidir con el protocolo de comunicación usado por el fabricante de su dispositivo. La mayoría de los dispositivos usan un protocolo asociado con su fabricante (por ejemplo, los dispositivos Teltonika usan el protocolo Teltonika). Revise la documentación de su dispositivo o consulte con su proveedor si no está seguro.
#### ¿Puedo conectar un nodo de Fuente de datos a varios nodos aguas abajo?
Sí, puede conectar un **nodo de Fuente de datos** a varios nodos de procesamiento para crear rutas de procesamiento paralelas. Esto le permite aplicar diferentes transformaciones al mismo flujo de datos. Aquí tiene un ejemplo:
#### ¿Puedo incorporar datos de un sistema que no sea un dispositivo de Navixy?
Sí, a través de la **pestaña Software** pestaña, pero solo para enriquecer un dispositivo que ya haya agregado en la **Dispositivos** pestaña. No es una forma de crear un flujo sin dispositivos en él.
#### El sistema desde el que envío informa con menos frecuencia que mi dispositivo, ¿se perderán los datos enviados?
No, pero un atributo enviado puede dejar de ser el valor actual rápidamente si el dispositivo informa con mucha más frecuencia, ya que ambos contribuyentes comparten el mismo historial móvil. Haga referencia al atributo aguas abajo como `value('attribute_name', 0, 'valid')` en lugar de su nombre simple para obtener de forma confiable la última lectura real, independientemente del momento. Esta es una consecuencia esperada de que dos flujos se ejecuten a distintas velocidades, no un defecto. Consulte [Cómo se gestionan los datos enviados](#how-pushed-data-is-handled) y [Valores faltantes y enrutamiento de null](/docs/user/es/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md#missing-values-and-null-routing) para el `'válido'` frente a `'todos'` distinción en una condición de un nodo Logic.
#### Envié datos, pero no se muestran. ¿Qué está mal?
Revise esto en este orden:
1. Confirme que la solicitud incluyó un encabezado válido `Authorization: NVX ` . Un encabezado faltante o no válido falla de forma explícita con un error HTTP 400.
2. Confirme que el nombre del campo enviado coincida con el ajuste del nodo **Clave primaria** exactamente, y que su valor coincida con uno de los configurados **Mapeos** exactamente, solo letras, dígitos y guiones bajos. Un valor con guiones es la causa más común: pasa la validación propia del endpoint de envío sin error, pero nunca puede coincidir con un valor Key almacenado, así que la solicitud sigue devolviendo éxito mientras nada se fusiona.
3. Revise el historial del atributo en Analizador de datos, no solo su valor actual. Un dispositivo que reporta su propia telemetría a menudo puede desplazar un valor fusionado fuera de la ranura actual en cuestión de segundos, aunque la fusión haya tenido éxito.
#### Envié un campo y las lecturas del propio dispositivo parecen incorrectas
Es probable que el nombre del campo enviado haya coincidido con un atributo nativo que el dispositivo ya reporta, o con uno enviado por el conector de otro flujo, y haya sobrescrito su historial en lugar de crear un atributo separado. Cambie el nombre del campo enviado con un prefijo distinto, luego revise el historial del atributo en [Analizador de datos](/docs/user/es/guide/account/iot-logic/data-stream-analyzer.md) para confirmar que los valores enviados y nativos ya no estén mezclados.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://navixy.com/docs/user/es/guide/account/iot-logic/nodes/data-source-node.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
.png?alt=media)
