====== SMART → DataLake: integración de datos ====== Extracción de conjuntos de datos del ERP SMART hacia **DataLake**, el producto de análisis de datos mediante IA, para la empresa **Alvemaco Rentacar** (clave de instalación **ALR**). Cada conjunto de datos se obtiene llamando a un procedimiento almacenado a través del servicio web de Smart (//iSmartWebDoc//). El agente de DataLake ejecuta una consulta ''SELECT * FROM (...)'' y recibe el resultado en JSON. ---- ====== Información general ====== === Métodos de acceso === Los datos se pueden alcanzar de dos formas: * **SmartWebDoc** (servicio web): los procedimientos se llaman por HTTP con una petición POST, tal y como se describe a continuación y se utiliza en todos los ejemplos de este documento. //SmartWebDoc lo instala Smart Software Solutions.// Ver la documentación de SmartWebDoc: [[https://wiki.smartastur.com/doku.php?id=usu:smartweb:introduccion_a_smartwebdoc|Introducción a SmartWebDoc]]. * **ODBC**: alternativamente, los mismos procedimientos se pueden consultar directamente mediante una conexión ODBC a la base de datos Firebird. Los nombres de procedimientos y campos son idénticos, y las sentencias ''SELECT * FROM (...)'' son las mismas; **solo cambian el transporte y el formato de la respuesta**. Por ODBC el cliente recibe directamente el conjunto de resultados (filas y columnas), sin el envoltorio JSON (''version'' / ''resultados'' / ''metaData'' / ''datos'') que se describe más abajo y que es propio de SmartWebDoc. //La instalación del driver ODBC es responsabilidad del administrador de sistemas del cliente.// Los datos de conexión y los ejemplos siguientes se refieren al servicio **SmartWebDoc**. === Método === POST === Formato === http://#ip:#puerto/services/ismartwebdoc/?format=json Para esta instalación: http://192.168.1.125:8001/services/ismartwebdoc/?format=json === Puertos posibles === - 8001 === Direcciones IP posibles === - 192.168.1.125 === Credenciales de usuario === No es necesario introducir credenciales en el lado del cliente: el servicio SmartWebDoc se configura con un usuario dedicado, creado ad-hoc para DataLake, a través del cual el administrador de Smart establece las restricciones de acceso y los privilegios sobre tablas y procedimientos. === Otros === Para los ejemplos se ha utilizado "Postman v8.0.4". Documentación de SmartWebDoc: [[https://wiki.smartastur.com/doku.php?id=usu:smartweb:introduccion_a_smartwebdoc|Introducción a SmartWebDoc]]. === Envoltorio de la respuesta === Todos los procedimientos devuelven el mismo envoltorio JSON. Con la opción ''"metaData":true'', la respuesta incluye, además de los datos, la descripción de cada campo (tipo y etiqueta). A continuación se muestra un ejemplo completo con el procedimiento ''ALR_VEHICULOS_FLOTA''; el resto de procedimientos siguen la misma estructura, solo cambian los campos. == Cuerpo del POST == { "version" : "1.2", "metodo" : "Raw", "opciones" : { "metaData":true }, "comandos" : [ { "sql":"SELECT * FROM ALR_VEHICULOS_FLOTA(:fecha)", "params": { "fecha" : "2026-12-31"} } ] } == Respuesta (valores ilustrativos, campos abreviados) == { "version": "1.2", "resultados": [ { "estado": "OK", "metaData": { "S_ARTICULO": { "tipo": "ftString", "etiqueta": "S_ARTICULO" }, "S_NRO_SERIE": { "tipo": "ftString", "etiqueta": "S_NRO_SERIE" }, "S_DESCRIPCION": { "tipo": "ftString", "etiqueta": "S_DESCRIPCION" }, "S_STOCK": { "tipo": "ftFloat", "etiqueta": "S_STOCK" }, "S_NUMERO": { "tipo": "ftInteger", "etiqueta": "S_NUMERO" }, "S_DIESEL": { "tipo": "ftInteger", "etiqueta": "S_DIESEL" }, "S_TIPO_COMBUSTIBLE": { "tipo": "ftString", "etiqueta": "S_TIPO_COMBUSTIBLE" }, "S_COD_ACTIVO": { "tipo": "ftString", "etiqueta": "S_COD_ACTIVO" }, "S_PEGATINA_MEDIO": { "tipo": "ftString", "etiqueta": "S_PEGATINA_MEDIO" }, "S_FECHA_COMPRA": { "tipo": "ftDateTime","etiqueta": "S_FECHA_COMPRA" }, "S_NRO_POLIZA": { "tipo": "ftString", "etiqueta": "S_NRO_POLIZA" }, "S_SITUACION": { "tipo": "ftString", "etiqueta": "S_SITUACION" } }, "datos": [ { "S_ARTICULO": "VE00125", "S_NRO_SERIE": "1234ABC", "S_DESCRIPCION": "TURISMOS COMPACTOS", "S_STOCK": 1, "S_NUMERO": 1, "S_DIESEL": 1, "S_TIPO_COMBUSTIBLE": "DIESEL", "S_COD_ACTIVO": "AF001234", "S_PEGATINA_MEDIO": "C", "S_FECHA_COMPRA": "2024-03-15T00:00:00.000", "S_NRO_POLIZA": "P-0099887", "S_SITUACION": "ALMACEN CENTRAL" } ] } ] } Notas sobre la respuesta: - ''estado'' vale "OK" cuando el comando se ejecuta correctamente. - En ''metaData'', ''tipo'' es el tipo de dato de cada campo (''ftString'' para texto, un tipo numérico para importes y cantidades, un tipo fecha para las fechas). ''etiqueta'' es, por defecto, el propio nombre del campo. - ''datos'' es la lista de filas. Los campos vacíos se devuelven como ''null''. ---- ====== Notas generales de integración ====== Aspectos comunes a todos los conjuntos de datos: * **Alcance actual**: 1 conjunto de datos (//Flota de vehículos//). El documento se irá ampliando a medida que se incorporen nuevos procedimientos. * **Nomenclatura**: los procedimientos de esta integración se prefijan con la clave de instalación, ''ALR_''. Los campos de salida se prefijan con ''S_'' (//salida//) y los parámetros de entrada con ''P_''. * **Códigos de terceros**: los códigos de cliente, empleado, etc. se emiten sin prefijo de tipo (por ejemplo "027893", no "CL-027893"). * **Fechas**: se envían en formato ''aaaa-mm-dd'' (por ejemplo "2026-12-31") y se devuelven en formato ISO (''aaaa-mm-ddThh:mm:ss.zzz''). * **Consultas sobre el resultado**: al tratarse de procedimientos seleccionables, el cliente puede aplicar ''WHERE'', ''ORDER BY'', ''GROUP BY'' y funciones de agregación sobre su salida, sin necesidad de procedimientos adicionales. ---- ====== Conjunto de datos: Flota de vehículos ====== === Procedimiento === ALR_VEHICULOS_FLOTA === Parámetros === - P_FECHA_HASTA TIMESTAMP //(fecha de corte del informe)// === Resultados === - S_ARTICULO VARCHAR(10), - S_NRO_SERIE VARCHAR(20), - S_DESCRIPCION VARCHAR(60), - S_STOCK NUMERIC(17,5), - S_NUMERO INTEGER, - S_DIESEL INTEGER, - S_GASOLINA INTEGER, - S_GLP INTEGER, - S_GNC INTEGER, - S_ELECTRICO INTEGER, - S_MHEV_DIESEL INTEGER, - S_MHEV_GASOLINA INTEGER, - S_PHEV_DIESEL INTEGER, - S_PHEV_GASOLINA INTEGER, - S_HEV_GASOLINA INTEGER, - S_HEV_DIESEL INTEGER, - S_TIPO_COMBUSTIBLE VARCHAR(60), - S_COD_ACTIVO VARCHAR(10), - S_CON_COMBUSTIBLE INTEGER, - S_ERROR_NUMERO INTEGER, - S_PEGATINA_MEDIO VARCHAR(60), - S_FECHA_COMPRA TIMESTAMP, - S_NRO_POLIZA VARCHAR(20), - S_SITUACION VARCHAR(60) === Comportamiento === Devuelve la **flota de vehículos con existencias a la fecha ''P_FECHA_HASTA''**, con una fila por vehículo (combinación de artículo y número de serie), su clasificación por tipo de combustible y etiqueta medioambiental, y dónde se encuentra. Es el mismo informe que en SmartOffice se encuentra en //Gestión de flota → Informes → Flota de vehículos//. **Selección de las filas** El punto de partida es el estado de almacén a la fecha de corte, limitado a los artículos del **grupo estadístico de vehículos** definido para la instalación. Solo se emiten los vehículos con movimiento de existencias hasta esa fecha; cada fila agrupa por artículo, número de serie y descripción del grupo estadístico. //La fecha de corte afecta únicamente a las existencias.// El resto de los datos (situación, póliza, ficha técnica, fecha de compra) se toman del **estado actual** de la ficha del vehículo, no de su estado en la fecha solicitada. Es decir, ''P_FECHA_HASTA'' delimita qué vehículos aparecen y con cuánto stock, pero no reconstruye la situación histórica de cada uno. **Identificación del vehículo** * ''S_ARTICULO'': código del artículo (modelo de vehículo) en SMART. * ''S_NRO_SERIE'': número de serie del vehículo, que en la flota corresponde a la **matrícula**. * ''S_DESCRIPCION'': descripción del **grupo estadístico del activo** al que pertenece el vehículo (su categoría de flota), no la descripción del artículo. * ''S_COD_ACTIVO'': código del activo (ficha de inmovilizado / ficha de flota) correspondiente a ese número de serie. Es la clave que se debe usar para cruzar con otros conjuntos de datos. **Existencias y recuento** * ''S_STOCK'': existencias útiles del vehículo a la fecha de corte. Al tratarse de material identificado por número de serie, el valor normal es 1. * ''S_NUMERO'': número de registros de existencias agrupados en la fila. Lo normal es 1 por vehículo; un valor mayor indica que el mismo número de serie aparece en más de un registro de almacén. * ''S_ERROR_NUMERO'': diferencia entre ''S_NUMERO'' y ''S_CON_COMBUSTIBLE''. Es una marca de control de calidad: vale 0 cuando el vehículo tiene un único registro y un tipo de combustible reconocido, y distinto de 0 cuando falta el combustible en la ficha técnica, cuando su valor no es uno de los reconocidos, o cuando el número de serie está duplicado en almacén. **Clasificación por combustible** * ''S_TIPO_COMBUSTIBLE'': valor del campo ''COMBUSTIBL'' de la ficha técnica del activo. * ''S_DIESEL'', ''S_GASOLINA'', ''S_GLP'', ''S_GNC'', ''S_ELECTRICO'', ''S_MHEV_DIESEL'', ''S_MHEV_GASOLINA'', ''S_PHEV_DIESEL'', ''S_PHEV_GASOLINA'', ''S_HEV_GASOLINA'', ''S_HEV_DIESEL'': indicadores excluyentes del tipo de combustible, con valor 1 en la columna que corresponde al vehículo y 0 en el resto. Están desglosados en columnas para poder obtener el reparto de la flota por motorización con una sola consulta agregada (''SUM'' de cada columna), sin necesidad de pivotar el literal. * ''MHEV'' = híbrido ligero (//mild hybrid//), ''HEV'' = híbrido convencional, ''PHEV'' = híbrido enchufable, cada uno en su variante diésel o gasolina. * El indicador se activa por coincidencia **exacta** de ''S_TIPO_COMBUSTIBLE'' con uno de estos valores: ''DIESEL'', ''GASOLINA'', ''GLP'', ''GNC'', ''ELECTRICO'', ''MHEV DIESEL'', ''MHEV GASOLINA'', ''PHEV DIESEL'', ''PHEV GASOLINA'', ''HEV GASOLINA'', ''HEV DIESEL''. Cualquier otro valor deja todos los indicadores a 0. * ''S_CON_COMBUSTIBLE'': suma de los indicadores anteriores. Vale 1 cuando el vehículo tiene un tipo de combustible reconocido y 0 cuando no lo tiene o su valor no es reconocido. La suma de los indicadores solo cuadra con el total de la flota sobre las filas con ''S_CON_COMBUSTIBLE = 1''. * ''S_PEGATINA_MEDIO'': valor del campo ''PEGMED'' de la ficha técnica del activo, la etiqueta medioambiental de la DGT del vehículo. **Datos administrativos** * ''S_FECHA_COMPRA'': fecha de compra registrada en el activo. * ''S_NRO_POLIZA'': número de la póliza de seguro **vigente hoy** para ese activo. Se devuelve ''null'' si el vehículo no tiene póliza en vigor en el momento de la consulta. * ''S_SITUACION'': dónde está el vehículo según el movimiento de inventario pendiente. Si está entregado en un contrato de alquiler, se devuelve la **razón social del cliente** del contrato; en caso contrario, el **almacén** en el que se encuentra. Se devuelve ''null'' si el vehículo no tiene movimiento pendiente. //Nota: los campos sin dato en la ficha del vehículo se devuelven como ''null'' (o 0 en los campos indicadores).// === Ejemplos === == Flota completa a una fecha == { "version" : "1.2", "metodo" : "Raw", "opciones" : { "metaData":true }, "comandos" : [ { "sql":"SELECT * FROM ALR_VEHICULOS_FLOTA(:fecha) ORDER BY S_NRO_SERIE", "params": { "fecha" : "2026-12-31"} } ] } == Vehículos por situación (almacén o cliente en el que están) == { "version" : "1.2", "metodo" : "Raw", "opciones" : { "metaData":true }, "comandos" : [ { "sql":"SELECT S_SITUACION, SUM(S_STOCK) AS UNIDADES FROM ALR_VEHICULOS_FLOTA(:fecha) GROUP BY S_SITUACION ORDER BY 2 DESC", "params": { "fecha" : "2026-12-31"} } ] } == Vehículos de una categoría de flota concreta == { "version" : "1.2", "metodo" : "Raw", "opciones" : { "metaData":true }, "comandos" : [ { "sql":"SELECT * FROM ALR_VEHICULOS_FLOTA(:fecha) WHERE S_DESCRIPCION=:categoria ORDER BY S_NRO_SERIE", "params": { "fecha" : "2026-12-31", "categoria" : "TURISMOS COMPACTOS"} } ] } == Reparto de la flota por motorización == { "version" : "1.2", "metodo" : "Raw", "opciones" : { "metaData":true }, "comandos" : [ { "sql":"SELECT SUM(S_NUMERO) AS TOTAL, SUM(S_DIESEL) AS DIESEL, SUM(S_GASOLINA) AS GASOLINA, SUM(S_GLP) AS GLP, SUM(S_GNC) AS GNC, SUM(S_ELECTRICO) AS ELECTRICO, SUM(S_MHEV_DIESEL) AS MHEV_DIESEL, SUM(S_MHEV_GASOLINA) AS MHEV_GASOLINA, SUM(S_PHEV_DIESEL) AS PHEV_DIESEL, SUM(S_PHEV_GASOLINA) AS PHEV_GASOLINA, SUM(S_HEV_DIESEL) AS HEV_DIESEL, SUM(S_HEV_GASOLINA) AS HEV_GASOLINA FROM ALR_VEHICULOS_FLOTA(:fecha)", "params": { "fecha" : "2026-12-31"} } ] } == Reparto por etiqueta medioambiental == { "version" : "1.2", "metodo" : "Raw", "opciones" : { "metaData":true }, "comandos" : [ { "sql":"SELECT S_PEGATINA_MEDIO, SUM(S_NUMERO) AS UNIDADES FROM ALR_VEHICULOS_FLOTA(:fecha) GROUP BY S_PEGATINA_MEDIO ORDER BY 2 DESC", "params": { "fecha" : "2026-12-31"} } ] } == Control de calidad: vehículos sin combustible reconocido o con recuento incoherente == { "version" : "1.2", "metodo" : "Raw", "opciones" : { "metaData":true }, "comandos" : [ { "sql":"SELECT * FROM ALR_VEHICULOS_FLOTA(:fecha) WHERE S_CON_COMBUSTIBLE=0 OR S_ERROR_NUMERO<>0", "params": { "fecha" : "2026-12-31"} } ] } ---- == Registro de cambios del documento == --- //[[juanma@smartastur.com|Juanma]] 2026/09/08 // Puerto del servicio: 8001. Formato de fecha de los parámetros: ''aaaa-mm-dd''. --- //[[juanma@smartastur.com|Juanma]] 2026/08/10 // Flota de vehículos: precisiones sobre el alcance de la fecha de corte, la descripción (grupo estadístico) y los valores reconocidos de tipo de combustible. --- //[[juanma@smartastur.com|Juanma]] 2026/08/10 // Documento inicial. Integración SMART → DataLake para Alvemaco Rentacar (ALR): información general de acceso y conjunto de datos //Flota de vehículos// (''ALR_VEHICULOS_FLOTA'').