> 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
## Visión general técnica y capacidades
{% columns %}
{% column %}
**Fuente de datos** El 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 a través de los protocolos TCP/UDP/HTTP en interfaces de red y mediante colas MQTT, y luego decodificando 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 ha agregado a este nodo. Un sistema externo, como una plataforma telemática independiente que no envía datos a Navixy de forma predeterminada, inserta atributos adicionales en el flujo del dispositivo. A veces esa plataforma externa es la propia del fabricante del dispositivo. En lugar de migrar el dispositivo a la ingesta nativa de Navixy, el **Software** La pestaña lo mantiene registrado tal cual. Enriquece continuamente el flujo del dispositivo con datos de esa otra plataforma, por lo que ambos flujos se ejecutan en paralelo. Consulte [Cómo se gestionan los datos enviados](#how-pushed-data-is-handled) para entender el funcionamiento, y [Opciones de configuración](#configuration-options) para configurarlo.
### Integración con la arquitectura de flujo
**nodo de Fuente de datos** funciona como el punto de entrada de los 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 distintos fabricantes en formatos unificados
* Rutas de procesamiento paralelas al conectar una fuente de datos con varios nodos posteriores
* Filtrado selectivo de dispositivos para incluir solo las fuentes de datos relevantes en su flujo
* Enriquecimiento del flujo para dispositivos ya conectados, mediante 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 múltiples 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 broker MQTT
* **Transformación unificada de datos**: Convierte los mensajes específicos del dispositivo a un formato estandarizado para un procesamiento uniforme
* **Filtrado de dispositivos**: Proporciona capacidades de filtrado para seleccionar modelos o protocolos específicos
* **Procesamiento en tiempo real**: Gestiona los flujos de datos de telemetría entrantes en tiempo real para su procesamiento inmediato
* **Enriquecimiento por push HTTP**: Fusiona los atributos enviados desde un sistema externo en el flujo de un dispositivo ya seleccionado en este nodo. HTTP es hoy el único tipo de push compatible, y la arquitectura está diseñada para admitir 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 cuadro de configuración se organiza en dos pestañas:
* **Dispositivos**: selecciona qué dispositivos envían telemetría al flujo. Es obligatorio y funciona exactamente igual que antes.
* **Software**: configura el enriquecimiento por push 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 **Software** la pestaña depende de la **Dispositivos** pestaña. Su **Dispositivo origen** selector solo muestra los dispositivos ya seleccionados en **Dispositivos**, y no muestra datos disponibles hasta que seleccione al menos uno allí.
{% endhint %}
Veamos qué elementos usa 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 **Software** pestaña opcional, que solo puede asociar los 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 push HTTP (opcional)
Cambie a la **Software** pestaña para enriquecer los dispositivos que seleccionó en Dispositivos con datos enviados desde un sistema externo. Este paso es opcional. Consulte [Configuración del enriquecimiento por push 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 notificará si algún dispositivo seleccionado no coincide con los nuevos parámetros, pero no lo eliminará automáticamente de su selección.
{% endhint %}
### Configuración del enriquecimiento por push HTTP
El enriquecimiento por push HTTP permite que un sistema externo agregue atributos a un dispositivo ya seleccionado en la **Dispositivos** pestaña de este nodo, mediante el envío de datos a una URL generada. Es opcional y requiere al menos un dispositivo seleccionado en [Pasos de configuración](#configuration-steps) ella primero.
Esto es útil cuando un dispositivo ya reporta a un sistema separado que no envía datos a Navixy de forma predeterminada, por ejemplo una plataforma de gestión de baterías que realiza seguimiento del nivel de batería del mismo vehículo. En lugar de migrar el dispositivo a la ingesta nativa de Navixy, puede mantenerlo registrado tal como está 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 mapeado, junto con su telemetría GPS nativa.
{% stepper %}
{% step %}
#### Configurar el tipo de conector
Cambie a la **Software** pestaña y establezca **Tipo de conector** a **HTTP**, actualmente la única opción.
{% endstep %}
{% step %}
#### Guarde el flujo y copie la URL generada
Guarde todo el flujo, no solo este Nodo. El **URL** campo solo genera un valor una vez que el flujo se guarda con **Tipo de conector** establecido. Hasta entonces, muestra un marcador de posición que le pide 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 %}
#### Autentique el sistema externo
Proporcione al sistema externo una válida [clave de API de Navixy](/docs/user/es/guide/account/api-keys.md), y configúrelo para enviar `Authorization: NVX ` con cada solicitud de push, junto con la URL. Un push sin este encabezado falla, por lo que tanto la URL como el encabezado son obligatorios antes de que puedan recibirse datos.
{% endstep %}
{% step %}
#### Definir clave primaria y correspondencias
Ingrese un **Clave primaria**: el nombre del campo que el sistema externo usa para identificar a qué dispositivo pertenece un registro enviado. Admite hasta 64 caracteres, solo letras, dígitos y guiones bajos.
Agregar uno **Correspondencias** fila por dispositivo para enriquecer. Para cada fila, seleccione la **Dispositivo origen**, limitado a los dispositivos ya seleccionados en Dispositivos, e ingrese la **Valor de la clave** que identifica a ese dispositivo en los envíos entrantes. Este campo almacena hasta 255 caracteres, pero el propio endpoint de envío solo acepta hasta 100 caracteres por campo, así que, en la práctica, mantenga el valor bastante por debajo de 100 caracteres.
{% hint style="warning" %}
Tanto la clave primaria como el valor de la clave aceptan solo letras, dígitos y guiones bajos; no guiones ni otra puntuación. La validación general de campos del endpoint de envío es más permisiva y acepta guiones en cualquier campo sin problema, pero un valor con guiones nunca puede coincidir con un valor de clave almacenado, por lo que los envíos que usan 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**, luego vuelva a guardar 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 apropiado 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 en 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 la configuración del Nodo **Correspondencias**, y luego combina los campos restantes en el flujo de datos del dispositivo asignado 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 denominado en **Clave primaria**, junto con `flujo_id` y `id_del_Nodo`, se usa 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 una asignación | 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 ninguna asignación | 200, `éxito: true` | No. Se descarta silenciosamente |
| Faltante o no válido `Authorization` encabezado | error 400 | No. Se rechaza antes de que Navixy verifique la clave primaria |
{% hint style="info" %}
Una respuesta 200 solo confirma que Navixy aceptó la solicitud, no que los datos se fusionaron. Un valor de clave primaria que no coincide se descarta silenciosamente, sin ningún error que lo indique. Si no está seguro de que un envío se haya vinculado, revise los atributos del dispositivo asignado 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 único espacio de nombres con los atributos nativos del 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 aparte.
Los sensores, los reportes y las 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 coincide con el atributo nativo de combustible de un dispositivo inyectaría una lectura falsa, generando eventos falsos de caída de combustible o reabastecimiento en los reportes.
Para evitarlo, anteponga un prefijo a los nombres de los campos enviados para que no puedan entrar en conflicto 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 del mensaje del sistema, como `velocidad`, `latitud`, `longitud`, `rumbo`, `satélites`, y `hdop` no pueden sobrescribirse de esta forma. 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 paquetes del propio dispositivo pueden adelantar el historial del atributo más allá del valor enviado en cuestión de segundos, aunque la fusión se haya realizado correctamente.
{% hint style="info" %}
Es una consecuencia esperada de que dos flujos de datos funcionen a velocidades distintas, no un defecto. Use el atributo aguas abajo como `value('attribute_name', 0, 'valid')` en lugar de su nombre sin formato. `'valid'` retrocede en el historial del atributo hasta la última lectura no nula, de modo que los nodos aguas abajo obtengan el valor enviado independientemente del momento.
{% endhint %}
El endpoint de envío admite hasta 1 solicitud por segundo por clave de API, con un tamaño de ráfaga de 1. Ajuste en consecuencia la frecuencia de las solicitudes del sistema externo.
## Preguntas frecuentes
#### ¿Puedo usar varios nodos Fuente de datos en un solo flujo?
Sí, puede usar varios **Nodos de fuente de datos** nodos Fuente de datos en un solo espacio de trabajo. Esto es útil cuando necesita procesar datos de distintos tipos de dispositivos de diferentes maneras o cuando desea fusionar varios flujos de datos después de transformaciones específicas.
#### ¿Qué sucede si un dispositivo ya se usa en otro flujo?
Un dispositivo puede pertenecer a varios flujos al mismo tiempo. Si añade 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. Que esté 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 uno de los envíos 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 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 **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 Fuente de datos a varios nodos descendentes?
Sí, puede conectar un **nodo de Fuente de datos** nodo Fuente de datos a varios nodos de procesamiento para crear rutas de procesamiento paralelas. Esto le permite aplicar distintas transformaciones al mismo flujo de datos. Este es un ejemplo:
#### ¿Puedo incorporar datos de un sistema que no sea un dispositivo Navixy?
Sí, a través de la **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.
#### El sistema desde el que envío reporta 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 reporta mucho más seguido, ya que ambas fuentes comparten el mismo historial continuo. Referencie el atributo aguas abajo como `value('attribute_name', 0, 'valid')` en lugar de su nombre sin formato para obtener de forma confiable la última lectura real, sin importar el momento. Esta es una consecuencia esperada de que dos flujos se ejecuten a diferentes velocidades, no un defecto.
#### Envié datos, pero no aparecen. ¿Qué está mal?
Verifique estos puntos en orden:
1. Confirme que la solicitud incluyó un `Authorization: NVX ` encabezado. Un encabezado faltante o no válido falla de forma evidente con un error HTTP 400.
2. Confirme que el nombre del campo enviado coincide exactamente con la configuración del Nodo **Clave primaria** y que su valor coincide con uno de los valores configurados **Correspondencias** 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 de la clave almacenado, así que la solicitud sigue devolviendo éxito aunque no se fusione nada.
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 sacar un valor fusionado de la ranura actual en cuestión de segundos, aunque la fusión se haya realizado con éxito.
#### Envié un campo y las lecturas nativas del dispositivo parecen incorrectas
El nombre del campo enviado probablemente coincidía con un atributo nativo que el dispositivo ya reporta, o con uno enviado por el conector de otro flujo, y sobrescribió 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) Analizador de datos para confirmar que los valores enviados y nativos ya no se mezclan.
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.