Referencia de la API REST

Histrix expone una API REST que permite operar todas las aplicaciones instaladas. Cada XML es un recurso: se lo puede consultar, insertar, modificar, borrar, exportar y además pedir su estructura (schema) para construir un cliente propio.

La API es autodescriptiva: recorriéndola desde /api/ con un navegador se obtienen los recursos disponibles en cada nivel.

Todas las rutas de datos requieren un token de acceso. Ver Autenticación y OIDC.

Convenciones

• La base de todas las rutas es /api. La base de datos se indica en la ruta: /api/db/{db}/...
• El token se envía en la cabecera Authorization: Bearer {token}.
• El formato de respuesta predeterminado es JSON. El parámetro requestFormat acepta application/json, application/xml y application/php.
• Las rutas que aceptan una ruta de XML la reciben como resto de la URL, con su directorio: app/contabilidad/man/ctbconceptos_crud.xml.

Descubrimiento

Método	Ruta	Descripción
GET	/api/	Recursos disponibles
GET	/api/info	Nombre y versión del framework y de la API
GET	/api/about	Información de la instalación
GET	/api/version	Versión del motor
GET/POST	/api/help	Parámetros aceptados
GET	/api/db	Bases disponibles
GET	/api/db/{db}	Recursos de la base
GET	/api/db/{db}/config	Configuración de la base

Ejemplo de /api/db:

{
  "cliente1": {
    "id": "cliente1",
    "name": "Cliente Uno",
    "description": "Base productiva"
  },
  "cliente2": {
    "id": "cliente2",
    "name": "Cliente Dos",
    "description": "Base de pruebas"
  }
}

Sesión y usuario

Método	Ruta	Descripción
GET/POST	/api/db/{db}/session	Inicia sesión de aplicación
DELETE	/api/session/	Cierra la sesión
GET	/api/db/{db}/me	Datos del usuario del token
GET	/api/db/{db}/users/	Usuarios de la base
POST	/api/db/{db}/location/	Registra la ubicación del usuario
POST	/api/db/{db}/change-password/	Cambia la contraseña
POST	/api/resetpassword/	Solicita el reseteo de contraseña

Menú y favoritos

Método	Ruta	Descripción
GET	/api/db/{db}/menu/[{id}]	Árbol de menú del usuario, o un ítem
PUT	/api/db/{db}/menu/security/{menuid}	Permisos del ítem de menú
GET	/api/db/{db}/favorites/	Favoritos del usuario
PUT	/api/db/{db}/favorites/	Guarda favoritos

curl --header "Authorization: Bearer $TOKEN" \
  https://servidor/api/db/cliente/menu/

{
  "description": "Nested Tree Menu",
  "parameters": { "id": "menu id" },
  "tree": [
    {
      "id": "274",
      "title": "CONTABILIDAD",
      "childs": [
        {
          "id": "21",
          "title": "PLAN DE CUENTAS",
          "uri": "/app/contabilidad/cuentas_tree.xml"
        }
      ]
    }
  ]
}

Precaución

Si tree viene vacío con HTTP 200, revisar parameters.login en la respuesta: un token válido pero sin usuario asociado devuelve un menú vacío sin error. El otro motivo habitual es que los ítems de HTXMENU no tengan web_version = 1.

Aplicaciones sin estado

Estas rutas operan directamente sobre un XML, sin crear una instancia persistente. Son las adecuadas para integraciones.

Método	Ruta	Descripción
OPTIONS	/api/db/{db}/app/{xml}	Estructura del contenedor
GET	/api/db/{db}/app/{xml}	Consulta datos
POST	/api/db/{db}/app/{xml}	Inserta
PUT	/api/db/{db}/app/{xml}	Modifica
DELETE	/api/db/{db}/app/{xml}	Borra
PATCH	/api/db/{db}/app/{xml}	Procesa un lote de registros
GET	/api/db/{db}/schema/{xml}	Schema en formato de cliente
GET	/api/db/{db}/schema/field/{field}/{xml}	Schema de un campo
GET	/api/db/{db}/nodes/{xml}	Nodos de un XML tipo árbol
GET	/api/db/{db}/export/{formato}/{xml}	Exporta
GET	/api/db/{db}/export/pdf/{xml}	Genera el PDF
GET	/api/db/{db}/print/{xml}	Imprime
GET/POST	/api/db/{db}/pdf/{xml}	Genera el PDF
GET/POST	/api/db/{db}/json/{instance}	Datos en formato DataTables

OPTIONS: estructura del contenedor

curl --header "Authorization: Bearer $TOKEN" \
  -X OPTIONS https://servidor/api/db/cliente/app/general/iva_crud.xml

{
  "resources": {
    "GET": "Get Data",
    "OPTIONS": "App Info",
    "EXPORT": "Export Data",
    "POST": "insert Data",
    "PUT": "Update Data",
    "DELETE": "Delete Data"
  },
  "dataContainer": {
    "titulo": "Categorias de IVA",
    "tipo": "abm",
    "TablaBase": "GEN_IVA",
    "tablas": {
      "GEN_IVA": {
        "nombreTabla": "GEN_IVA",
        "campos": {
          "id_iva": {
            "NombreCampo": "id_iva",
            "Etiqueta": "código",
            "TipoDato": "varchar",
            "autoinc": "true",
            "noshow": "true"
          }
        }
      }
    }
  }
}

OPTIONS devuelve la representación interna completa del contenedor. Para construir un cliente conviene usar /schema/{xml}, que entrega una versión normalizada y estable: tipos, etiquetas, estilos (form_style, label_style), opciones de combos, parámetros de los helpers de tipo link, configuración de paginación (page_size, max_limit) y el indicador preFetch.

Nota

Un cliente propio debe respetar preFetch: cuando es false el formulario arranca vacío y no corresponde pedir datos. Los campos de trabajo de una grilla que no son columnas de la tabla necesitan local="true" en el XML; sin eso, el GET falla con error 1054 de columna desconocida.

GET: consulta

curl --header "Authorization: Bearer $TOKEN" \
  -X GET https://servidor/api/db/cliente/app/general/iva_crud.xml

{
  "data": [
    { "id_iva": "1", "abreviacion_iva": "R.Insc.", "nombre_iva": "Responsable Inscripto", "letra": "A" },
    { "id_iva": "3", "abreviacion_iva": "Exe", "nombre_iva": "Exento", "letra": "B" }
  ]
}

Filtro por campo. Cualquier campo declarado en el XML se puede pasar como parámetro de query:

curl --header "Authorization: Bearer $TOKEN" \
  "https://servidor/api/db/cliente/app/general/iva_crud.xml?id_iva=1"

Límite simple. _limit fija la cantidad de registros; _limit=0 elimina los límites preestablecidos en el XML. Para recorrer un resultado largo conviene la paginación, que se describe más abajo:

curl --header "Authorization: Bearer $TOKEN" \
  "https://servidor/api/db/cliente/app/general/iva_crud.xml?_limit=3"

Rangos y operadores. Se combinan tres arreglos paralelos:

_f[]  campo
_o[]  operador (=, !=, >=, <=, like)
_v[]  valor

curl --header "Authorization: Bearer $TOKEN" \
  "https://servidor/api/db/cliente/app/general/iva_crud.xml?_f[]=id_iva&_o[]=>=&_v[]=3&_f[]=id_iva&_o[]=<&_v[]=5"

Paginación

GET /app/{xml} acepta dos estilos de paginación, y los dos se traducen internamente a LIMIT/OFFSET:

Estilo	Parámetros	Ejemplo
Desplazamiento	limit, offset	?limit=20&offset=40
Página	page, page_size	?page=3&page_size=20

Cuando llegan los dos, page/page_size tiene prioridad sobre limit/offset. Si no llega ninguno se usa el default del XML: el atributo limit= —o paginar=— del <histrix>.

La paginación es opcional. Si no hay parámetros por query y el XML tampoco define un límite, la respuesta es la de siempre: {"data": [...]} con todas las filas y sin bloque pagination. Un cliente que ya funcionaba no cambia.

curl --header "Authorization: Bearer $TOKEN" \
  "https://servidor/api/db/cliente/app/ventas/qry/ventas_qry.xml?limit=2"

{
  "data": [
    { "id_venta": "1", "cliente": "ACME", "total": "1500.00" },
    { "id_venta": "2", "cliente": "Otra S.A.", "total": "2300.00" }
  ],
  "pagination": {
    "limit": 2,
    "offset": 0,
    "count": 2,
    "has_more": true,
    "next": "https://servidor/api/db/cliente/app/ventas/qry/ventas_qry.xml?limit=2&offset=2"
  }
}

El bloque pagination trae:

Campo	Contenido
limit	Filas por página efectivamente aplicadas
offset	Filas salteadas
count	Filas devueltas en esta página
has_more	Si hay más resultados
next	URL completa de la página siguiente, o null si no hay más
page, page_size	Solo en el estilo por página
total, total_pages	Solo si se pidió with_total

Recorrer todo el resultado es seguir next hasta que venga null. La URL ya conserva los filtros y el orden del pedido original, así que no hay que rearmar el query:

url="https://servidor/api/db/cliente/app/ventas/qry/ventas_qry.xml?limit=100&cliente=ACME"
while [ -n "$url" ] && [ "$url" != "null" ]; do
  page=$(curl -s --header "Authorization: Bearer $TOKEN" "$url")
  echo "$page" | jq '.data[]'
  url=$(echo "$page" | jq -r '.pagination.next // ""')
done

Total exacto. Contar el total cuesta una consulta más, así que no se hace salvo que se pida con with_total=1 (o with_total=true). Con eso la respuesta agrega total y total_pages:

curl --header "Authorization: Bearer $TOKEN" \
  "https://servidor/api/db/cliente/app/ventas/qry/ventas_qry.xml?page=1&page_size=50&with_total=1"

"pagination": {
  "limit": 50, "offset": 0, "count": 50,
  "page": 1, "page_size": 50,
  "total": 213, "total_pages": 5,
  "has_more": true,
  "next": "https://servidor/api/db/cliente/app/ventas/qry/ventas_qry.xml?page=2&page_size=50&with_total=1"
}

Precaución

Sin with_total, has_more es una inferencia: vale true cuando la página vino llena, es decir cuando la cantidad de filas devueltas llega al limit pedido. Si el total es múltiplo exacto del tamaño de página, la última página devuelve has_more: true y un next que responde con cero filas. Recorrer hasta que data venga vacío —o pedir with_total=1, que vuelve el dato exacto— resuelve el caso.

Tope. El máximo es de 200 filas por página. Un limit o un page_size mayor no falla: se recorta a 200, y el valor aplicado es el que informa pagination.limit.

Conocer el tamaño de página antes de pedir datos. El schema del XML lo expone, para que un cliente no tenga que inferirlo a fuerza de requests:

curl --header "Authorization: Bearer $TOKEN" \
  "https://servidor/api/db/cliente/schema/ventas/qry/ventas_qry.xml"

"pagination": { "enabled": true, "page_size": 100, "offset": 0, "max_limit": 200 }

Nota

La paginación no se aplica a las peticiones en modo DataTables (_dt), que usan su propio mecanismo con start, length y recordsTotal. Tampoco reemplaza a _limit, que sigue funcionando como límite simple sin bloque pagination.

POST: inserción

El cuerpo lleva en data un arreglo JSON de objetos campo/valor:

curl --header "Authorization: Bearer $TOKEN" -X POST \
  -d 'data=[{"nombre_iva": "TEST", "letra": "X"}]' \
  https://servidor/api/db/cliente/app/general/iva_crud.xml

PUT: modificación

Además de data, se envía keys con los campos que identifican el registro:

curl --header "Authorization: Bearer $TOKEN" -X PUT \
  -d 'data=[{"nombre_iva": "TEST 2"}]' \
  -d 'keys=[{"id_iva": 7}]' \
  https://servidor/api/db/cliente/app/general/iva_crud.xml

DELETE: borrado

curl --header "Authorization: Bearer $TOKEN" -X DELETE \
  -d 'keys=[{"id_iva": 7}]' \
  https://servidor/api/db/cliente/app/general/iva_crud.xml

PATCH: proceso por lote

Ejecuta la lógica de grabación del XML —incluidos sus movimientos— sobre un arreglo de registros:

curl --header "Authorization: Bearer $TOKEN" -X PATCH \
  -d 'jsonData=[{"clave": "valor"}, {"clave": "otro valor"}]' \
  https://servidor/api/db/cliente/app/general/iva_crud.xml

Instancias

Una instancia es un contenedor vivo en la sesión: mantiene filtros, campos calculados y filas temporales. Es el modelo que usa la interfaz web y el necesario para reproducir formularios de ingreso con grillas.

Método	Ruta	Descripción
GET/POST	/api/db/{db}/instance/xml/{xml}	Crea la instancia
GET	/api/db/{db}/instance/{instance}	Lee datos
PUT	/api/db/{db}/instance/{instance}	Actualiza datos
DELETE	/api/db/{db}/instance/{instance}	Destruye la instancia
DELETE	/api/db/{db}/instances/	Destruye varias instancias
PUT	/api/db/{db}/instance/{instance}/set/[{id}]	Actualiza un campo
POST	/api/db/{db}/instance/{instance}/field/{field}/	Refresca un campo
PUT	/api/db/{db}/instance/{instance}/field/{field}/	Asigna valor a un campo
POST	/api/db/{db}/{instance}/fields/{source}/	Refresca los campos dependientes de uno
POST	/api/db/{db}/instance/{instance}/filter/	Aplica filtros
GET	/api/db/{db}/instance/{instance}/page/{page}	Página de resultados
GET	/api/db/{db}/instance/{instance}/refresh/	Refresca la vista
PUT	/api/db/{db}/instance/{instance}/table/	Graba filas de la grilla
PUT	/api/db/{db}/instance/{instance}/data/[{row}]	Actualiza una fila
DELETE	/api/db/{db}/instance/{instance}/data/[{row}]	Borra una fila
PUT	/api/db/{db}/instance/{instance}/row/[{row}]	Refresca una fila
PUT	/api/db/{db}/instance/{instance}/order/	Reordena
PUT	/api/db/{db}/instance/{instance}/swap/{origen}/{destino}	Intercambia filas
POST	/api/db/{db}/instance/{instance}/process/[{vars}]	Ejecuta la grabación
PUT	/api/db/{db}/instance/{instance}/reset/	Reinicia los datos
GET	/api/db/{db}/instance/{instance}/tree/	Vista de árbol
GET	/api/db/{db}/instance/{instance}/nodes/	Nodos del árbol
GET	/api/db/{db}/instance/{instance}/events/	Eventos de calendario
GET	/api/db/{db}/instance/{instance}/print/	PDF de la instancia
GET	/api/db/{db}/instance/{instance}/debug/	Estado del contenedor
DELETE	/api/db/{db}/instance/{instance}/debug/	Cancela la consulta en curso

Ayudas y autocompletado

Los popups de ayuda y los autocompletados de un campo se sirven desde la instancia del formulario padre, no pidiendo el XML de la ayuda por separado:

GET  /api/db/{db}/instance/{instance}/field/{field}/help/    autocompletado
POST /api/db/{db}/instance/{instance}/field/{field}/help/    grilla de ayuda

Esa ruta aplica las condiciones que el padre le impone al helper. Pedir el XML de la ayuda por app/ ignora esas condiciones y suele devolver cero filas.

Seguridad por registro y por campo

Método	Ruta	Descripción
GET	/api/db/{db}/metadata/{instance}/{id}	Seguridad del registro
GET	/api/db/{db}/instance/{instance}/privacy/[{rowid}]	Formulario de privacidad
PUT	/api/db/{db}/instance/{instance}/privacy/{rowid}	Cambia la privacidad
GET	/api/db/{db}/instance/{instance}/field/{field}/security/	Permisos del campo
PUT	/api/db/{db}/instance/{instance}/field/{field}/security/	Actualiza permisos

Exportación e importación

Método	Ruta	Descripción
GET	/api/db/{db}/instance/{instance}/export/	Formulario de exportación
GET	/api/db/{db}/instance/{instance}/export/{formato}/	Exporta en el momento
GET	/api/db/{db}/instance/{instance}/export/start/{formato}/	Encola la exportación
GET	/api/db/{db}/export-job/status/{jobId}	Estado del trabajo
GET	/api/db/{db}/export-job/download/{jobId}	Descarga el resultado
GET	/api/db/{db}/instance/{instance}/import/	Formulario de importación
PUT	/api/db/{db}/instance/{instance}/import/	Guarda la importación
POST	/api/db/{db}/instance/{instance}/import/{path}	Importa un archivo

Las exportaciones grandes se resuelven de forma asíncrona: export/start/{formato}/ devuelve un jobId que se consulta con export-job/status/{jobId} hasta que termina y luego se descarga con export-job/download/{jobId}. Ver Exportación de datos.

Archivos

Método	Ruta	Descripción
GET	/api/db/{db}/dir[/{ruta}]	Contenido de un directorio
GET	/api/db/{db}/files/{archivo}	Descarga
POST	/api/db/{db}/files/{archivo}	Subida
DELETE	/api/db/{db}/files/{archivo}	Borrado
GET	/api/db/{db}/thumb[/{ruta}]	Miniatura
GET	/api/db/{db}/view[/{ruta}]	Visor
PUT	/api/db/{db}/save/{xml}	Guarda el archivo XML (editor)
GET	/api/db/{db}/barcode	Genera un código de barras

Subida de un archivo:

curl --header "Authorization: Bearer $TOKEN" \
  -F "file=@perfil.jpg;filename=perfil.jpg;type=image/jpeg" \
  https://servidor/api/db/cliente/files/clientes/perfil.jpg

El backend de archivos puede ser local o S3. Cuando es S3, el tag <path> del montaje actúa como prefijo raíz, lo que permite que varias bases compartan un bucket separadas por subdirectorio.

Impresión

Método	Ruta	Descripción
GET	/api/db/{db}/print/file/{id}	Descarga el trabajo de impresión
POST	/api/db/{db}/print/done/{id}	Marca el trabajo como impreso
POST	/api/db/{db}/print/error/{id}	Marca el trabajo con error
GET	/api/qztray/sign	Firma para QZ Tray
GET	/api/qztray/cert	Certificado de QZ Tray

La impresión directa a impresoras locales (térmicas, fiscales, etiquetas) se hace a través de QZ Tray: el navegador pide la firma al servidor y envía el trabajo a la impresora.

Configuración y parámetros

Método	Ruta	Descripción
GET	/api/db/{db}/settings/[{sección}]	Lee la configuración
PUT	/api/db/{db}/settings/[{sección}]	Actualiza la configuración
POST	/api/db/{db}/settings/[{sección}]	Crea una opción
GET	/api/db/{db}/useroption/{clave}	Opción del usuario
POST	/api/db/{db}/useroption/{clave}	Guarda opción del usuario
DELETE	/api/db/{db}/useroption/{clave}	Borra opción del usuario
GET	/api/db/{db}/parameters/panel/{xmlPath}	Panel de parámetros
PUT	/api/db/{db}/parameters/	Guarda parámetros
GET	/api/db/{db}/parameters/values	Valores de los parámetros

Tareas programadas y autoinicio

Método	Ruta	Descripción
GET/POST/PUT/DELETE	/api/db/{db}/crontab/[{id}]	Tareas programadas
GET/POST/PUT/DELETE	/api/db/{db}/autoinit/[{id}]	Programas de autoinicio
GET/POST	/api/db/{db}/sysmon/	Monitor del sistema
GET	/api/db/{db}/tasks/	Tareas del usuario

Mensajería y notificaciones

Método	Ruta	Descripción
GET	/api/db/{db}/user/notifications/	Notificaciones
DELETE	/api/db/{db}/user/notifications/	Borra todas
GET	/api/db/{db}/user/notifications/config	Configuración
PUT	/api/db/{db}/user/notifications/config	Guarda configuración
GET	/api/db/{db}/user/messages/	Mensajes
POST	/api/db/{db}/user/message/[{id}]	Envía un mensaje
DELETE	/api/db/{db}/user/message/{id}	Borra un mensaje
GET	/api/db/{db}/mail/	Correo del usuario
GET	/api/db/{db}/sendmail/[{instance}]	Formulario de envío

Assets y etiquetas

Método	Ruta	Descripción
GET	/api/js/{db}	Bundle de JavaScript
GET	/api/css/{db}	Bundle de CSS
GET	/api/images/{imagen}	Imagen del tema
GET	/api/db/{db}/tags/{grupo}[/{tag}]	Lee etiquetas
POST	/api/db/{db}/tags/{grupo}[/{tag}]	Asigna etiquetas

Recursos públicos

Método	Ruta	Descripción
GET	/api/db/{db}/pub/[{token}]	Recurso público por token
GET	/api/db/{db}/encuesta/{token}	Encuesta
POST	/api/db/{db}/encuesta/{token}	Respuesta de la encuesta
GET/POST	/api/db/{db}/registration/	Registro de usuarios
POST	/api/db/{db}/confirm-registration/	Confirma el registro

Cualquier XML ubicado bajo xml/public/ se sirve sin token. Es el mecanismo para publicar galerías, catálogos o endpoints de lectura hacia afuera; conviene combinarlo con un dataSource que controle exactamente qué devuelve.

Precaución

Los endpoints de descubrimiento OIDC viven en /api/db/{db}/.well-known/..., es decir fuera de la raíz del sitio. Varios proxies bloquean por defecto .well-known cuando no está en la raíz y responden 403. Si el discovery falla con 403, revisar la configuración del proxy antes que la de Histrix.