Integración
Consultar con OData
La base analítica se publica con OData v4, un estándar abierto que entienden Power BI, Excel y la mayoría de herramientas de análisis sin escribir una línea de código. Esta página es para quien quiere ir más allá y consultar directamente.
La dirección y el acceso#
Esofitec te entrega, al activar el módulo:
- La dirección del punto OData de tu base analítica.
- Un usuario y una contraseña propios del servicio, distintos de los de la aplicación.
El acceso es HTTPS y con autenticación básica. En los ejemplos, la dirección
aparece como BASE.
Es de solo lectura
El servicio no admite crear, modificar ni borrar. No es una restricción de permisos que se pueda ampliar: es el diseño. Para escribir está la API de s360.
Una credencial por consumidor
Si vais a conectar desde varios sitios —el Power BI corporativo, un análisis de un consultor externo—, pide una credencial por cada uno. Así se puede revocar una sin cortar las demás, y el registro de accesos dice quién ha leído qué.
Lo primero: qué hay publicado#
GET {BASE}/
Devuelve la lista de entidades disponibles. Y para el detalle de campos y tipos:
GET {BASE}/$metadata
El documento de metadatos es grande: no lo pidas en cada ejecución
Describe el modelo entero. Muchas bibliotecas lo descargan al conectar, y ese solo paso puede convertir un proceso de segundos en uno de minutos. Descárgalo una vez, guárdalo y renuévalo cuando cambie la versión de tu solución.
Leer una entidad#
GET {BASE}/PROYECTOS
Las opciones de consulta admitidas#
El servicio admite las opciones de lectura del estándar:
| Opción | Para qué sirve |
|---|---|
$select |
Traer solo los campos que necesitas |
$filter |
Acotar qué registros se devuelven |
$orderby |
Ordenar el resultado |
$top y $skip |
Paginar |
$count |
Obtener el número de registros |
$expand |
Traer entidades relacionadas en la misma llamada |
$apply |
Agrupar y agregar en el servidor |
$select: pide poco#
GET {BASE}/TAREAS?$select=ID,CODIGO,FECHA_INICIO,ID_PROYECTO,ID_ESTADO
Es la optimización que más se nota y la que más se olvida
Una entidad ancha con cincuenta campos, pedida entera para usar cinco, multiplica por diez el tráfico y el tiempo de recarga.
$filter: acota#
GET {BASE}/SERVICIOS_PARTE?$filter=FECHA ge 2026-01-01 and FECHA le 2026-12-31
GET {BASE}/CLIENTES?$filter=VIGENTE eq 1
GET {BASE}/PROYECTOS?$filter=ID_EMPRESA eq '5B7C…'
Operadores de comparación: eq, ne, gt, ge, lt, le. Lógicos: and, or,
not.
Las fechas van en formato ISO
2026-01-31, año-mes-día. Aquí no hay ambigüedad posible, a diferencia de lo que
ocurre integrando contra el sistema operativo.
Filtra siempre por empresa y por fecha
Son los dos filtros que más reducen el trabajo del servidor y los que evitan el error clásico de sumar registros de otra empresa.
$orderby, $top y $skip#
GET {BASE}/PARTES?$orderby=FECHA desc&$top=100
GET {BASE}/PARTES?$orderby=FECHA desc&$top=100&$skip=100
$count: contar sin descargar#
GET {BASE}/TAREAS?$count=true&$top=1
Pide siempre un elemento junto con el conteo
Si pides el conteo con $top=0, la respuesta puede venir con cero, aunque
haya miles de registros. Es un falso negativo silencioso: nada falla, simplemente
te informa de que no hay nada. Con $top=1 el conteo es correcto.
$expand: traer lo relacionado#
GET {BASE}/TAREAS?$expand=SERVICIOS_PARTE
Útil para explorar, peligroso para cargar
Para entender el modelo va bien. Para alimentar un cuadro de mando es preferible cargar las entidades por separado y relacionarlas en la herramienta: se paginan mejor y se refrescan de forma independiente.
$apply: agregar en el servidor#
GET {BASE}/SERVICIOS_PARTE?$apply=groupby((ID_PROYECTO),aggregate(HORAS with sum as TotalHoras))
Una sola transformación, no encadenadas
Se puede agrupar y agregar en una operación, pero no encadenar transformaciones sucesivas. Si necesitas varios niveles, haz varias consultas y combina en tu herramienta.
Cuando el detalle no importa, agrega en origen
Para una tarjeta de «horas del año por cliente» no hace falta traerse doscientas mil líneas de servicio: una consulta agregada devuelve treinta filas.
Errores y comportamiento#
- Las respuestas siguen el estándar OData; los errores llegan con su código HTTP y un cuerpo descriptivo.
- Un filtro que no encuentra nada devuelve una colección vacía, no un error.
- Si la dirección no responde, comprueba que el módulo esté activo y que la credencial sea la del servicio analítico y no la de la aplicación.
Buenos modales con el servicio#
- Una conexión cada vez. Varias extracciones simultáneas no van más rápido: compiten entre sí.
- Evita las horas de la ventana de actualización, que están en Actualizaciones: mientras se carga, las lecturas conviven con la escritura.
- Incremental siempre que puedas, filtrando por
MODIFICADOEL.
Qué viene después#
Conectar Power BI aplica todo esto sin escribir consultas a mano.