Instructivo de Apis de consulta de datos nativas

Calipso · Disponible a partir de la versión 3.04.212.

Referencia técnica: VLCCO-2428

1. ¿Qué son las APIs de consulta de datos nativas?

Calipso incorpora una ayuda integrada para consumir las APIs REST de vistas desde otros sistemas (Postman, Excel o un programa propio). Para cada vista, la ayuda muestra los datos de conexión, ejemplos listos para copiar y la descripción de sus columnas. Además, permite descargar la especificación OpenAPI para importarla en Postman o Swagger.

Las APIs disponibles son tres:

2. Requisitos

• Contar con la versión 3.04.212 o superior.

• Ser usuario administrador: la ayuda está restringida a administradores (se valida del lado del servidor).

• Tener permiso sobre la vista que se quiere consultar.

• Conocer la contraseña del usuario, que se envía en el header password y nunca se muestra en pantalla.

3. Ver la documentación de una vista

3.1. Abrir la ayuda

1. Ingresar a la vista que se quiere consultar (por ejemplo, Ventas › Administración de Ventas › Factura de Venta).

2. Hacer clic derecho sobre la vista para abrir la ventana Opciones.

3. En la categoría Edición XML, seleccionar Documentación de APIs REST.

Figura 1. Opción “Documentación de APIs REST” dentro de la categoría Edición XML.

3.2. Contenido de la ventana API REST

Se abre la ventana API de la vista, que incluye:

• Datos de conexión: URL base, usuario, instancia e ID exacto de la vista (dataViewId).

• Ejemplos `curl` listos para copiar, para leer los datos de la grilla y los registros completos.

• Ejemplo de filtro armado sobre una columna real de la vista, con los operadores disponibles.

• Columnas de la vista (nombre, título, tipo y si se puede filtrar) y atributos de la entidad.

Figura 2. Ventana API REST de la vista Factura de Venta.

3.3. Datos para conectarse

Cada llamada se autentica con el usuario, la contraseña y la instancia, que se envían en los headers:

Tip: copiá el dataViewId exactamente como figura en la ayuda, incluyendo las llaves y el nombre de la vista.

4. Leer los datos de la grilla

Devuelve las filas tal como se ven en la vista, de a 100 por página. pageNumber empieza en 0 y pageSize admite hasta 10000.

curl --location 'https://<servidor>/restcalipso/restservice/dataviews/query' \

  --header 'Content-Type: application/json' \

  --header 'username: <TU_USUARIO>' \

  --header 'password: <TU_CONTRASEÑA>' \

  --header 'instance: <INSTANCIA>' \

  --data '{

    "dataViewId": "{89C2350B-3F01-11D5-86AD-0080AD403F5F}Factura de Venta",

    "pageNumber": 0,

    "pageSize": 100

  }'

5. Leer los registros completos

Devuelve cada registro con todos los atributos de la entidad, como en la pantalla de edición. Para traer registros puntuales, agregar "rowIds": ["id1", "id2"] al body.

curl --location 'https://<servidor>/restcalipso/restservice/entities/query' \

  --header 'Content-Type: application/json' \

  --header 'username: <TU_USUARIO>' \

  --header 'password: <TU_CONTRASEÑA>' \

  --header 'instance: <INSTANCIA>' \

  --data '{

    "dataViewId": "{89C2350B-3F01-11D5-86AD-0080AD403F5F}Factura de Venta",

    "pageNumber": 0,

    "pageSize": 100

  }'

6. Cómo filtrar (solo en la grilla)

• Agregar filters al body de la llamada a dataviews/query.

• Cada filtro usa el nombre de la columna (no el título) y el tipo que figura en la tabla de columnas de la ayuda.

• Las fechas se informan con el formato yyyy-MM-dd (por ejemplo, 2026-01-31).

• La ayuda de cada vista trae un ejemplo de filtro armado sobre una columna real, con los operadores disponibles.

7. Descargar la especificación OpenAPI (Postman / Swagger)

El botón Descargar OpenAPI (Postman / Swagger) genera un archivo OpenAPI 3.0.3 que se importa directo en Postman. Los headers username, password e instance y el body de ejemplo ya vienen cargados.

7.1. Importar en Postman

1. En la ventana API REST, hacer clic en Descargar OpenAPI (Postman / Swagger).

2. En Postman, ir a Import › File y seleccionar el archivo descargado.

3. En la colección importada, crear la variable password con la contraseña del usuario. El usuario y la instancia ya vienen cargados.

4. Ejecutar la llamada deseada.

8. Documentación general desde el Admin Dashboard

Además de la ayuda por vista, existe una guía general de las tres APIs:

1. En el menú lateral, ingresar a Dashboards › Admin Dashboard.

2. En el Panel de Administración, dentro de Utilidades, hacer clic en Documentación de APIs REST.

Figura 3. Acceso a la Documentación de APIs REST desde el Panel de Administración.

La guía general explica:

• Cómo autenticarse.

• Qué significan los errores 400, 401 y 403.

• Un buscador de vistas que lleva a la ayuda de cada una.

9. Seguridad

• La ayuda queda restringida a administradores y se valida del lado del servidor, no solo ocultando el botón.

• Solo lee la definición de la vista: nunca ejecuta la vista ni lee datos de negocio.

• La contraseña no se muestra en ningún lado.

• Los atributos marcados como secretos no se documentan.

• No se agregaron librerías nuevas.