Smartwiki

Esta página es de solo lectura. Puedes ver la fuente pero no puedes cambiarla. Pregunta a tu administrador si crees que esto es incorrecto.
====== 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 <procedimiento>(...)'' 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 <procedimiento>(...)'' 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 ==
<code>
{
  "version"  : "1.2",
  "metodo"   : "Raw",
  "opciones" : { "metaData":true },
  "comandos" :
  [
    {
      "sql":"SELECT * FROM ALR_VEHICULOS_FLOTA(:fecha)",
      "params": { "fecha" : "2026-12-31"}
    }
  ]
}
</code>
== Respuesta (valores ilustrativos, campos abreviados) ==
<code>
{
    "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"
                }
            ]
        }
    ]
}
</code>

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 ==
<code>
{
  "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"}
    }
  ]
}
</code>
== Vehículos por situación (almacén o cliente en el que están) ==
<code>
{
  "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"}
    }
  ]
}
</code>
== Vehículos de una categoría de flota concreta ==
<code>
{
  "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"}
    }
  ]
}
</code>
== Reparto de la flota por motorización ==
<code>
{
  "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"}
    }
  ]
}
</code>
== Reparto por etiqueta medioambiental ==
<code>
{
  "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"}
    }
  ]
}
</code>
== Control de calidad: vehículos sin combustible reconocido o con recuento incoherente ==
<code>
{
  "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"}
    }
  ]
}
</code>

----

== 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'').